tomdz 2005/12/22 12:40:21
Modified: src/java/org/apache/ojb/broker Tag: OJB_1_0_RELEASE
PersistenceBroker.java
Log:
Updated Javadoc
Revision Changes Path
No revision
No revision
1.30.2.6 +202 -165
db-ojb/src/java/org/apache/ojb/broker/PersistenceBroker.java
Index: PersistenceBroker.java
===================================================================
RCS file:
/home/cvs/db-ojb/src/java/org/apache/ojb/broker/PersistenceBroker.java,v
retrieving revision 1.30.2.5
retrieving revision 1.30.2.6
diff -u -r1.30.2.5 -r1.30.2.6
--- PersistenceBroker.java 21 Dec 2005 22:22:08 -0000 1.30.2.5
+++ PersistenceBroker.java 22 Dec 2005 20:40:17 -0000 1.30.2.6
@@ -41,9 +41,8 @@
* @see org.apache.ojb.broker.core.PersistenceBrokerImpl
* @see org.apache.ojb.broker.core.PersistenceBrokerBean
*
- * @author <a href="mailto:[EMAIL PROTECTED]">Thomas Mahler<a>
+ * @author Thomas Mahler
* @version $Id$
- *
*/
public interface PersistenceBroker extends Configurable, ObjectContainer
{
@@ -53,44 +52,59 @@
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.accesslayer.StatementManagerIF} instance associated with
this broker.
+ *
+ * @return The statement manager
*/
public StatementManagerIF serviceStatementManager();
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.accesslayer.ConnectionManagerIF} instance associated with
this broker.
+ *
+ * @return The connection manager
*/
public ConnectionManagerIF serviceConnectionManager();
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.accesslayer.sql.SqlGenerator} instance associated with
this broker.
+ *
+ * @return The SQL generator
*/
public SqlGenerator serviceSqlGenerator();
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.accesslayer.JdbcAccess} instance associated with this
broker.
+ *
+ * @return The JDBC access object
*/
public JdbcAccess serviceJdbcAccess();
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.util.sequence.SequenceManager} instance associated with
this broker.
+ *
+ * @return The sequence manager
*/
public SequenceManager serviceSequenceManager();
/**
- * Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.util.BrokerHelper} instance associated with this broker.
- * Makes some helper methods available.
+ * Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.util.BrokerHelper} instance associated with this broker,
which
+ * makes some additional helper methods available.
+ *
+ * @return The broker helper object
*/
public BrokerHelper serviceBrokerHelper();
/**
* Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.cache.ObjectCache} instance associated
* with this broker.
+ *
+ * @return The object cache
*/
public ObjectCache serviceObjectCache();
/**
* Return the [EMAIL PROTECTED] IdentityFactory} instance associated
with this broker.
- * @return service to create [EMAIL PROTECTED] Identity} objects.
+ *
+ * @return The identity factory
*/
public IdentityFactory serviceIdentity();
@@ -100,70 +114,78 @@
//
*************************************************************************
/**
- * Performs a broker event to inform all managed
- * [EMAIL PROTECTED] PBListener} implementations.
+ * Fires a broker event to inform all registered [EMAIL PROTECTED]
PBListener} instances.
+ *
+ * @param event The event to fire
*/
public void fireBrokerEvent(PersistenceBrokerEvent event);
/**
- * Performs a broker event to inform all managed
- * [EMAIL PROTECTED] PBListener} implementations.
+ * Fires a life cycle event to inform all registered [EMAIL PROTECTED]
PBListener} instances.
+ *
+ * @param event The event to fire
*/
public void fireBrokerEvent(PBLifeCycleEvent event);
/**
- * Performs a broker event to inform all managed
- * [EMAIL PROTECTED] PBListener} implementations.
+ * Fires a state event to inform all registered [EMAIL PROTECTED]
PBListener} instances.
+ *
+ * @param event The event to fire
*/
public void fireBrokerEvent(PBStateEvent event);
/**
- * Removes all temporary listeners from this PersistenceBroker instance
- * - Handle with care!
+ * Removes all temporary listeners from this broker.
+ * Use with care, because some internals rely on this mechanism.
+ *
+ * @see #removeListener(PBListener)
*/
public void removeAllListeners() throws PersistenceBrokerException;
/**
- * If parameter <code>permanet</code> was <code>true</code> all
permanent and temporary listeners
- * will be removed from this PersistenceBroker instance.
- * <br/>
- * <b>NOTE:</b> Handle with care!
- *
- * @see #removeListener(PBListener listener)
+ * Removes all temporary and, if desired, permanent listeners from this
broker.
+ * Use with care, because some internals rely on this mechanism.
+ *
+ * @param permanent Whether the listener will stay registered after
closing
+ * the broker
+ * @see #removeListener(PBListener)
*/
public void removeAllListeners(boolean permanent) throws
PersistenceBrokerException;
/**
- * Adds a temporary [EMAIL PROTECTED] org.apache.ojb.broker.PBListener}
- * to this PersistenceBroker instance - when PersistenceBroker.close()
was
- * called the listener was removed.
+ * Adds a temporary [EMAIL PROTECTED] org.apache.ojb.broker.PBListener}
to this broker.
+ * Note that temporary listeners will be removed upon closing a broker
(returning
+ * it to the pool).
*
* @param listener The listener to add
- * @see #addListener(org.apache.ojb.broker.PBListener listener, boolean
permanent)
+ * @see #addListener(PBListener, boolean)
*/
public void addListener(PBListener listener) throws
PersistenceBrokerException;
/**
- * Adds a permanent [EMAIL PROTECTED] org.apache.ojb.broker.PBListener}
- * to this PersistenceBroker instance if parameter <code>permanent</code>
- * was <code>true</code>. This means the listener will be
- * hold the whole life time of the broker.
+ * Adds a temporary or permanent [EMAIL PROTECTED]
org.apache.ojb.broker.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).
* <br/>
* <b>NOTE:</b> 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
+ * 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
* [EMAIL PROTECTED]
org.apache.ojb.broker.core.PersistenceBrokerFactoryIF} or extend the default
- * implementation [EMAIL PROTECTED]
org.apache.ojb.broker.core.PersistenceBrokerFactoryDefaultImpl}
- * and add the listener at creation of the [EMAIL PROTECTED]
org.apache.ojb.broker.PersistenceBroker}
+ * one, [EMAIL PROTECTED]
org.apache.ojb.broker.core.PersistenceBrokerFactoryDefaultImpl}. There you
+ * can add the listener at creation of the [EMAIL PROTECTED]
org.apache.ojb.broker.PersistenceBroker}
* instances.
+ *
+ * @param listener The listener to add
+ * @param permanent Whether the listener will stay registered after
closing
+ * the broker
*/
public void addListener(PBListener listener, boolean permanent) throws
PersistenceBrokerException;
/**
- * Removes a listener from this PersistenceBroker instance
- * @param listener
+ * Removes the specified listener from this broker.
+ *
+ * @param listener The listener to remove
*/
public void removeListener(PBListener listener) throws
PersistenceBrokerException;
@@ -173,55 +195,49 @@
//
*************************************************************************
/**
- * Abort and close the transaction.
- * Calling abort abandons all persistent object modifications and
releases the
- * associated locks.
- * <br>
- * If transaction is not in progress a TransactionNotInProgressException
is thrown
+ * 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
*/
public void abortTransaction() throws TransactionNotInProgressException;
/**
- * Begin a transaction against the underlying RDBMS.
- * Calling <code>beginTransaction</code> multiple times,
- * without an intervening call to <code>commitTransaction</code> or
<code>abortTransaction</code>,
- * causes the exception <code>TransactionInProgressException</code> to
be thrown
- * on the second and subsequent calls.
+ * Begins a transaction against the underlying RDBMS.
+ *
+ * @throws TransactionInProgressException If there is already a
transaction in progress
*/
- public void beginTransaction()
- throws TransactionInProgressException,
TransactionAbortedException;
+ public void beginTransaction() throws TransactionInProgressException,
TransactionAbortedException;
/**
- * Commit and close the transaction.
- * Calling <code>commit</code> 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.
+ * 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
+ * @throws TransactionAbortedException If the transaction cannot
be committed
*/
- public void commitTransaction()
- throws TransactionNotInProgressException,
TransactionAbortedException;
-
+ public void commitTransaction() throws
TransactionNotInProgressException, TransactionAbortedException;
/**
- * Returns <tt>true</tt> if the broker performs a transaction,
<tt>false</tt>
- * in the other case.
+ * Determines whether there is currently a transaction in progress.
+ *
+ * @return <code>true</code> if there is a transaction in progress
*/
public boolean isInTransaction() throws PersistenceBrokerException;
/**
- * 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.
+ * 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.
*
- * @return true if successful
+ * @return <code>true</code> if the broker was successfully closed
*/
public boolean close();
/**
- * Returns <tt>true</tt> if this instance is closed.
+ * Determines whether this broker is closed.
+ *
+ * @return <tt>true</tt> if this instance is closed
*/
public boolean isClosed();
@@ -232,209 +248,230 @@
//
*************************************************************************
/**
- * Returns the [EMAIL PROTECTED]
org.apache.ojb.broker.metadata.DescriptorRepository}
- * associated with this broker.
+ * Returns the metadata descriptor repository associated with this
broker.
+ *
+ * @return The descriptor repository
*/
public DescriptorRepository getDescriptorRepository();
/**
* Get the [EMAIL PROTECTED] PBKey} for this broker.
+ *
+ * @return The broker key
*/
public PBKey getPBKey();
/**
- * Returns a ClassDescriptor for the persistence capable class.
- * Throws a PersistenceBrokerException if clazz is not persistence
capable,
- * i.e. if no metadata was defined for this class or class was not found.
+ * Returns the class descriptor for the given persistence capable class.
+ *
+ * @param clazz The target class
+ * @return 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
*/
public ClassDescriptor getClassDescriptor(Class clazz) throws
PersistenceBrokerException;
/**
- * Same as [EMAIL PROTECTED] #getClassDescriptor}, but does not throw an
exception when class was not found.
- * Useful for checking if an object is persistence Capable.
- * @param clazz target class
- * @return true if descriptor was found
+ * Determines whether the given class is persistence capable and thus
has an associated
+ * class descriptor in the metadata.
+ *
+ * @param clazz The target class
+ * @return <code>true</code> if a class descriptor was found
*/
public boolean hasClassDescriptor(Class clazz);
-
/**
- * 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.
+ * 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.
+ *
+ * @param clazz The class to get the top level class for
+ * @return The top level class for it
+ * @throws PersistenceBrokerException If the class is not persistence
capable,
+ * if no metadata was defined for this class
*/
public Class getTopLevelClass(Class clazz) throws
PersistenceBrokerException;
-
-
//
*************************************************************************
// Object lifecycle
//
*************************************************************************
/**
- * 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.
- *
+ * Clears the broker's internal cache.
*/
public void clearCache() throws PersistenceBrokerException;
/**
- * Removes the object from the brokers internal cache.
- * If object is instance of [EMAIL PROTECTED]
org.apache.ojb.broker.Identity},
- * the associated object was removed from cache.
- * <br/>
- * Note: Removing is not recursive.
+ * Removes the given object or, if it is an instance of [EMAIL
PROTECTED] org.apache.ojb.broker.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.
+ *
+ * @param objectOrIdentity The object to be removed from the cache or
its identity
*/
public void removeFromCache(Object objectOrIdentity) 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
+ * Makes the given object persistent in the underlying persistence
system.
+ * This is usually done by issuing an INSERT ... or UPDATE ... in an
RDBMS.
*
- * (decide whether insert or update is needed. And for updates only
generate code for modified columns)
+ * @param obj The object to store
+ * @param modification Specifies what operation to perform (for
generating optimized SQL)
*/
public void store(Object obj,
ObjectModification modification) throws
PersistenceBrokerException;
/**
- * make object obj persistent in the underlying persistence system.
- * E.G. by INSERT INTO ... or UPDATE ... in an RDBMS
+ * Make the given object persistent in the underlying persistence system.
+ * This is usually done by issuing an INSERT ... or UPDATE ... in an
RDBMS.
+ *
+ * @param obj The object to store
*/
public void store(Object obj) throws PersistenceBrokerException;
/**
- * deletes the objects obj concrete representation in the underlying
persistence system.
- * E.G. by DELETE FROM ... WHERE ... in an RDBMS
+ * Deletes the given object's persistent representation in the
underlying persistence system.
+ * This is usually done by issuing a DELETE ... in an RDBMS
+ *
+ * @param obj The object to delete
*/
public void delete(Object obj) 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
+ * Deletes an m:n implementor which defines the relationship between two
persistent objects.
+ * This is usually a row in an indirection table.<br/>
+ * 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 :
collection descriptor element . isAssinableFrom(rightClass)
+ * 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
- *
- *
- * <b>Pre-coditions :</b>
- * <li></li>
- *
- * <b>Pos-coditions :</b>
- * <li></li>
- *
- * <b>Assertions :</b>
- * <li></li>
- *
- * @param m2nImpl
- * @throws PersistenceBrokerException if an error occours
+ *
+ * @param m2nImpl The m:n implementor to delete
*/
public void deleteMtoNImplementor(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.<br/>
+ * 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).
+ *
+ * @param m2nImpl The m:n implementor to delete
*/
public void addMtoNImplementor(MtoNImplementor m2nImpl) throws
PersistenceBrokerException;
/**
- * Deletes all objects matching the query from the underlying
persistence system.
- * E.G. by DELETE FROM ... WHERE ... in an RDBMS
- * <p/>
- * <b>Note:</b> This method directly perform the delete statement
ignoring object
- * references and do not synchronize the cache - take care!
+ * Deletes all objects matching the given query, from the underlying
persistence system.
+ * This is usually done via DELETE ... in an RDBMS.<br/>
+ * <b>Note:</b> This method directly perform the delete statement
ignoring any object
+ * references and does not synchronize the cache - take care!
+ *
+ * @param query The query determining the objects to delete
*/
public void deleteByQuery(Query query) throws PersistenceBrokerException;
-
-
-
-
//
*************************************************************************
// Query methods
//
*************************************************************************
/**
- * Retrieve all Reference- and Collection-attributes of a given
- * instance, independent from the used metadata-settings of the
- * references.
+ * Retrieve all references and collections of the given object
irrespective of the
+ * metadata settings defined for them.
*
- * @param pInstance the persistent instance
+ * @param obj The persistent object
*/
- public void retrieveAllReferences(Object pInstance) throws
PersistenceBrokerException;
+ public void retrieveAllReferences(Object obj) throws
PersistenceBrokerException;
/**
- * retrieve a single reference- or collection attribute
- * of a persistent instance.
- * @param pInstance the persistent instance
- * @param pAttributeName the name of the Attribute to load
+ * Retrieve the specified reference or collection attribute for the
given persistent object.
+ *
+ * @param obj The persistent object
+ * @param attrName The name of the attribute to retrieve
*/
- public void retrieveReference(Object pInstance, String pAttributeName)
throws PersistenceBrokerException;
+ public void retrieveReference(Object obj, String attrName) throws
PersistenceBrokerException;
/**
- * Returns the count of elements a given query will return.
+ * Returns the number of elements that the given query will return.
+ *
+ * @param query The query
+ * @return The number of elements returned by the query
*/
public int getCount(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.
+ * 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.
+ *
+ * @param query The query
+ * @return The persistent objects matching the query
*/
public Collection getCollectionByQuery(Query query) throws
PersistenceBrokerException;
/**
- * Retrieve a userdefined Collection that implements the interface
Manageable collection
- * that contains all Objects matching the Query query.
- * <br>
- * If query has no criteria no WHERE-clause is generated, i.e. ALL table
rows are selected.
+ * 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.
+ *
+ * @param collectionClass The collection type which needs to implement
+ * [EMAIL PROTECTED] ManageableCollection}
+ * @param query The query
+ * @return The persistent objects matching the query
*/
public ManageableCollection getCollectionByQuery(Class collectionClass,
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.
+ * 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 [EMAIL PROTECTED] Iterator#next()}. Note
that if the Query has no criteria
+ * ALL persistent objects of the class targeted by the query will be
returned.
+ *
+ * @param query The query
+ * @return The persistent objects matching the query
*/
public Iterator getIteratorByQuery(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
+ * Retrieves the rows (as <code>Object[]</code> 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 [EMAIL PROTECTED]
Iterator#next()}.
+ *
+ * @param query The report query
+ * @return The rows matching the query
*/
public Iterator getReportQueryIteratorByQuery(Query query) 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)
+ * Retrieve a persistent object from the underlying datastore by its
identity. However, users
+ * are encouraged to use [EMAIL PROTECTED] #getObjectByQuery(Query)}
instead, as this method is mainly
+ * intended to be used for internal handling of materialization by OID
(e.g. in Proxies).
+ *
+ * @param id The persistent object's id
+ * @return The persistent object
*/
public Object getObjectByIdentity(Identity id) throws
PersistenceBrokerException;
/**
- * Retrieve an Object by query.
- * I.e perform a SELECT ... FROM ... WHERE ... in an RDBMS
+ * Retrieve the (first) persistent object from the underlying datastore
that matches the given
+ * query.
+ *
+ * @param query The query
+ * @return The persistent object
*/
public Object getObjectByQuery(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 !
- * @param PrimaryKeyClass the pk class for the searched objects
- * @param query the query
+ * Returns an enumeration of objects representing the primary keys for
the objects that match
+ * the given query. Mainly useful for EJB Finder Methods.<br/>
+ * <b>Note:</b> This method is not yet aware of extents!
+ *
+ * @param pkClass The class to use for the primary keys
+ * @param query The query
+ * @return The pk enumeration
*/
- public Enumeration getPKEnumerationByQuery(Class PrimaryKeyClass, Query
query)
+ public Enumeration getPKEnumerationByQuery(Class pkClass, Query query)
throws PersistenceBrokerException;
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
