org.springframework.orm.ojb
Class PersistenceBrokerTemplate

java.lang.Object
  extended by org.springframework.jdbc.support.JdbcAccessor
      extended by org.springframework.orm.ojb.OjbAccessor
          extended by 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)


Copyright (c) 2002-2007 The Spring Framework Project.