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, PersistenceBrokerFactorySyncImpl.PersistenceBrokerSyncImpl, PersistenceBrokerHandle, PersistenceBrokerImpl, PoolablePersistenceBroker

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

StatementManagerIF serviceStatementManager()
Returns the StatementManagerIF instance associated with this broker.

Returns:
The statement manager

serviceConnectionManager

ConnectionManagerIF serviceConnectionManager()
Returns the ConnectionManagerIF instance associated with this broker.

Returns:
The connection manager

serviceSqlGenerator

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

Returns:
The SQL generator

serviceJdbcAccess

JdbcAccess serviceJdbcAccess()
Returns the JdbcAccess instance associated with this broker.

Returns:
The JDBC access object

serviceSequenceManager

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

Returns:
The sequence manager

serviceBrokerHelper

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

Returns:
The broker helper object

serviceObjectCache

ObjectCache serviceObjectCache()
Returns the ObjectCache instance associated with this broker.

Returns:
The object cache

serviceIdentity

IdentityFactory serviceIdentity()
Return the IdentityFactory instance associated with this broker.

Returns:
The identity factory

fireBrokerEvent

void fireBrokerEvent(PersistenceBrokerEvent event)
Fires a broker event to inform all registered PBListener instances.

Parameters:
event - The event to fire

fireBrokerEvent

void fireBrokerEvent(PBLifeCycleEvent event)
Fires a life cycle event to inform all registered PBListener instances.

Parameters:
event - The event to fire

fireBrokerEvent

void fireBrokerEvent(PBStateEvent event)
Fires a state event to inform all registered PBListener instances.

Parameters:
event - The event to fire

removeAllListeners

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

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

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

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

void removeListener(PBListener listener)
                    throws PersistenceBrokerException
Removes the specified listener from this broker.

Parameters:
listener - The listener to remove
Throws:
PersistenceBrokerException

abortTransaction

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

void beginTransaction()
                      throws TransactionInProgressException,
                             TransactionAbortedException
Begins a transaction against the underlying RDBMS.

Throws:
TransactionInProgressException - If there is already a transaction in progress
TransactionAbortedException

commitTransaction

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

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

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

boolean isClosed()
Determines whether this broker is closed.

Returns:
true if this instance is closed

getDescriptorRepository

DescriptorRepository getDescriptorRepository()
Returns the metadata descriptor repository associated with this broker.

Returns:
The descriptor repository

getPBKey

PBKey getPBKey()
Get the PBKey for this broker.

Returns:
The broker key

getClassDescriptor

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

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

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

void clearCache()
                throws PersistenceBrokerException
Clears the broker's internal cache.

Throws:
PersistenceBrokerException

removeFromCache

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


(C) 2002 - 2006 Apache Software Foundation
All rights reserved. Published under the Apache License 2.0.
http://db.apache.org/ojb
Version: 1.0.4, 2005-12-30