org.apache.ojb.broker
Interface PersistenceBroker

All Superinterfaces:
org.apache.ojb.broker.util.configuration.Configurable, ObjectContainer
All Known Implementing Classes:
DelegatingPersistenceBroker, PersistenceBrokerAbstractImpl, PersistenceBrokerBean

public interface PersistenceBroker
extends org.apache.ojb.broker.util.configuration.Configurable, ObjectContainer

PersistenceBroker declares a protocol for persisting arbitrary objects. A typical implementation might wrap an RDBMS access layer.

Version:
$Id: PersistenceBroker.java,v 1.27 2003/07/16 11:19:32 arminw Exp $
Author:
Thomas Mahler
See Also:
PersistenceBrokerImpl, PersistenceBrokerBean

Method Summary
 void abortTransaction()
          Abort and close the transaction.
 void addListener(PBListener listener)
          Adds a temporary PBListener to this PersistenceBroker instance - when PersistenceBroker.close() was called the listener was removed.
 void addListener(PBListener listener, boolean permanent)
          Adds a permanent PBListener to this PersistenceBroker instance if parameter permanent was true.
 void addMtoNImplementor(MtoNImplementor m2nImpl)
           
 void beginTransaction()
          Begin a transaction against the underlying RDBMS.
 void clearCache()
          clears the brokers internal cache.
 boolean close()
          Close this PersistenceBroker so that no further requests may be made on it.
 void commitTransaction()
          Commit and close the transaction.
 void delete(java.lang.Object obj)
          deletes the objects obj concrete representation in the underlying persistence system.
 void deleteByQuery(Query query)
          Deletes all objects matching the query from the underlying persistence system.
 void deleteMtoNImplementor(MtoNImplementor m2nImpl)
          Deletes and MtoN implementor (a row on a indirection table) As it is today, ojb doesn't handle collection inherence, so collections descriptors are written per class.
 void fireBrokerEvent(PBLifeCycleEvent event)
          Performs a broker event to inform all managed PBListener implementations.
 void fireBrokerEvent(PBStateEvent event)
          Performs a broker event to inform all managed PBListener implementations.
 void fireBrokerEvent(PersistenceBrokerEvent event)
          Performs a broker event to inform all managed PBListener implementations.
 ClassDescriptor getClassDescriptor(java.lang.Class clazz)
          returns a ClassDescriptor for the persistence capable class clazz.
 ManageableCollection getCollectionByQuery(java.lang.Class collectionClass, Query query)
          Retrieve a userdefined Collection that implements the interface Manageable collection that contains all Objects matching the Query query.
 java.util.Collection getCollectionByQuery(Query query)
          Retrieve a collection of itemClass Objects matching the Query query.
 int getCount(Query query)
          Returns the count of elements a given query will return.
 DescriptorRepository getDescriptorRepository()
          Returns the DescriptorRepository associated with this broker.
 java.util.Iterator getIteratorByQuery(Query query)
          returns an Iterator that iterates Objects of class c if calling the .next() method.
 java.lang.Object getObjectByIdentity(Identity id)
          Retrieve an Object by its Identity.
 java.lang.Object getObjectByQuery(Query query)
          Retrieve an Object by query.
 PBKey getPBKey()
          Get the PBKey for this broker.
 java.util.Enumeration getPKEnumerationByQuery(java.lang.Class PrimaryKeyClass, Query query)
          Returns an Enumeration of PrimaryKey Objects for objects of class DataClass.
 java.util.Iterator getReportQueryIteratorByQuery(Query query)
          Returns an Iterator that iterates Object[] calling the .next() method.
 java.lang.Class getTopLevelClass(java.lang.Class clazz)
          Returns the top level (extent) class to which the given class belongs.
 boolean hasClassDescriptor(java.lang.Class clazz)
          same as getClassDescriptor, but does not throw.
 boolean isClosed()
           
 boolean isInTransaction()
          Returns true if the broker performs a transaction, false in the other case
 void removeAllListeners()
          Removes all temporary listeners from this PersistenceBroker instance - Handle with care!
 void removeAllListeners(boolean permanent)
          If parameter permanet was true all permanent and temporary listeners will be removed from this PersistenceBroker instance.
 void removeFromCache(java.lang.Object obj)
          Removes the object from the brokers internal cache.
 void removeListener(PBListener listener)
          Removes a listener from this PersistenceBroker instance
 void retrieveAllReferences(java.lang.Object pInstance)
          Retrieve all Reference- and Collection-attributes of a given instance
 void retrieveReference(java.lang.Object pInstance, java.lang.String pAttributeName)
          retrieve a single reference- or collection attribute of a persistent instance.
 org.apache.ojb.broker.util.BrokerHelper serviceBrokerHelper()
          Returns the BrokerHelper instance associated with this broker.
 org.apache.ojb.broker.accesslayer.ConnectionManagerIF serviceConnectionManager()
          Returns the ConnectionManagerIF instance associated with this broker.
 org.apache.ojb.broker.accesslayer.JdbcAccess serviceJdbcAccess()
          Returns the JdbcAccess instance associated with this broker.
 org.apache.ojb.broker.cache.ObjectCache serviceObjectCache()
          Returns the ObjectCache instance associated with this broker.
 SequenceManager serviceSequenceManager()
          Returns the SequenceManager instance associated with this broker.
 org.apache.ojb.broker.accesslayer.sql.SqlGenerator serviceSqlGenerator()
          Returns the SqlGenerator instance associated with this broker.
 org.apache.ojb.broker.accesslayer.StatementManagerIF serviceStatementManager()
          Returns the StatementManagerIF instance associated with this broker.
 void store(java.lang.Object obj)
          make object obj persistent in the underlying persistence system.
 void store(java.lang.Object obj, org.apache.ojb.broker.util.ObjectModification modification)
          makes object obj persistent in the underlying persistence system.
 
Methods inherited from interface org.apache.ojb.broker.util.configuration.Configurable
configure
 
Methods inherited from interface org.odbms.ObjectContainer
query
 

Method Detail

serviceStatementManager

public org.apache.ojb.broker.accesslayer.StatementManagerIF serviceStatementManager()
Returns the StatementManagerIF instance associated with this broker.


serviceConnectionManager

public org.apache.ojb.broker.accesslayer.ConnectionManagerIF serviceConnectionManager()
Returns the ConnectionManagerIF instance associated with this broker.


serviceSqlGenerator

public org.apache.ojb.broker.accesslayer.sql.SqlGenerator serviceSqlGenerator()
Returns the SqlGenerator instance associated with this broker.


serviceJdbcAccess

public org.apache.ojb.broker.accesslayer.JdbcAccess serviceJdbcAccess()
Returns the JdbcAccess instance associated with this broker.


serviceSequenceManager

public SequenceManager serviceSequenceManager()
Returns the SequenceManager instance associated with this broker.


serviceBrokerHelper

public org.apache.ojb.broker.util.BrokerHelper serviceBrokerHelper()
Returns the BrokerHelper instance associated with this broker. Makes some helper methods available.


serviceObjectCache

public org.apache.ojb.broker.cache.ObjectCache serviceObjectCache()
Returns the ObjectCache instance associated with this broker.


fireBrokerEvent

public void fireBrokerEvent(PersistenceBrokerEvent event)
Performs a broker event to inform all managed PBListener implementations.


fireBrokerEvent

public void fireBrokerEvent(PBLifeCycleEvent event)
Performs a broker event to inform all managed PBListener implementations.


fireBrokerEvent

public void fireBrokerEvent(PBStateEvent event)
Performs a broker event to inform all managed PBListener implementations.


removeAllListeners

public void removeAllListeners()
                        throws PersistenceBrokerException
Removes all temporary listeners from this PersistenceBroker instance - Handle with care!

Throws:
PersistenceBrokerException

removeAllListeners

public void removeAllListeners(boolean permanent)
                        throws PersistenceBrokerException
If parameter permanet was true all permanent and temporary listeners will be removed from this PersistenceBroker instance.
NOTE: Handle with care!

Throws:
PersistenceBrokerException
See Also:
removeListener(PBListener listener)

addListener

public void addListener(PBListener listener)
                 throws PersistenceBrokerException
Adds a temporary PBListener to this PersistenceBroker instance - when PersistenceBroker.close() was called the listener was removed.

Parameters:
listener - The listener to add
Throws:
PersistenceBrokerException
See Also:
addListener(org.apache.ojb.broker.PBListener listener, boolean permanent)

addListener

public void addListener(PBListener listener,
                        boolean permanent)
                 throws PersistenceBrokerException
Adds a permanent PBListener to this PersistenceBroker instance if parameter permanent was true. This means the listener will be hold the whole life time of the broker.
NOTE: Handle carefully when using this method, keep in mind you don't know which instance was returned next time from the pool, with a permanent listener or without! To garantee that any pooled broker instance use the permanent listener, best way is to implement your own PersistenceBrokerFactoryIF or extend the default implementation PersistenceBrokerFactoryDefaultImpl and add the listener at creation of the PersistenceBroker instances.

Throws:
PersistenceBrokerException

removeListener

public void removeListener(PBListener listener)
                    throws PersistenceBrokerException
Removes a listener from this PersistenceBroker instance

Parameters:
listener -
Throws:
PersistenceBrokerException

abortTransaction

public void abortTransaction()
                      throws TransactionNotInProgressException
Abort and close the transaction. Calling abort abandons all persistent object modifications and releases the associated locks.
If transaction is not in progress a TransactionNotInProgressException is thrown

Throws:
TransactionNotInProgressException

beginTransaction

public void beginTransaction()
                      throws TransactionInProgressException,
                             TransactionAbortedException
Begin a transaction against the underlying RDBMS. Calling beginTransaction multiple times, without an intervening call to commitTransaction or abortTransaction, causes the exception TransactionInProgressException to be thrown on the second and subsequent calls.

Throws:
TransactionInProgressException
TransactionAbortedException

commitTransaction

public void commitTransaction()
                       throws TransactionNotInProgressException,
                              TransactionAbortedException
Commit and close the transaction. Calling commit commits to the database all UPDATE, INSERT and DELETE statements called within the transaction and releases any locks held by the transaction. If beginTransaction() has not been called before a TransactionNotInProgressException exception is thrown. If the transaction cannot be commited a TransactionAbortedException exception is thrown.

Throws:
TransactionNotInProgressException
TransactionAbortedException

isInTransaction

public boolean isInTransaction()
                        throws PersistenceBrokerException
Returns true if the broker performs a transaction, false in the other case

Throws:
PersistenceBrokerException

close

public boolean close()
Close this PersistenceBroker so that no further requests may be made on it. A PersistenceBroker instance can be used only until it is closed. Closing a PersistenceBroker might release it to the pool of available PersistenceBrokers, or might be garbage collected, at the option of the implementation.

Returns:
true if successful

isClosed

public boolean isClosed()

getDescriptorRepository

public DescriptorRepository getDescriptorRepository()
Returns the DescriptorRepository associated with this broker.


getPBKey

public PBKey getPBKey()
Get the PBKey for this broker.


getClassDescriptor

public ClassDescriptor getClassDescriptor(java.lang.Class clazz)
                                   throws PersistenceBrokerException
returns a ClassDescriptor for the persistence capable class clazz. throws a PersistenceBrokerException if clazz is not persistence capable, i.e. if clazz is not defined in the DescriptorRepository.

Throws:
PersistenceBrokerException

hasClassDescriptor

public boolean hasClassDescriptor(java.lang.Class clazz)
same as getClassDescriptor, but does not throw. Useful for checking if an object is persistence Capable.

Parameters:
clazz -
Returns:
true if descriptor was found

getTopLevelClass

public java.lang.Class getTopLevelClass(java.lang.Class clazz)
                                 throws PersistenceBrokerException
Returns the top level (extent) class to which the given class belongs. This may be a (abstract) base-class, an interface or the given class itself, if no extent is defined.

Throws:
PersistenceBrokerException - if clazz is not persistence capable, i.e. if clazz is not defined in the DescriptorRepository.

clearCache

public void clearCache()
                throws PersistenceBrokerException
clears the brokers internal cache. removing is recursive. That is referenced Objects are also removed from the cache, if the auto-retrieve flag is set for obj.getClass() in the metadata repository.

Throws:
PersistenceBrokerException

removeFromCache

public void removeFromCache(java.lang.Object obj)
                     throws PersistenceBrokerException
Removes the object from the brokers internal cache. If object is instance of Identity, the associated object was removed from cache.
Removing is not recursive.

Throws:
PersistenceBrokerException

store

public void store(java.lang.Object obj,
                  org.apache.ojb.broker.util.ObjectModification modification)
           throws PersistenceBrokerException
makes object obj persistent in the underlying persistence system. E.G. by INSERT INTO ... or UPDATE ... in an RDBMS. The ObjectModification parameter can be used to generate optimized SQL code (decide whether insert or update is needed. And for updates only generate code for modified columns)

Throws:
PersistenceBrokerException

store

public void store(java.lang.Object obj)
           throws PersistenceBrokerException
make object obj persistent in the underlying persistence system. E.G. by INSERT INTO ... or UPDATE ... in an RDBMS

Throws:
PersistenceBrokerException

delete

public void delete(java.lang.Object obj)
            throws PersistenceBrokerException
deletes the objects obj concrete representation in the underlying persistence system. E.G. by DELETE FROM ... WHERE ... in an RDBMS

Throws:
PersistenceBrokerException

deleteMtoNImplementor

public void deleteMtoNImplementor(MtoNImplementor m2nImpl)
                           throws PersistenceBrokerException
Deletes and MtoN implementor (a row on a indirection table) As it is today, ojb doesn't handle collection inherence, so collections descriptors are written per class. We try to match one of these collection descriptors, iterating from the left side and looking for possible for classes on the right side using : collection descriptor element . isAssinableFrom(rightClass) TODO: handle cache problems TODO: delete more than one row if possible Pre-coditions :
  • Pos-coditions :
  • Assertions :
  • Parameters:
    m2nImpl -
    Throws:
    PersistenceBrokerException - if an error occours

    addMtoNImplementor

    public void addMtoNImplementor(MtoNImplementor m2nImpl)
                            throws PersistenceBrokerException
    Throws:
    PersistenceBrokerException

    deleteByQuery

    public void deleteByQuery(Query query)
                       throws PersistenceBrokerException
    Deletes all objects matching the query from the underlying persistence system. E.G. by DELETE FROM ... WHERE ... in an RDBMS

    Throws:
    PersistenceBrokerException

    retrieveAllReferences

    public void retrieveAllReferences(java.lang.Object pInstance)
                               throws PersistenceBrokerException
    Retrieve all Reference- and Collection-attributes of a given instance

    Parameters:
    pInstance - the persistent instance
    Throws:
    PersistenceBrokerException

    retrieveReference

    public void retrieveReference(java.lang.Object pInstance,
                                  java.lang.String pAttributeName)
                           throws PersistenceBrokerException
    retrieve a single reference- or collection attribute of a persistent instance.

    Parameters:
    pInstance - the persistent instance
    pAttributeName - the name of the Attribute to load
    Throws:
    PersistenceBrokerException

    getCount

    public int getCount(Query query)
                 throws PersistenceBrokerException
    Returns the count of elements a given query will return.

    Throws:
    PersistenceBrokerException

    getCollectionByQuery

    public java.util.Collection getCollectionByQuery(Query query)
                                              throws PersistenceBrokerException
    Retrieve a collection of itemClass Objects matching the Query query. If the Query has no criteria no WHERE-clause is generated, i.e. ALL table rows are selected.

    Throws:
    PersistenceBrokerException

    getCollectionByQuery

    public ManageableCollection getCollectionByQuery(java.lang.Class collectionClass,
                                                     Query query)
                                              throws PersistenceBrokerException
    Retrieve a userdefined Collection that implements the interface Manageable collection that contains all Objects matching the Query query.
    If query has no criteria no WHERE-clause is generated, i.e. ALL table rows are selected.

    Throws:
    PersistenceBrokerException

    getIteratorByQuery

    public java.util.Iterator getIteratorByQuery(Query query)
                                          throws PersistenceBrokerException
    returns an Iterator that iterates Objects of class c if calling the .next() method. The Elements returned come from a SELECT ... WHERE Statement that is defined by the Query query. If itemProxy is null, no proxies are used.

    Throws:
    PersistenceBrokerException

    getReportQueryIteratorByQuery

    public java.util.Iterator getReportQueryIteratorByQuery(Query query)
                                                     throws PersistenceBrokerException
    Returns an Iterator that iterates Object[] calling the .next() method. The Elements returned come from a SELECT ... WHERE sqlStatement The Class c is only used to provide the associated JDBC Connection

    Throws:
    PersistenceBrokerException

    getObjectByIdentity

    public java.lang.Object getObjectByIdentity(Identity id)
                                         throws PersistenceBrokerException
    Retrieve an Object by its Identity. Application Developers are encouraged to use getObjectByQuery(). This method is mainly used for internal performant handling of materialization by OID (e.g. in Proxies)

    Throws:
    PersistenceBrokerException

    getObjectByQuery

    public java.lang.Object getObjectByQuery(Query query)
                                      throws PersistenceBrokerException
    Retrieve an Object by query. I.e perform a SELECT ... FROM ... WHERE ... in an RDBMS

    Throws:
    PersistenceBrokerException

    getPKEnumerationByQuery

    public java.util.Enumeration getPKEnumerationByQuery(java.lang.Class PrimaryKeyClass,
                                                         Query query)
                                                  throws PersistenceBrokerException
    Returns an Enumeration of PrimaryKey Objects for objects of class DataClass. The Elements returned come from a SELECT ... WHERE Statement that is defined by the fields and their coresponding values of vecFields and vecValues. Useful for EJB Finder Methods... NOT YET AWARE OF EXTENTS !

    Parameters:
    PrimaryKeyClass - the pk class for the searched objects
    query - the query
    Throws:
    PersistenceBrokerException


    Authors: Thomas Mahler and others. (C) 2000 - 2003 Apache Software Foundation
    All rights reserved. Published under the Apache License.
    http://db.apache.org/ojb
    Version: 1.0.rc5, 2003-12-14