org.apache.openjpa.abstractstore
Class AbstractStoreManager

java.lang.Object
  extended by org.apache.openjpa.abstractstore.AbstractStoreManager
All Implemented Interfaces:
StoreManager, Closeable
Direct Known Subclasses:
XMLStoreManager

public abstract class AbstractStoreManager
extends Object
implements StoreManager

Abstract store manager implementation to ease development of custom OpenJPA back-ends. A concrete subclass must define implementations for the following methods:

Additionally, subclasses should not attempt to acquire resources until open() has been called. Store manager instances might be created to call metadata methods such as newConfiguration() or getUnsupportedOptions() and never opened. These instances should not consume any data store resources. Notes:

Since:
0.3.1

Field Summary
protected  StoreContext ctx
           
 
Fields inherited from interface org.apache.openjpa.kernel.StoreManager
FORCE_LOAD_ALL, FORCE_LOAD_DFG, FORCE_LOAD_NONE, FORCE_LOAD_REFRESH, VERSION_DIFFERENT, VERSION_EARLIER, VERSION_LATER, VERSION_SAME
 
Constructor Summary
AbstractStoreManager()
           
 
Method Summary
protected  boolean assignDataStoreId(OpenJPAStateManager sm, Object val)
          Assign a new datastore identity to the given instance.
 boolean assignField(OpenJPAStateManager sm, int field, boolean preFlush)
          Assign a value to the given field.
 boolean assignObjectId(OpenJPAStateManager sm, boolean preFlush)
          Assign an object id to the given new instance.
 void beforeStateChange(OpenJPAStateManager sm, PCState fromState, PCState toState)
          Notification that the given state manager is about to change its lifecycle state.
 void begin()
          OpenJPA assumes that after this method is invoked, all data accesses through this store manager will be part of a single unit of work that can be rolled back.
 void beginOptimistic()
          No-op implementation.
 boolean cancelAll()
          Returns false.
 void close()
          Free any resources this store manager is using.
 void commit()
          This is a no-op implementation.
 int compareVersion(OpenJPAStateManager state, Object v1, Object v2)
          Casts v1 and v2 to Comparable, and invokes v1.compareTo (v2).
 Object copyDataStoreId(Object oid, ClassMetaData meta)
          Copy the given object id value.
abstract  ResultObjectProvider executeExtent(ClassMetaData meta, boolean subs, FetchConfiguration fetch)
          Create a ResultObjectProvider that can return all instances of type, optionally including subclasses as defined by subclasses.
 Collection flush(Collection sms)
          Breaks down states based on the objects' current states, and delegates to flush(Collection,Collection,Collection,Collection,Collection).
protected abstract  Collection flush(Collection pNew, Collection pNewUpdated, Collection pNewFlushedDeleted, Collection pDirty, Collection pDeleted)
          Responsible for writing modifications happened back to the data store.
 Object getClientConnection()
          Returns null.
 StoreContext getContext()
          Returns the StoreContext that this store manager is associated with.
 Seq getDataStoreIdSequence(ClassMetaData forClass)
          Returns the system-configured sequence.
 Class getDataStoreIdType(ClassMetaData meta)
          Return the class used by this StoreManager for datastore identity values.
 Class getManagedType(Object oid)
          Return the persistent class for the given data store identity value.
protected  String getPlatform()
          Returns a string name to identify the platform of this store manager.
protected  Collection getUnsupportedOptions()
          Returns a set of option names that this store manager does not support.
 Seq getValueSequence(FieldMetaData forField)
          Returns null.
abstract  boolean initialize(OpenJPAStateManager sm, PCState state, FetchConfiguration fetch, Object edata)
          This method is invoked when OpenJPA needs to load an object whose identity is known but which has not yet been loaded from the data store.
abstract  boolean load(OpenJPAStateManager sm, BitSet fields, FetchConfiguration fetch, int lockLevel, Object edata)
          This method is invoked when OpenJPA needs to load additional data into an object that has already been at least partially loaded by a previous initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) invocation.
 Collection loadAll(Collection sms, PCState state, int load, FetchConfiguration fetch, Object edata)
          This implementation just delegates to the proper singular method (StoreManager.initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) or StoreManager.load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object)) depending on each state manager's state.
protected  OpenJPAConfiguration newConfiguration()
          Return a new configuration instance for this runtime.
 Object newDataStoreId(Object val, ClassMetaData meta)
          Create a new unique datastore identity for the given type from the given oid value (presumably pk, stringified oid, or oid instance).
 FetchConfiguration newFetchConfiguration()
          Return a fetch configuration suitable for this runtime.
 StoreQuery newQuery(String language)
          Return a query implementation suitable for this store.
protected  void open()
          No-op implementation.
 void releaseConnection()
          Override to release previously-retained connection.
 void retainConnection()
          Override to retain a dedicated connection.
 void rollback()
          This is a no-op implementation.
 void rollbackOptimistic()
          No-op implementation.
 void setContext(StoreContext ctx)
          Set a reference to the corresponding context.
 boolean syncVersion(OpenJPAStateManager sm, Object edata)
          Since this store manager does not provide optimistic locking support, this method always returns true.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.openjpa.kernel.StoreManager
exists
 

Field Detail

ctx

protected StoreContext ctx
Constructor Detail

AbstractStoreManager

public AbstractStoreManager()
Method Detail

setContext

public final void setContext(StoreContext ctx)
Description copied from interface: StoreManager
Set a reference to the corresponding context. This method will be called before the store manager is used. The store manager is responsible for pulling any necessary configuration data from the context, including the transaction mode and connection retain mode.

Specified by:
setContext in interface StoreManager

getContext

public StoreContext getContext()
Returns the StoreContext that this store manager is associated with.


open

protected void open()
No-op implementation. Ready this store manager for persistent operations.


beginOptimistic

public void beginOptimistic()
No-op implementation. Override this method to provide optimistic locking semantics for your data store if you need notification of the beginning of an optimistic transaction.

Specified by:
beginOptimistic in interface StoreManager

rollbackOptimistic

public void rollbackOptimistic()
No-op implementation. Override this method to provide optimistic locking semantics for your data store if you need notification of a rollback of an optimistic transaction before begin() is invoked.

Specified by:
rollbackOptimistic in interface StoreManager

begin

public void begin()
OpenJPA assumes that after this method is invoked, all data accesses through this store manager will be part of a single unit of work that can be rolled back. This is a no-op implementation. If your data store does not support any concept of locking or transactions, you need not override this method.

Specified by:
begin in interface StoreManager

commit

public void commit()
This is a no-op implementation. If your data store does not have a concept of transactions or a unit of work, you need not override this method. If it does, then override this method to notify the data store that the current transaction should be committed.

Specified by:
commit in interface StoreManager

rollback

public void rollback()
This is a no-op implementation. If your data store does not have a concept of transactions or a unit of work, you need not override this method. If it does, then override this method to notify the data store that the current transaction should be rolled back.

Specified by:
rollback in interface StoreManager

syncVersion

public boolean syncVersion(OpenJPAStateManager sm,
                           Object edata)
Since this store manager does not provide optimistic locking support, this method always returns true.

Specified by:
syncVersion in interface StoreManager
Parameters:
sm - the instance to check
edata - the current execution data, or null if not given to the calling method of the context
Returns:
true if the instance still exists in the datastore and is up-to-date, false otherwise

initialize

public abstract boolean initialize(OpenJPAStateManager sm,
                                   PCState state,
                                   FetchConfiguration fetch,
                                   Object edata)
This method is invoked when OpenJPA needs to load an object whose identity is known but which has not yet been loaded from the data store. sm is a partially-set-up state manager for this object. The ID and least-derived type information for the instance to load can be obtained by invoking sm.getObjectId() and sm.getMetaData(). When implementing this method, load the data for this object from the data store, determine the most-derived subclass of the newly-loaded data, and then use the OpenJPAStateManager.initialize(java.lang.Class, org.apache.openjpa.kernel.PCState) method to populate sm with a new instance of the appropriate type. Once OpenJPAStateManager.initialize(java.lang.Class, org.apache.openjpa.kernel.PCState) has been invoked, proceed to load field data into sm as in the load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object) method, by using OpenJPAStateManager.store(int, java.lang.Object) (or the appropriate OpenJPAStateManager.storetype method) to put the data into the object.

Specified by:
initialize in interface StoreManager
Parameters:
sm - the instance to initialize
state - the lifecycle state to initialize the state manager with
fetch - configuration for how to load the instance
edata - the current execution data, or null if not given to the calling method of the broker
Returns:
true if the matching instance exists in the data store, false otherwise

load

public abstract boolean load(OpenJPAStateManager sm,
                             BitSet fields,
                             FetchConfiguration fetch,
                             int lockLevel,
                             Object edata)
This method is invoked when OpenJPA needs to load additional data into an object that has already been at least partially loaded by a previous initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) invocation. Load data into sm by using OpenJPAStateManager.store(int, java.lang.Object) (or the appropriate OpenJPAStateManager.storetype method) to put the data into the object.

Specified by:
load in interface StoreManager
Parameters:
sm - the instance to load
fields - set of fields to load; all field indexes in this set must be loaded; this set is mutable
fetch - the fetch configuration to use when loading related objects
lockLevel - attempt to load simple fields at this lock level; relations should be loaded at the read lock level of the fetch configuration
edata - the current execution data, or null if not given to the calling method of the broker
Returns:
false if the object no longer exists in the database, true otherwise

loadAll

public Collection loadAll(Collection sms,
                          PCState state,
                          int load,
                          FetchConfiguration fetch,
                          Object edata)
This implementation just delegates to the proper singular method (StoreManager.initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) or StoreManager.load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object)) depending on each state manager's state. If your data store provides bulk loading APIs, overriding this method to be more clever may be advantageous.

Specified by:
loadAll in interface StoreManager
Parameters:
sms - the state manager instances to load
state - the lifecycle state to initialize uninitialized state managers with; may be null if no uninitialized instances are included in sms
load - one of the FORCE_LOAD_* constants describing the fields to force-load if this is a refresh or retrieve action
fetch - the current fetch configuration to use when loading related objects
edata - the current execution data, or null if not given to the calling method of the broker
Returns:
a collection of the state manager identities for which no data store record exists
See Also:
ImplHelper.loadAll(java.util.Collection, org.apache.openjpa.kernel.StoreManager, org.apache.openjpa.kernel.PCState, int, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object)

flush

public Collection flush(Collection sms)
Breaks down states based on the objects' current states, and delegates to flush(Collection,Collection,Collection,Collection,Collection).

Specified by:
flush in interface StoreManager
See Also:
org.apache.openjpa.util.ApplicationIds#assign()

beforeStateChange

public void beforeStateChange(OpenJPAStateManager sm,
                              PCState fromState,
                              PCState toState)
Description copied from interface: StoreManager
Notification that the given state manager is about to change its lifecycle state. The store manager is not required to do anything in this method, but some back ends may need to.

Specified by:
beforeStateChange in interface StoreManager

assignObjectId

public boolean assignObjectId(OpenJPAStateManager sm,
                              boolean preFlush)
Description copied from interface: StoreManager
Assign an object id to the given new instance. Return false if the instance cannot be assigned an identity because a flush is required (for example, the identity is determined by the datastore on insert). For application identity instances, the assigned object id should be based on field state. The implementation is responsible for using the proper value strategy according to the instance metadata. This method is called the first time a user requests the oid of a new instance before flush.

Specified by:
assignObjectId in interface StoreManager
preFlush - whether this assignment is being requested by the system as part of pre-flush activities, and can be ignored if it is more efficient to assign within StoreManager.flush(java.util.Collection)
See Also:
ImplHelper.generateFieldValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.FieldMetaData), ImplHelper.generateIdentityValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.ClassMetaData, int), org.apache.openjpa.util.ApplicationIds#assign()

assignDataStoreId

protected boolean assignDataStoreId(OpenJPAStateManager sm,
                                    Object val)
Assign a new datastore identity to the given instance. This given value may be null.


assignField

public boolean assignField(OpenJPAStateManager sm,
                           int field,
                           boolean preFlush)
Description copied from interface: StoreManager
Assign a value to the given field. Return false if the value cannot be assigned because a flush is required (for example, the field value is determined by the datastore on insert). This method is called the first time a user requests the value of a field with a value-strategy on a new instance before flush.

Specified by:
assignField in interface StoreManager
preFlush - whether this assignment is being requested by the system as part of pre-flush activities, and can be ignored if it is more efficient to assign within StoreManager.flush(java.util.Collection)
See Also:
ImplHelper.generateFieldValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.FieldMetaData)

getManagedType

public Class getManagedType(Object oid)
Description copied from interface: StoreManager
Return the persistent class for the given data store identity value. If the given value is not a datastore identity object, return null.

Specified by:
getManagedType in interface StoreManager

getDataStoreIdType

public Class getDataStoreIdType(ClassMetaData meta)
Description copied from interface: StoreManager
Return the class used by this StoreManager for datastore identity values. The given metadata may be null, in which case the return value should the common datastore identity class for all classes, or null if this store manager does not use a common identity class.

Specified by:
getDataStoreIdType in interface StoreManager

copyDataStoreId

public Object copyDataStoreId(Object oid,
                              ClassMetaData meta)
Description copied from interface: StoreManager
Copy the given object id value. Use the described type of the given metadata, which may be a subclass of the given oid's described type.

Specified by:
copyDataStoreId in interface StoreManager

newDataStoreId

public Object newDataStoreId(Object val,
                             ClassMetaData meta)
Description copied from interface: StoreManager
Create a new unique datastore identity for the given type from the given oid value (presumably pk, stringified oid, or oid instance).

Specified by:
newDataStoreId in interface StoreManager

retainConnection

public void retainConnection()
Override to retain a dedicated connection.

Specified by:
retainConnection in interface StoreManager

releaseConnection

public void releaseConnection()
Override to release previously-retained connection.

Specified by:
releaseConnection in interface StoreManager

getClientConnection

public Object getClientConnection()
Returns null. If your data store can provide a distinct connection object, return it here.

Specified by:
getClientConnection in interface StoreManager

executeExtent

public abstract ResultObjectProvider executeExtent(ClassMetaData meta,
                                                   boolean subs,
                                                   FetchConfiguration fetch)
Create a ResultObjectProvider that can return all instances of type, optionally including subclasses as defined by subclasses. The implementation of the result provider will typically execute some sort of data store query to find all the applicable objects, loop through the results, extracting object IDs from the data, and invoke StoreContext.find(Object,FetchConfiguration,BitSet,Object,int) on each OID. When invoking this method, the first argument is the OID. The second is the given fetch configuration. The third argument is a mask of fields to exclude from loading; it will typically be null. The fourth argument is an object that will be passed through to initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) or load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object), and typically will contain the actual data to load. For example, for a JDBC-based store manager, this might be the result set that is being iterated over. If this argument is null, then the initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object) or load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object) method will have to issue another command to the data store in order to fetch the data to be loaded.

Specified by:
executeExtent in interface StoreManager

newQuery

public StoreQuery newQuery(String language)
Description copied from interface: StoreManager
Return a query implementation suitable for this store. If the query is iterated within a data store transaction, returned instances should be locked. Return null if this store does not support native execution of the given language. OpenJPA can execute JPQL in memory even without back end support.

Specified by:
newQuery in interface StoreManager
Parameters:
language - the query language

newFetchConfiguration

public FetchConfiguration newFetchConfiguration()
Description copied from interface: StoreManager
Return a fetch configuration suitable for this runtime. Typically will be or extend FetchConfigurationImpl.

Specified by:
newFetchConfiguration in interface StoreManager

compareVersion

public int compareVersion(OpenJPAStateManager state,
                          Object v1,
                          Object v2)
Casts v1 and v2 to Comparable, and invokes v1.compareTo (v2). If v1 is less than v2, returns StoreManager.VERSION_EARLIER. If the same, returns StoreManager.VERSION_SAME. Otherwise, returns StoreManager.VERSION_LATER. If either v1 or v2 are null, returns StoreManager.VERSION_DIFFERENT.

Specified by:
compareVersion in interface StoreManager
Parameters:
state - the state manager for the object
v1 - the first version object to compare
v2 - the second version object to compare
Returns:

getDataStoreIdSequence

public Seq getDataStoreIdSequence(ClassMetaData forClass)
Returns the system-configured sequence. To use some other sort of datastore identifier (a GUID, string, or someting of that nature), override getManagedType(java.lang.Object), getDataStoreIdType(org.apache.openjpa.meta.ClassMetaData), copyDataStoreId(java.lang.Object, org.apache.openjpa.meta.ClassMetaData), newDataStoreId(java.lang.Object, org.apache.openjpa.meta.ClassMetaData).

Specified by:
getDataStoreIdSequence in interface StoreManager

getValueSequence

public Seq getValueSequence(FieldMetaData forField)
Returns null.

Specified by:
getValueSequence in interface StoreManager

cancelAll

public boolean cancelAll()
Returns false. If your data store supports cancelling queries, this method should cancel any currently-running queries and return true if any were cancelled.

Specified by:
cancelAll in interface StoreManager
Returns:
true if any statements cancelled, false otherwise

close

public void close()
Description copied from interface: StoreManager
Free any resources this store manager is using.

Specified by:
close in interface StoreManager
Specified by:
close in interface Closeable

flush

protected abstract Collection flush(Collection pNew,
                                    Collection pNewUpdated,
                                    Collection pNewFlushedDeleted,
                                    Collection pDirty,
                                    Collection pDeleted)
Responsible for writing modifications happened back to the data store. If you do not remove the OpenJPAConfiguration.OPTION_INC_FLUSH option in getUnsupportedOptions(), this will be called only once at the end of a transaction. Otherwise, it may be called periodically throughout the course of a transaction. If this store manager supports optimistic transactions, datastore version information should be updated during flush, and the state manager's version indicator should be updated through the OpenJPAStateManager.setNextVersion(java.lang.Object) method. This method will only be invoked if there are meaningful changes to store. This differs from the behavior of StoreManager.flush(java.util.Collection), which may be invoked with a collection of objects in states that do not require any datastore action (for example, objects in the transient-transactional state).

Parameters:
pNew - Objects that should be added to the store, and that have not previously been flushed.
pNewUpdated - New objects that have been modified since they were initially flushed. These were in persistentNew in an earlier flush invocation.
pNewFlushedDeleted - New objects that have been deleted since they were initially flushed. These were in persistentNew in an earlier flush invocation.
pDirty - Objects that were loaded from the data store and have since been modified.
pDeleted - Objects that were loaded from the data store and have since been deleted. These may have been in a previous flush invocation's persistentDirty list.
Returns:
a collection of exceptions encountered during flushing.

newConfiguration

protected OpenJPAConfiguration newConfiguration()
Return a new configuration instance for this runtime. Configuration data is maintained at the factory level and is available to all OpenJPA components; therefore it is a good place to maintain shared resources such as connection pools, etc.


getUnsupportedOptions

protected Collection getUnsupportedOptions()
Returns a set of option names that this store manager does not support. By default, returns the following:


getPlatform

protected String getPlatform()
Returns a string name to identify the platform of this store manager. Returns the class name of this store manager by default.



Copyright © 2006-2007 Apache Software Foundation. All Rights Reserved.