org.apache.ojb.broker.core
Class DelegatingPersistenceBroker

java.lang.Object
  extended byorg.apache.ojb.broker.core.DelegatingPersistenceBroker
All Implemented Interfaces:
org.apache.ojb.broker.util.configuration.Configurable, ObjectContainer, PBState, PersistenceBroker
Direct Known Subclasses:
PersistenceBrokerHandle, PoolablePersistenceBroker

public class DelegatingPersistenceBroker
extends java.lang.Object
implements PersistenceBroker, PBState

Delegating implementation of a PersistenceBroker

Author:
Armin Waibel

Constructor Summary
DelegatingPersistenceBroker(PersistenceBroker broker)
           
 
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 configure(org.apache.ojb.broker.util.configuration.Configuration pConfig)
           
 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.
 PersistenceBroker getDelegate()
          Returns only the wrapped PersistenceBroker instance
 DescriptorRepository getDescriptorRepository()
          Returns the DescriptorRepository associated with this broker.
 PersistenceBroker getInnermostDelegate()
          If my underlying PersistenceBroker is not a DelegatingPersistenceBroker, returns it, otherwise recursively invokes this method on my delegate.
 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
 Query query()
          factory method to create a new Query object.
 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 setClosed(boolean closed)
           
 void setDelegate(PersistenceBroker 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 class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DelegatingPersistenceBroker

public DelegatingPersistenceBroker(PersistenceBroker broker)
Method Detail

getDelegate

public PersistenceBroker getDelegate()
Returns only the wrapped PersistenceBroker instance


setDelegate

public void setDelegate(PersistenceBroker broker)

getInnermostDelegate

public PersistenceBroker getInnermostDelegate()
If my underlying PersistenceBroker is not a DelegatingPersistenceBroker, returns it, otherwise recursively invokes this method on my delegate.

Hence this method will return the first delegate that is not a DelegatingPersistenceBroker, or null when no non-DelegatingPersistenceBroker delegate can be found by transversing this chain.

This method is useful when you may have nested DelegatingPersistenceBrokers, and you want to make sure to obtain a "genuine" PersistenceBroker implementaion instance.


isInTransaction

public boolean isInTransaction()
                        throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
Returns true if the broker performs a transaction, false in the other case

Specified by:
isInTransaction in interface PersistenceBroker
Throws:
PersistenceBrokerException

isClosed

public boolean isClosed()
Specified by:
isClosed in interface PersistenceBroker

setClosed

public void setClosed(boolean closed)
Specified by:
setClosed in interface PBState

beginTransaction

public void beginTransaction()
                      throws TransactionInProgressException,
                             TransactionAbortedException
Description copied from interface: PersistenceBroker
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.

Specified by:
beginTransaction in interface PersistenceBroker
Throws:
TransactionInProgressException
TransactionAbortedException

commitTransaction

public void commitTransaction()
                       throws TransactionNotInProgressException,
                              TransactionAbortedException
Description copied from interface: PersistenceBroker
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.

Specified by:
commitTransaction in interface PersistenceBroker
Throws:
TransactionNotInProgressException
TransactionAbortedException

abortTransaction

public void abortTransaction()
                      throws TransactionNotInProgressException
Description copied from interface: PersistenceBroker
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

Specified by:
abortTransaction in interface PersistenceBroker
Throws:
TransactionNotInProgressException

close

public boolean close()
Description copied from interface: PersistenceBroker
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.

Specified by:
close in interface PersistenceBroker
Returns:
true if successful

serviceSqlGenerator

public org.apache.ojb.broker.accesslayer.sql.SqlGenerator serviceSqlGenerator()
Description copied from interface: PersistenceBroker
Returns the SqlGenerator instance associated with this broker.

Specified by:
serviceSqlGenerator in interface PersistenceBroker

serviceJdbcAccess

public org.apache.ojb.broker.accesslayer.JdbcAccess serviceJdbcAccess()
Description copied from interface: PersistenceBroker
Returns the JdbcAccess instance associated with this broker.

Specified by:
serviceJdbcAccess in interface PersistenceBroker

delete

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

Specified by:
delete in interface PersistenceBroker
Throws:
PersistenceBrokerException

store

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

Specified by:
store in interface PersistenceBroker
Throws:
PersistenceBrokerException

store

public void store(java.lang.Object obj,
                  org.apache.ojb.broker.util.ObjectModification modification)
           throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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)

Specified by:
store in interface PersistenceBroker
Throws:
PersistenceBrokerException

getPBKey

public PBKey getPBKey()
Description copied from interface: PersistenceBroker
Get the PBKey for this broker.

Specified by:
getPBKey in interface PersistenceBroker

removeFromCache

public void removeFromCache(java.lang.Object obj)
                     throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
removeFromCache in interface PersistenceBroker
Throws:
PersistenceBrokerException

clearCache

public void clearCache()
                throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
clearCache in interface PersistenceBroker
Throws:
PersistenceBrokerException

getDescriptorRepository

public DescriptorRepository getDescriptorRepository()
Description copied from interface: PersistenceBroker
Returns the DescriptorRepository associated with this broker.

Specified by:
getDescriptorRepository in interface PersistenceBroker

removeAllListeners

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

Specified by:
removeAllListeners in interface PersistenceBroker
Throws:
PersistenceBrokerException

removeAllListeners

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

Specified by:
removeAllListeners in interface PersistenceBroker
Throws:
PersistenceBrokerException
See Also:
PersistenceBroker.removeListener(PBListener listener)

retrieveReference

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

Specified by:
retrieveReference in interface PersistenceBroker
Parameters:
pInstance - the persistent instance
pAttributeName - the name of the Attribute to load
Throws:
PersistenceBrokerException

retrieveAllReferences

public void retrieveAllReferences(java.lang.Object pInstance)
                           throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
Retrieve all Reference- and Collection-attributes of a given instance

Specified by:
retrieveAllReferences in interface PersistenceBroker
Parameters:
pInstance - the persistent instance
Throws:
PersistenceBrokerException

serviceConnectionManager

public org.apache.ojb.broker.accesslayer.ConnectionManagerIF serviceConnectionManager()
Description copied from interface: PersistenceBroker
Returns the ConnectionManagerIF instance associated with this broker.

Specified by:
serviceConnectionManager in interface PersistenceBroker

serviceStatementManager

public org.apache.ojb.broker.accesslayer.StatementManagerIF serviceStatementManager()
Description copied from interface: PersistenceBroker
Returns the StatementManagerIF instance associated with this broker.

Specified by:
serviceStatementManager in interface PersistenceBroker

serviceSequenceManager

public SequenceManager serviceSequenceManager()
Description copied from interface: PersistenceBroker
Returns the SequenceManager instance associated with this broker.

Specified by:
serviceSequenceManager in interface PersistenceBroker

serviceBrokerHelper

public org.apache.ojb.broker.util.BrokerHelper serviceBrokerHelper()
Description copied from interface: PersistenceBroker
Returns the BrokerHelper instance associated with this broker. Makes some helper methods available.

Specified by:
serviceBrokerHelper in interface PersistenceBroker

serviceObjectCache

public org.apache.ojb.broker.cache.ObjectCache serviceObjectCache()
Description copied from interface: PersistenceBroker
Returns the ObjectCache instance associated with this broker.

Specified by:
serviceObjectCache in interface PersistenceBroker

fireBrokerEvent

public void fireBrokerEvent(PersistenceBrokerEvent event)
Description copied from interface: PersistenceBroker
Performs a broker event to inform all managed PBListener implementations.

Specified by:
fireBrokerEvent in interface PersistenceBroker

fireBrokerEvent

public void fireBrokerEvent(PBLifeCycleEvent event)
Description copied from interface: PersistenceBroker
Performs a broker event to inform all managed PBListener implementations.

Specified by:
fireBrokerEvent in interface PersistenceBroker

fireBrokerEvent

public void fireBrokerEvent(PBStateEvent event)
Description copied from interface: PersistenceBroker
Performs a broker event to inform all managed PBListener implementations.

Specified by:
fireBrokerEvent in interface PersistenceBroker

addListener

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

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

addListener

public void addListener(PBListener listener,
                        boolean permanent)
                 throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
addListener in interface PersistenceBroker
Throws:
PersistenceBrokerException

removeListener

public void removeListener(PBListener listener)
                    throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
Removes a listener from this PersistenceBroker instance

Specified by:
removeListener in interface PersistenceBroker
Parameters:
listener -
Throws:
PersistenceBrokerException

getTopLevelClass

public java.lang.Class getTopLevelClass(java.lang.Class clazz)
                                 throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
getTopLevelClass in interface PersistenceBroker
Throws:
PersistenceBrokerException - if clazz is not persistence capable, i.e. if clazz is not defined in the DescriptorRepository.

hasClassDescriptor

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

Specified by:
hasClassDescriptor in interface PersistenceBroker
Parameters:
clazz -
Returns:
true if descriptor was found

getClassDescriptor

public ClassDescriptor getClassDescriptor(java.lang.Class clazz)
                                   throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
getClassDescriptor in interface PersistenceBroker
Throws:
PersistenceBrokerException

getPKEnumerationByQuery

public java.util.Enumeration getPKEnumerationByQuery(java.lang.Class primaryKeyClass,
                                                     Query query)
                                              throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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 !

Specified by:
getPKEnumerationByQuery in interface PersistenceBroker
Parameters:
primaryKeyClass - the pk class for the searched objects
query - the query
Throws:
PersistenceBrokerException

getObjectByQuery

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

Specified by:
getObjectByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

getObjectByIdentity

public java.lang.Object getObjectByIdentity(Identity id)
                                     throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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)

Specified by:
getObjectByIdentity in interface PersistenceBroker
Throws:
PersistenceBrokerException

getReportQueryIteratorByQuery

public java.util.Iterator getReportQueryIteratorByQuery(Query query)
                                                 throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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

Specified by:
getReportQueryIteratorByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

getIteratorByQuery

public java.util.Iterator getIteratorByQuery(Query query)
                                      throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
getIteratorByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

getCollectionByQuery

public ManageableCollection getCollectionByQuery(java.lang.Class collectionClass,
                                                 Query query)
                                          throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
getCollectionByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

getCount

public int getCount(Query query)
             throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
Returns the count of elements a given query will return.

Specified by:
getCount in interface PersistenceBroker
Throws:
PersistenceBrokerException

getCollectionByQuery

public java.util.Collection getCollectionByQuery(Query query)
                                          throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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.

Specified by:
getCollectionByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

configure

public void configure(org.apache.ojb.broker.util.configuration.Configuration pConfig)
               throws org.apache.ojb.broker.util.configuration.ConfigurationException
Specified by:
configure in interface org.apache.ojb.broker.util.configuration.Configurable
Throws:
org.apache.ojb.broker.util.configuration.ConfigurationException

query

public Query query()
Description copied from interface: ObjectContainer
factory method to create a new Query object.

Specified by:
query in interface ObjectContainer
Returns:
a new Query object

deleteByQuery

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

Specified by:
deleteByQuery in interface PersistenceBroker
Throws:
PersistenceBrokerException

deleteMtoNImplementor

public void deleteMtoNImplementor(MtoNImplementor m2nImpl)
                           throws PersistenceBrokerException
Description copied from interface: PersistenceBroker
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 :
  • Specified by:
    deleteMtoNImplementor in interface PersistenceBroker
    Parameters:
    m2nImpl -
    Throws:
    PersistenceBrokerException - if an error occours
    See Also:
    PersistenceBroker.deleteMtoNImplementor(org.apache.ojb.broker.MtoNImplementor)

    addMtoNImplementor

    public void addMtoNImplementor(MtoNImplementor m2nImpl)
                            throws PersistenceBrokerException
    Specified by:
    addMtoNImplementor in interface PersistenceBroker
    Throws:
    PersistenceBrokerException
    See Also:
    PersistenceBroker.addMtoNImplementor(org.apache.ojb.broker.MtoNImplementor)


    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