org.apache.ojb.broker
Interface PersistenceBroker

All Superinterfaces:

org.apache.ojb.broker.util.configuration.Configurable, ObjectContainer

All Known Subinterfaces:

PersistenceBrokerInternal

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 365239 2005-12-22 20:40:17Z tomdz $

Author:

Thomas Mahler

See Also:

PersistenceBrokerImpl, PersistenceBrokerBean

Method Summary

void	abortTransaction() Aborts and closes the current transaction.
void	addListener(PBListener listener) Adds a temporary PBListener to this broker.
void	addListener(PBListener listener, boolean permanent) Adds a temporary or permanent PBListener to this broker, depending on the parameter value.
void	addMtoNImplementor(MtoNImplementor m2nImpl) Stores the given m:n implementor int the underlying persistence system.
void	beginTransaction() Begins a transaction against the underlying RDBMS.
void	clearCache() Clears the broker's internal cache.
boolean	close() Closes this broker so that no further requests may be made on it.
void	commitTransaction() Commits and closes the current transaction.
void	delete(java.lang.Object obj) Deletes the given object's persistent representation in the underlying persistence system.
void	deleteByQuery(Query query) Deletes all objects matching the given query, from the underlying persistence system.
void	deleteMtoNImplementor(MtoNImplementor m2nImpl) Deletes an m:n implementor which defines the relationship between two persistent objects.
void	fireBrokerEvent(PBLifeCycleEvent event) Fires a life cycle event to inform all registered PBListener instances.
void	fireBrokerEvent(PBStateEvent event) Fires a state event to inform all registered PBListener instances.
void	fireBrokerEvent(PersistenceBrokerEvent event) Fires a broker event to inform all registered PBListener instances.
ClassDescriptor	getClassDescriptor(java.lang.Class clazz) Returns the class descriptor for the given persistence capable class.
ManageableCollection	getCollectionByQuery(java.lang.Class collectionClass, Query query) Retrieves the persistent objects matching the given query.
java.util.Collection	getCollectionByQuery(Query query) Retrieves the persistent objects matching the given query.
int	getCount(Query query) Returns the number of elements that the given query will return.
DescriptorRepository	getDescriptorRepository() Returns the metadata descriptor repository associated with this broker.
java.util.Iterator	getIteratorByQuery(Query query) Retrieves the persistent objects matching the given query and returns them as an iterator which may, depending on the configured collection type, be reloading the objects from the database upon calling Iterator.next().
java.lang.Object	getObjectByIdentity(Identity id) Retrieve a persistent object from the underlying datastore by its identity.
java.lang.Object	getObjectByQuery(Query query) Retrieve the (first) persistent object from the underlying datastore that matches the given query.
PBKey	getPBKey() Get the PBKey for this broker.
java.util.Enumeration	getPKEnumerationByQuery(java.lang.Class pkClass, Query query) Returns an enumeration of objects representing the primary keys for the objects that match the given query.
java.util.Iterator	getReportQueryIteratorByQuery(Query query) Retrieves the rows (as Object[] instances) matching the given query and returns them as an iterator which may, depending on the configured collection type, be reloading the objects from the database upon calling Iterator.next().
java.lang.Class	getTopLevelClass(java.lang.Class clazz) Returns the top level class (most abstract class in terms of extents) from which the given class extends.
boolean	hasClassDescriptor(java.lang.Class clazz) Determines whether the given class is persistence capable and thus has an associated class descriptor in the metadata.
boolean	isClosed() Determines whether this broker is closed.
boolean	isInTransaction() Determines whether there is currently a transaction in progress.
void	removeAllListeners() Removes all temporary listeners from this broker.
void	removeAllListeners(boolean permanent) Removes all temporary and, if desired, permanent listeners from this broker.
void	removeFromCache(java.lang.Object objectOrIdentity) Removes the given object or, if it is an instance of Identity, the object identified by it, from the broker's internal cache.
void	removeListener(PBListener listener) Removes the specified listener from this broker.
void	retrieveAllReferences(java.lang.Object obj) Retrieve all references and collections of the given object irrespective of the metadata settings defined for them.
void	retrieveReference(java.lang.Object obj, java.lang.String attrName) Retrieve the specified reference or collection attribute for the given persistent object.
BrokerHelper	serviceBrokerHelper() Returns the BrokerHelper instance associated with this broker, which makes some additional helper methods available.
ConnectionManagerIF	serviceConnectionManager() Returns the ConnectionManagerIF instance associated with this broker.
IdentityFactory	serviceIdentity() Return the IdentityFactory instance associated with this broker.
JdbcAccess	serviceJdbcAccess() Returns the JdbcAccess instance associated with this broker.
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.
StatementManagerIF	serviceStatementManager() Returns the StatementManagerIF instance associated with this broker.
void	store(java.lang.Object obj) Make the given object persistent in the underlying persistence system.
void	store(java.lang.Object obj, ObjectModification modification) Makes the given object 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 StatementManagerIF serviceStatementManager()

Returns the StatementManagerIF instance associated with this broker.

Returns:

The statement manager

serviceConnectionManager

public ConnectionManagerIF serviceConnectionManager()

Returns the ConnectionManagerIF instance associated with this broker.

Returns:

The connection manager

serviceSqlGenerator

public org.apache.ojb.broker.accesslayer.sql.SqlGenerator serviceSqlGenerator()

Returns the SqlGenerator instance associated with this broker.

Returns:

The SQL generator

serviceJdbcAccess

public JdbcAccess serviceJdbcAccess()

Returns the JdbcAccess instance associated with this broker.

Returns:

The JDBC access object

serviceSequenceManager

public SequenceManager serviceSequenceManager()

Returns the SequenceManager instance associated with this broker.

Returns:

The sequence manager

serviceBrokerHelper

public BrokerHelper serviceBrokerHelper()

Returns the BrokerHelper instance associated with this broker, which makes some additional helper methods available.

Returns:

The broker helper object

serviceObjectCache

public ObjectCache serviceObjectCache()

Returns the ObjectCache instance associated with this broker.

Returns:

The object cache

serviceIdentity

public IdentityFactory serviceIdentity()

Return the IdentityFactory instance associated with this broker.

Returns:

The identity factory

fireBrokerEvent

public void fireBrokerEvent(PersistenceBrokerEvent event)

Fires a broker event to inform all registered PBListener instances.

Parameters:

event - The event to fire

fireBrokerEvent

public void fireBrokerEvent(PBLifeCycleEvent event)

Fires a life cycle event to inform all registered PBListener instances.

Parameters:

event - The event to fire

fireBrokerEvent

public void fireBrokerEvent(PBStateEvent event)

Fires a state event to inform all registered PBListener instances.

Parameters:

event - The event to fire

removeAllListeners

public void removeAllListeners()
                        throws PersistenceBrokerException

Removes all temporary listeners from this broker. Use with care, because some internals rely on this mechanism.

Throws:

PersistenceBrokerException

See Also:

removeListener(PBListener)

removeAllListeners

public void removeAllListeners(boolean permanent)
                        throws PersistenceBrokerException

Removes all temporary and, if desired, permanent listeners from this broker. Use with care, because some internals rely on this mechanism.

Parameters:

permanent - Whether the listener will stay registered after closing the broker

Throws:

PersistenceBrokerException

See Also:

removeListener(PBListener)

addListener

public void addListener(PBListener listener)
                 throws PersistenceBrokerException

Adds a temporary PBListener to this broker. Note that temporary listeners will be removed upon closing a broker (returning it to the pool).

Parameters:

listener - The listener to add

Throws:

PersistenceBrokerException

See Also:

addListener(PBListener, boolean)

addListener

public void addListener(PBListener listener,
                        boolean permanent)
                 throws PersistenceBrokerException

Adds a temporary or permanent PBListener to this broker, depending on the parameter value. Note that temporary listeners will be removed upon closing a broker (returning it to the pool).
NOTE: Handle carefully when using this method, keep in mind you don't know which broker instance will be returned next time from the pool! To guarantee that a listener is connect to every broker, the best way is to define your own implementation of PersistenceBrokerFactoryIF or extend the default one, PersistenceBrokerFactoryDefaultImpl. There you can add the listener at creation of the PersistenceBroker instances.

Parameters:

listener - The listener to add

permanent - Whether the listener will stay registered after closing the broker

Throws:

PersistenceBrokerException

removeListener

public void removeListener(PBListener listener)
                    throws PersistenceBrokerException

Removes the specified listener from this broker.

Parameters:

listener - The listener to remove

Throws:

PersistenceBrokerException

abortTransaction

public void abortTransaction()
                      throws TransactionNotInProgressException

Aborts and closes the current transaction. This abandons all persistent object modifications and releases the associated locks.

Throws:

TransactionNotInProgressException - If no transaction is currently in progress

beginTransaction

public void beginTransaction()
                      throws TransactionInProgressException,
                             TransactionAbortedException

Begins a transaction against the underlying RDBMS.

Throws:

TransactionInProgressException - If there is already a transaction in progress

TransactionAbortedException

commitTransaction

public void commitTransaction()
                       throws TransactionNotInProgressException,
                              TransactionAbortedException

Commits and closes the current transaction. This commits all database-changing statements (e.g. UPDATE, INSERT and DELETE) issued within the transaction since the last commit to the database, and releases any locks held by the transaction.

Throws:

TransactionNotInProgressException - If there is no transaction currently in progress

TransactionAbortedException - If the transaction cannot be committed

isInTransaction

public boolean isInTransaction()
                        throws PersistenceBrokerException

Determines whether there is currently a transaction in progress.

Returns:

true if there is a transaction in progress

Throws:

PersistenceBrokerException

close

public boolean close()

Closes this broker so that no further requests may be made on it. Closing a broker might release it to the pool of available brokers, or might be garbage collected, at the option of the implementation.

Returns:

true if the broker was successfully closed

isClosed

public boolean isClosed()

Determines whether this broker is closed.

Returns:

true if this instance is closed

getDescriptorRepository

public DescriptorRepository getDescriptorRepository()

Returns the metadata descriptor repository associated with this broker.

Returns:

The descriptor repository

getPBKey

public PBKey getPBKey()

Get the PBKey for this broker.

Returns:

The broker key

getClassDescriptor

public ClassDescriptor getClassDescriptor(java.lang.Class clazz)
                                   throws PersistenceBrokerException

Returns the class descriptor for the given persistence capable class.

Parameters:

clazz - The target class

Returns:

The class descriptor

Throws:

PersistenceBrokerException - If the class is not persistence capable, i.e. if no metadata was defined for this class and hence its class descriptor was not found

hasClassDescriptor

public boolean hasClassDescriptor(java.lang.Class clazz)

Determines whether the given class is persistence capable and thus has an associated class descriptor in the metadata.

Parameters:

clazz - The target class

Returns:

true if a class descriptor was found

getTopLevelClass

public java.lang.Class getTopLevelClass(java.lang.Class clazz)
                                 throws PersistenceBrokerException

Returns the top level class (most abstract class in terms of extents) from which the given class extends. This may be a (abstract) base-class, an interface or the given class itself, if no extent is defined.

Parameters:

clazz - The class to get the top level class for

Returns:

The top level class for it

Throws:

PersistenceBrokerException - If the class is not persistence capable, if no metadata was defined for this class

clearCache

public void clearCache()
                throws PersistenceBrokerException

Clears the broker's internal cache.

Throws:

PersistenceBrokerException

removeFromCache

public void removeFromCache(java.lang.Object objectOrIdentity)
                     throws PersistenceBrokerException

Removes the given object or, if it is an instance of Identity, the object identified by it, from the broker's internal cache. Note that the removal is not recursive. This means, objects referenced by the removed object will not be automatically removed from the cache by this operation.

Parameters:

objectOrIdentity - The object to be removed from the cache or its identity

Throws:

PersistenceBrokerException

store

public void store(java.lang.Object obj,
                  ObjectModification modification)
           throws PersistenceBrokerException

Makes the given object persistent in the underlying persistence system. This is usually done by issuing an INSERT ... or UPDATE ... in an RDBMS.

Parameters:

obj - The object to store

modification - Specifies what operation to perform (for generating optimized SQL)

Throws:

PersistenceBrokerException

store

public void store(java.lang.Object obj)
           throws PersistenceBrokerException

Make the given object persistent in the underlying persistence system. This is usually done by issuing an INSERT ... or UPDATE ... in an RDBMS.

Parameters:

obj - The object to store

Throws:

PersistenceBrokerException

delete

public void delete(java.lang.Object obj)
            throws PersistenceBrokerException

Deletes the given object's persistent representation in the underlying persistence system. This is usually done by issuing a DELETE ... in an RDBMS

Parameters:

obj - The object to delete

Throws:

PersistenceBrokerException

deleteMtoNImplementor

public void deleteMtoNImplementor(MtoNImplementor m2nImpl)
                           throws PersistenceBrokerException

Deletes an m:n implementor which defines the relationship between two persistent objects. This is usually a row in an indirection table.
Note that OJB currently doesn't handle collection inheritance, 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 isAssignableFrom(rightClass). TODO: handle cache problems TODO: delete more than one row if possible

Parameters:

m2nImpl - The m:n implementor to delete

Throws:

PersistenceBrokerException

addMtoNImplementor

public void addMtoNImplementor(MtoNImplementor m2nImpl)
                        throws PersistenceBrokerException

Stores the given m:n implementor int the underlying persistence system. This is usually done by inserting a row in an indirection table.
Note that OJB currently doesn't handle collection inheritance, 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 isAssignableFrom(rightClass).

Parameters:

m2nImpl - The m:n implementor to delete

Throws:

PersistenceBrokerException

deleteByQuery

public void deleteByQuery(Query query)
                   throws PersistenceBrokerException

Deletes all objects matching the given query, from the underlying persistence system. This is usually done via DELETE ... in an RDBMS.
Note: This method directly perform the delete statement ignoring any object references and does not synchronize the cache - take care!

Parameters:

query - The query determining the objects to delete

Throws:

PersistenceBrokerException

retrieveAllReferences

public void retrieveAllReferences(java.lang.Object obj)
                           throws PersistenceBrokerException

Retrieve all references and collections of the given object irrespective of the metadata settings defined for them.

Parameters:

obj - The persistent object

Throws:

PersistenceBrokerException

retrieveReference

public void retrieveReference(java.lang.Object obj,
                              java.lang.String attrName)
                       throws PersistenceBrokerException

Retrieve the specified reference or collection attribute for the given persistent object.

Parameters:

obj - The persistent object

attrName - The name of the attribute to retrieve

Throws:

PersistenceBrokerException

getCount

public int getCount(Query query)
             throws PersistenceBrokerException

Returns the number of elements that the given query will return.

Parameters:

query - The query

Returns:

The number of elements returned by the query

Throws:

PersistenceBrokerException

getCollectionByQuery

public java.util.Collection getCollectionByQuery(Query query)
                                          throws PersistenceBrokerException

Retrieves the persistent objects matching the given query. Note that if the Query has no criteria ALL persistent objects of the class targeted by the query will be returned.

Parameters:

query - The query

Returns:

The persistent objects matching the query

Throws:

PersistenceBrokerException

getCollectionByQuery

public ManageableCollection getCollectionByQuery(java.lang.Class collectionClass,
                                                 Query query)
                                          throws PersistenceBrokerException

Retrieves the persistent objects matching the given query. The resulting collection will be of the supplied collection type. Note that if the Query has no criteria ALL persistent objects of the class targeted by the query will be returned.

Parameters:

collectionClass - The collection type which needs to implement ManageableCollection

query - The query

Returns:

The persistent objects matching the query

Throws:

PersistenceBrokerException

getIteratorByQuery

public java.util.Iterator getIteratorByQuery(Query query)
                                      throws PersistenceBrokerException

Retrieves the persistent objects matching the given query and returns them as an iterator which may, depending on the configured collection type, be reloading the objects from the database upon calling Iterator.next(). Note that if the Query has no criteria ALL persistent objects of the class targeted by the query will be returned.

Parameters:

query - The query

Returns:

The persistent objects matching the query

Throws:

PersistenceBrokerException

getReportQueryIteratorByQuery

public java.util.Iterator getReportQueryIteratorByQuery(Query query)
                                                 throws PersistenceBrokerException

Retrieves the rows (as Object[] instances) matching the given query and returns them as an iterator which may, depending on the configured collection type, be reloading the objects from the database upon calling Iterator.next().

Parameters:

query - The report query

Returns:

The rows matching the query

Throws:

PersistenceBrokerException

getObjectByIdentity

public java.lang.Object getObjectByIdentity(Identity id)
                                     throws PersistenceBrokerException

Retrieve a persistent object from the underlying datastore by its identity. However, users are encouraged to use getObjectByQuery(Query) instead, as this method is mainly intended to be used for internal handling of materialization by OID (e.g. in Proxies).

Parameters:

id - The persistent object's id

Returns:

The persistent object

Throws:

PersistenceBrokerException

getObjectByQuery

public java.lang.Object getObjectByQuery(Query query)
                                  throws PersistenceBrokerException

Retrieve the (first) persistent object from the underlying datastore that matches the given query.

Parameters:

query - The query

Returns:

The persistent object

Throws:

PersistenceBrokerException

getPKEnumerationByQuery

public java.util.Enumeration getPKEnumerationByQuery(java.lang.Class pkClass,
                                                     Query query)
                                              throws PersistenceBrokerException

Returns an enumeration of objects representing the primary keys for the objects that match the given query. Mainly useful for EJB Finder Methods.
Note: This method is not yet aware of extents!

Parameters:

pkClass - The class to use for the primary keys

query - The query

Returns:

The pk enumeration

Throws:

PersistenceBrokerException