ojb.broker
Interface PersistenceBroker

All Known Implementing Classes:

PersistenceBrokerClient, PersistenceBrokerImpl

public interface PersistenceBroker

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

Author:

Thomas Mahler

See Also:

PersistenceBrokerClient

Method Summary

void	abortTransaction() Abort and close the transaction.
void	beginTransaction() begin a transaction against the underlying RDBMS.
void	clearCache() clears the brokers internal cache.
boolean	close() close connection to last opened repository.
void	commitTransaction() Commit and close the transaction.
void	delete(java.lang.Object obj) deletes the objects obj concrete representation in the underlying persistence system.
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.
java.lang.Class	getExtentClass(java.lang.Class clazz) returnsthe Extent to which the class clazz belongs.
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.
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.
int	getUniqueId(java.lang.Class extent, java.lang.String attribute) returns a unique int for class extent and field attribute.
long	getUniqueLong(java.lang.Class extent, java.lang.String attribute) returns a unique long for class extent and field attribute.
java.lang.Object	getUniqueObject(java.lang.Class extent, java.lang.String attribute) returns a unique Object for class extent and field attribute.
java.lang.String	getUniqueString(java.lang.Class extent, java.lang.String attribute) returns a unique String for class extent and field attribute.
void	invalidate(Identity oid) removes the objects obj from the brokers internal cache and inform other caches in OJB cluster about invalidation.
boolean	isInTransaction() returns true if the broker performs a transaction.
boolean	open(java.lang.String repository, java.lang.String user, java.lang.String passwd) open a repository. returns true if successfull, else false.
void	removeFromCache(java.lang.Object obj) removes the objects obj from the brokers internal cache.
void	setClassDescriptor(ClassDescriptor modifiedOrNewDescriptor) adds a new or replaces an existing ClassDescriptor to the DescriptorRepository.
void	store(java.lang.Object obj) make object obj persistent in the underlying persistence system.
void	store(java.lang.Object obj, ObjectModification modification) makes object obj persistent in the underlying persistence system.

Method Detail

delete

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

deletes the objects obj concrete representation in the underlying persistence system. E.G. by DELETE FROM ... WHERE ... in an RDBMS

PersistenceBrokerException

removeFromCache

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

removes the objects obj from the brokers internal cache. removing is not recursive.

PersistenceBrokerException

invalidate

public void invalidate(Identity oid)
                throws PersistenceBrokerException

removes the objects obj from the brokers internal cache and inform other caches in OJB cluster about invalidation.

PersistenceBrokerException

clearCache

public void clearCache()
                throws PersistenceBrokerException

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

PersistenceBrokerException

store

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

make object obj persistent in the underlying persistence system. E.G. by INSERT INTO ... or UPDATE ... in an RDBMS

PersistenceBrokerException

abortTransaction

public void abortTransaction()
                      throws TransactionNotInProgressException

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

TransactionNotInProgressException

beginTransaction

public void beginTransaction()
                      throws TransactionInProgressException,
                             TransactionAbortedException

begin a transaction against the underlying RDBMS. Calling beginTransaction multiple times, without an intervening call to commitTransaction or abortTransaction, causes the exception TransactionInProgressException to be thrown on the second and subsequent calls.

TransactionInProgressException

TransactionAbortedException

commitTransaction

public void commitTransaction()
                       throws TransactionNotInProgressException,
                              TransactionAbortedException

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

TransactionNotInProgressException

TransactionAbortedException

isInTransaction

public boolean isInTransaction()
                        throws PersistenceBrokerException

returns true if the broker performs a transaction. returns false if broker is not in a transaction.

PersistenceBrokerException

open

public boolean open(java.lang.String repository,
                    java.lang.String user,
                    java.lang.String passwd)
             throws PersistenceBrokerException

open a repository. returns true if successfull, else false.

Parameters:

repository - name of the repository

user - user name, if left null username is taken from repository.

passwd - password, if left null password is taken from repository.

Returns:

true if successful, else false.

PersistenceBrokerException

close

public boolean close()

close connection to last opened repository.

Returns:

true if successful

getCollectionByQuery

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

retrieve a collection of itemClass Objects matching the Query query. if the Query has no criteria no WHERE-clause is generated, i.e. ALL table rows are selected.

PersistenceBrokerException

getCount

public int getCount(Query query)
             throws PersistenceBrokerException

returns the count of elements a given query will return.

PersistenceBrokerException

getCollectionByQuery

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

retrieve a userdefined Collection that implements the interface Manageable collection that contains all Objects matching the Query query. If query has no criteria no WHERE-clause is generated, i.e. ALL table rows are selected.

PersistenceBrokerException

getIteratorByQuery

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

returns an Iterator that iterates Objects of class c if calling the .next() method. The Elements returned come from a SELECT ... WHERE Statement that is defined by the Query query. If itemProxy is null, no proxies are used. NOT YET AWARE OF EXTENTS !

PersistenceBrokerException

getReportQueryIteratorByQuery

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

returns an Iterator that iterates Object[] calling the .next() method. The Elements returned come from a SELECT ... WHERE sqlStatement The Class c is only used to provide the associated JDBC Connection

PersistenceBrokerException

getObjectByIdentity

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

retrieve an Object by its Identity. Application Developers are encouraged to use getObjectByQuery(). This method is mainly used for internal performant handling of materialization by OID (e.g. in Proxies)

PersistenceBrokerException

getObjectByQuery

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

retrieve an Object by query. I.e perform a SELECT ... FROM ... WHERE ... in an RDBMS

PersistenceBrokerException

getPKEnumerationByQuery

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

returns an Enumeration of PrimaryKey Objects for objects of class DataClass. The Elements returned come from a SELECT ... WHERE Statement that is defined by the fields and their coresponding values of vecFields and vecValues. Useful for EJB Finder Methods... NOT YET AWARE OF EXTENTS !

Parameters:

PrimaryKeyClass - the pk class for the searched objects

query - the query

PersistenceBrokerException

store

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

makes object obj persistent in the underlying persistence system. E.G. by INSERT INTO ... or UPDATE ... in an RDBMS. The ObjectModification parameter can be used to generate optimized SQL code (decide whether insert or update is needed. And for updates only generate code for modified columns)

PersistenceBrokerException

getUniqueId

public int getUniqueId(java.lang.Class extent,
                       java.lang.String attribute)
                throws PersistenceBrokerException

returns a unique int for class extent and field attribute. the returned uid is unique accross all tables in the extent of class extent.

PersistenceBrokerException

getUniqueLong

public long getUniqueLong(java.lang.Class extent,
                          java.lang.String attribute)
                   throws PersistenceBrokerException

returns a unique long for class extent and field attribute. the returned number is unique accross all tables in the extent of class extent.

PersistenceBrokerException

getUniqueString

public java.lang.String getUniqueString(java.lang.Class extent,
                                        java.lang.String attribute)
                                 throws PersistenceBrokerException

returns a unique String for class extent and field attribute. the returned String is unique accross all tables in the extent of class extent.

PersistenceBrokerException

getUniqueObject

public java.lang.Object getUniqueObject(java.lang.Class extent,
                                        java.lang.String attribute)
                                 throws PersistenceBrokerException

returns a unique Object for class extent and field attribute. the returned Object is unique accross all tables in the extent of class extent.

PersistenceBrokerException

getClassDescriptor

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

returns a ClassDescriptor for the persistence capable class clazz. throws a PersistenceBrokerException if clazz is not persistence capable, i.e. if clazz is not defined in the DescriptorRepository.

PersistenceBrokerException

setClassDescriptor

public void setClassDescriptor(ClassDescriptor modifiedOrNewDescriptor)
                        throws PersistenceBrokerException

adds a new or replaces an existing ClassDescriptor to the DescriptorRepository.

PersistenceBrokerException

getExtentClass

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

returnsthe Extent to which the class clazz belongs. This may be a baseclass,an interface or clazz itself, if no Extent is defined. throws a PersistenceBrokerException if clazz is not persistence capable, i.e. if clazz is not defined in the DescriptorRepository.

PersistenceBrokerException