org.springframework.orm.ojb
Class PersistenceBrokerTemplate

java.lang.Object
  org.springframework.jdbc.support.JdbcAccessor
      org.springframework.orm.ojb.OjbAccessor
          org.springframework.orm.ojb.PersistenceBrokerTemplate

All Implemented Interfaces:

InitializingBean, PersistenceBrokerOperations

public class PersistenceBrokerTemplate
extends OjbAccessor
implements PersistenceBrokerOperations

Helper class that simplifies OJB PersistenceBroker data access code, and converts PersistenceBrokerExceptions into Spring DataAccessExceptions, following the org.springframework.dao exception hierarchy.

The central method is execute, supporting OJB code implementing the PersistenceBrokerCallback interface. It provides PersistenceBroker handling such that neither the PersistenceBrokerCallback implementation nor the calling code needs to explicitly care about retrieving/closing PersistenceBrokers, or handling OJB lifecycle exceptions.

Typically used to implement data access or business logic services that use OJB within their implementation but are OJB-agnostic in their interface. The latter or code calling the latter only have to deal with business objects, query objects, and org.springframework.dao exceptions.

Note that operations that return an Iterator (that is, getIteratorByQuery and getReportQueryIteratorByQuery) are supposed to be used within Spring-managed transactions (with PersistenceBrokerTransactionManager or JtaTransactionManager). Else, the Iterator won't be able to read results from its ResultSet anymore, as the underlying PersistenceBroker will already have been closed.

Since:

1.1

Author:

Juergen Hoeller

See Also:

OjbAccessor.setPbKey(org.apache.ojb.broker.PBKey), PersistenceBrokerCallback, PersistenceBroker, getIteratorByQuery(org.apache.ojb.broker.query.Query), getReportQueryIteratorByQuery(org.apache.ojb.broker.query.Query), PersistenceBrokerTransactionManager, JtaTransactionManager

Field Summary

Fields inherited from class org.springframework.jdbc.support.JdbcAccessor

logger

Constructor Summary

PersistenceBrokerTemplate()
Create a new PersistenceBrokerTemplate, using the default connection configured for OJB.

PersistenceBrokerTemplate(boolean allowCreate)
Create a new PersistenceBrokerTemplate, using the default connection configured for OJB.

PersistenceBrokerTemplate(org.apache.ojb.broker.PBKey pbKey)
Create a new PersistenceBrokerTemplate.

PersistenceBrokerTemplate(org.apache.ojb.broker.PBKey pbKey, boolean allowCreate)
Create a new PersistenceBrokerTemplate.

Method Summary

void	clearCache()
void	delete(Object entity)
void	deleteByQuery(org.apache.ojb.broker.query.Query query)
Object	execute(PersistenceBrokerCallback action) Execute the action specified by the given action object within a PersistenceBroker.
Collection	executeFind(PersistenceBrokerCallback action) Execute the specified action assuming that the result object is a Collection.
Collection	getCollectionByQuery(org.apache.ojb.broker.query.Query query)
int	getCount(org.apache.ojb.broker.query.Query query)
Iterator	getIteratorByQuery(org.apache.ojb.broker.query.Query query)
Object	getObjectById(Class entityClass, Object idValue) Return the persistent instance of the given entity class with the given id value, throwing an exception if not found.
Object	getObjectByQuery(org.apache.ojb.broker.query.Query query)
protected org.apache.ojb.broker.PersistenceBroker	getPersistenceBroker() Get an OJB PersistenceBroker for the PBKey of this template.
Iterator	getReportQueryIteratorByQuery(org.apache.ojb.broker.query.Query query)
boolean	isAllowCreate() Return if a new PersistenceBroker should be created if no thread-bound found.
protected void	releasePersistenceBroker(org.apache.ojb.broker.PersistenceBroker pb) Close the given PersistenceBroker, created for the PBKey of this template, if it isn't bound to the thread.
void	removeFromCache(Object entityOrId)
void	setAllowCreate(boolean allowCreate) Set if a new PersistenceBroker should be created when no transactional PersistenceBroker can be found for the current thread.
void	store(Object entity)

Methods inherited from class org.springframework.orm.ojb.OjbAccessor

convertJdbcAccessException, convertOjbAccessException, getJcdAlias, getPbKey, setJcdAlias, setPbKey

Methods inherited from class org.springframework.jdbc.support.JdbcAccessor

afterPropertiesSet, getDataSource, getExceptionTranslator, isLazyInit, setDatabaseProductName, setDataSource, setExceptionTranslator, setLazyInit

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PersistenceBrokerTemplate

public PersistenceBrokerTemplate()

Create a new PersistenceBrokerTemplate, using the default connection configured for OJB. Can be further configured via bean properties.

PersistenceBrokerTemplate

public PersistenceBrokerTemplate(boolean allowCreate)

Create a new PersistenceBrokerTemplate, using the default connection configured for OJB.

Parameters:

allowCreate - if a non-transactional PersistenceBroker should be created when no transactional PersistenceBroker can be found for the current thread

PersistenceBrokerTemplate

public PersistenceBrokerTemplate(org.apache.ojb.broker.PBKey pbKey)

Create a new PersistenceBrokerTemplate.

Parameters:

pbKey - the PBKey of the PersistenceBroker configuration to use

PersistenceBrokerTemplate

public PersistenceBrokerTemplate(org.apache.ojb.broker.PBKey pbKey,
                                 boolean allowCreate)

Create a new PersistenceBrokerTemplate.

Parameters:

pbKey - the PBKey of the PersistenceBroker configuration to use

allowCreate - if a new PersistenceBroker should be created if no thread-bound found

Method Detail

setAllowCreate

public void setAllowCreate(boolean allowCreate)

Set if a new PersistenceBroker should be created when no transactional PersistenceBroker can be found for the current thread.

JdoTemplate is aware of a corresponding PersistenceBroker bound to the current thread, for example when using PersistenceBrokerTransactionManager. If allowCreate is true, a new non-transactional PersistenceManager will be created if none found, which needs to be closed at the end of the operation. If false, an IllegalStateException will get thrown in this case.

See Also:

OjbFactoryUtils.getPersistenceBroker(org.apache.ojb.broker.PBKey, boolean)

isAllowCreate

public boolean isAllowCreate()

Return if a new PersistenceBroker should be created if no thread-bound found.

execute

public Object execute(PersistenceBrokerCallback action)
               throws DataAccessException

Description copied from interface: PersistenceBrokerOperations

Execute the action specified by the given action object within a PersistenceBroker. Application exceptions thrown by the action object get propagated to the caller (can only be unchecked). OJB exceptions are transformed into appropriate DAO ones. Allows for returning a result object, i.e. a domain object or a collection of domain objects.

Note: Callback code is not supposed to handle transactions itself! Use an appropriate transaction manager like PersistenceBrokerTransactionManager.

Specified by:

execute in interface PersistenceBrokerOperations

Parameters:

action - action object that specifies the OJB action

Returns:

a result object returned by the action, or null

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBrokerTransactionManager, org.springframework.dao, org.springframework.transaction

executeFind

public Collection executeFind(PersistenceBrokerCallback action)
                       throws DataAccessException

Description copied from interface: PersistenceBrokerOperations

Execute the specified action assuming that the result object is a Collection. This is a convenience method for executing OJB queries within an action.

Specified by:

executeFind in interface PersistenceBrokerOperations

Parameters:

action - action object that specifies the OJB action

Returns:

a result object returned by the action, or null

Throws:

DataAccessException - in case of OJB errors

getObjectById

public Object getObjectById(Class entityClass,
                            Object idValue)
                     throws DataAccessException

Description copied from interface: PersistenceBrokerOperations

Return the persistent instance of the given entity class with the given id value, throwing an exception if not found.

The given id value is typically just unique within the namespace of the persistent class, corresponding to a single primary key in a database table.

Specified by:

getObjectById in interface PersistenceBrokerOperations

Parameters:

entityClass - a persistent class

idValue - an id value of the persistent instance

Returns:

the persistent instance

Throws:

ObjectRetrievalFailureException - if not found

DataAccessException - in case of OJB errors

See Also:

IdentityFactory.buildIdentity(Class, Object), PersistenceBroker.getObjectByIdentity(org.apache.ojb.broker.Identity)

getObjectByQuery

public Object getObjectByQuery(org.apache.ojb.broker.query.Query query)
                        throws DataAccessException

Specified by:

getObjectByQuery in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.getObjectByQuery(org.apache.ojb.broker.query.Query)

getCollectionByQuery

public Collection getCollectionByQuery(org.apache.ojb.broker.query.Query query)
                                throws DataAccessException

Specified by:

getCollectionByQuery in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.getCollectionByQuery(org.apache.ojb.broker.query.Query)

getIteratorByQuery

public Iterator getIteratorByQuery(org.apache.ojb.broker.query.Query query)
                            throws DataAccessException

Specified by:

getIteratorByQuery in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.getIteratorByQuery(org.apache.ojb.broker.query.Query)

getReportQueryIteratorByQuery

public Iterator getReportQueryIteratorByQuery(org.apache.ojb.broker.query.Query query)

Specified by:

getReportQueryIteratorByQuery in interface PersistenceBrokerOperations

See Also:

PersistenceBroker.getReportQueryIteratorByQuery(org.apache.ojb.broker.query.Query)

getCount

public int getCount(org.apache.ojb.broker.query.Query query)
             throws DataAccessException

Specified by:

getCount in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.getCount(org.apache.ojb.broker.query.Query)

removeFromCache

public void removeFromCache(Object entityOrId)
                     throws DataAccessException

Specified by:

removeFromCache in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.removeFromCache(java.lang.Object)

clearCache

public void clearCache()
                throws DataAccessException

Specified by:

clearCache in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.clearCache()

store

public void store(Object entity)
           throws DataAccessException

Specified by:

store in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.store(java.lang.Object, org.apache.ojb.broker.util.ObjectModification)

delete

public void delete(Object entity)
            throws DataAccessException

Specified by:

delete in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.delete(java.lang.Object)

deleteByQuery

public void deleteByQuery(org.apache.ojb.broker.query.Query query)
                   throws DataAccessException

Specified by:

deleteByQuery in interface PersistenceBrokerOperations

Throws:

DataAccessException - in case of OJB errors

See Also:

PersistenceBroker.deleteByQuery(org.apache.ojb.broker.query.Query)

getPersistenceBroker

protected org.apache.ojb.broker.PersistenceBroker getPersistenceBroker()
                                                                throws DataAccessResourceFailureException,
                                                                       IllegalStateException

Get an OJB PersistenceBroker for the PBKey of this template.

Default implementation delegates to OjbFactoryUtils. Can be overridden in subclasses, e.g. for testing purposes.

Returns:

the PersistenceBroker

Throws:

DataAccessResourceFailureException - if the PersistenceBroker couldn't be created

IllegalStateException - if no thread-bound PersistenceBroker found and allowCreate false

See Also:

OjbAccessor.setJcdAlias(java.lang.String), OjbAccessor.setPbKey(org.apache.ojb.broker.PBKey), setAllowCreate(boolean), OjbFactoryUtils.getPersistenceBroker(PBKey, boolean)

releasePersistenceBroker

protected void releasePersistenceBroker(org.apache.ojb.broker.PersistenceBroker pb)

Close the given PersistenceBroker, created for the PBKey of this template, if it isn't bound to the thread.

Default implementation delegates to OjbFactoryUtils. Can be overridden in subclasses, e.g. for testing purposes.

Parameters:

pb - PersistenceBroker to close

See Also:

OjbAccessor.setJcdAlias(java.lang.String), OjbAccessor.setPbKey(org.apache.ojb.broker.PBKey), OjbFactoryUtils.releasePersistenceBroker(org.apache.ojb.broker.PersistenceBroker, org.apache.ojb.broker.PBKey)