org.jpox.store
Class AbstractStoreManager

java.lang.Object
  org.jpox.store.AbstractStoreManager

All Implemented Interfaces:

StoreManager

Direct Known Subclasses:

MappedStoreManager

public abstract class AbstractStoreManager
extends java.lang.Object
implements StoreManager

An abstract representation of a Store Manager. Manages the persistence of objects to the store. Will be implemented for the type of datastore (RDBMS, ODBMS, OLAP) in question. The store manager's responsibilities include:

• Creating and/or validating datastore tables according to the persistent classes being accessed by the application.
• Serving as the primary intermediary between StateManagers and the database.
• Serving as the base Extent and Query factory.

A store manager's knowledge of its contents is typically not complete. It knows about the classes that it has encountered in its lifetime. The PersistenceManager can make the StoreManager aware of a class, and can check if the StoreManager knows about a particular class. The Auto-Start mechanism provides a way of inheriting knowledge from the last time the store was used.

Version:

$Revision: 1.180 $

Field Summary

protected java.lang.String	autoStartMechanism Name of the AutoStart mechanism.
protected boolean	fixedDatastore Whether this datastore is fixed (no mods to datastore classes allowed).
protected static Localiser	LOCALISER Localiser for messages.
protected java.lang.String	nontxConnectionFactoryName Name of non-transactional connection factory (null if not present).
protected OMFContext	omfContext ObjectManagerFactory context.
protected StorePersistenceHandler	persistenceHandler Persistence handler.
protected PoidManager	poidManager Manager for identity generation.
protected boolean	readOnlyDatastore Whether this datastore is read only.
protected java.lang.String	readOnlyDatastoreAction What should happen if read-only and an update is invoked.
protected StoreSchemaHandler	schemaHandler Schema handler.
protected AutoStartMechanism	starter Auto-Start mechanism to use.
protected boolean	starterInitialised Whether the AutoStart mechanism is initialised
protected StoreDataManager	storeDataMgr Manager for the data definition in the datastore.
protected java.lang.String	storeManagerKey Key for this StoreManager e.g "rdbms", "db4o"
protected StoreManagerRuntime	storeManagerRuntime StoreManager Runtime.
protected java.lang.String	txConnectionFactoryName Name of transactional connection factory.

Constructor Summary

protected

AbstractStoreManager(java.lang.String key, ClassLoaderResolver clr, OMFContext omfContext) Constructor for a new StoreManager.

Method Summary

void	addClass(java.lang.String className, ClassLoaderResolver clr) Method to add a class to the managed list for this datastore manager.
void	addClasses(java.lang.String[] classNames, ClassLoaderResolver clr) Add classes to the persistence model for the datastore.
abstract void	addClasses(java.lang.String[] classes, ClassLoaderResolver clr, java.io.Writer writer, boolean completeDdl) Add classes to the persistence model for the datastore.
protected void	clearAutoStarter() Method to clear the Auto-Starter status.
void	close() Release of resources.
protected void	deregisterAllStoreData() Method to deregister all existing store data so that we are managing nothing.
ApiAdapter	getApiAdapter() Accessor for the API adapter.
AutoStartMechanism	getAutoStartMechanism() Accessor for the AutoStartMechanism
Store	getBackingStoreForField(ClassLoaderResolver clr, AbstractMemberMetaData fmd, java.lang.Class type) Accessor for the backing store for the specified field.
java.lang.String	getClassNameForObjectID(java.lang.Object id, ClassLoaderResolver clr, ObjectManager om) Returns the class corresponding to the given object identity.
ManagedConnection	getConnection(ObjectManager om) Accessor for a transactional connection for the specified ObjectManager, using its current transaction.
abstract java.util.Date	getDatastoreDate() Get the date/time of the datastore.
abstract Extent	getExtent(ObjectManager om, java.lang.Class c, boolean subclasses) Interface to getting an Extent for a class.
abstract JPOXConnection	getJPOXConnection(ObjectManager om) Method to return a JPOX connection for the ObjectManager.
JPOXSequence	getJPOXSequence(ObjectManager om, SequenceMetaData seqmd) Method to return a datastore sequence for this datastore matching the passed sequence MetaData.
MetaDataManager	getMetaDataManager()
OMFContext	getOMFContext() Accessor for the context in which this RDBMSManager is running
StorePersistenceHandler	getPersistenceHandler() Accessor for the store persistence handler.
PoidManager	getPoidManager() Accessor for the POIDManager for obtaining sequences.
protected java.util.Properties	getPropertiesForGenerator(AbstractClassMetaData cmd, int absoluteFieldNumber, ObjectManager om, SequenceMetaData seqmd, TableGeneratorMetaData tablegenmd) Method to return the properties to pass to the generator for the specified field.
StoreManagerRuntime	getRuntimeManager() Accessor for the runtime management of this component (if specified as required to the PMF/EMF).
StoreSchemaHandler	getSchemaHandler() Accessor for the store schema handler (if this datastore supports the concept of a schema).
java.lang.String	getStoreManagerKey() Accessor for the key for this store manager.
protected java.lang.String	getStrategyForNative(java.lang.String sequence) Method defining which value-strategy to use when the user specifies "native".
java.lang.Object	getStrategyValue(ObjectManager om, AbstractClassMetaData cmd, int absoluteFieldNumber) Method to retrieve the value for a strategy for a particular field.
protected java.lang.Object	getStrategyValueForGenerator(PoidGenerator generator, ObjectManager om) Accessor for the next value from the specified generator.
java.util.HashSet	getSubClassesForClass(java.lang.String className, boolean includeDescendents, ClassLoaderResolver clr) Utility to return the names of the classes that are known subclasses of the provided class.
java.util.Collection	getSupportedOptions() Accessor for the supported options in string form.
protected void	initialiseAutoStart(java.lang.String mechanism, java.lang.String mode, ClassLoaderResolver clr) Method to initialise the auto-start mechanism, loading up the classes from its store into memory so that we start from where we got to last time.
boolean	isStrategyDatastoreAttributed(IdentityStrategy identityStrategy, boolean datastoreIdentityField) Check if the strategy is attributed by the database when the PersistenceCapable object is inserted into the database
java.lang.String	manageClassForIdentity(java.lang.Object id, ClassLoaderResolver clr) Convenience method to ensure that the class defined by the passed OID/SingleFIeldIdentity is managed by the store.
boolean	managesClass(java.lang.String className) Accessor for whether the specified class is managed currently
void	notifyObjectIsOutdated(StateManager sm) Notifies this store manager that the main memory (RAM, heap) copy of the PC object of the supplied StateManager may not be regarded as valid anymore.
abstract void	outputDatastoreInformation(java.io.PrintStream ps) Method to output the datastore information to the specified PrintStream.
abstract void	outputSchemaInformation(java.io.PrintStream ps) Method to output the schema information to the specified PrintStream.
void	performVersionCheck(StateManager sm, java.lang.Object versionDatastore, VersionMetaData versionMetaData) Perform an optimistic version check on the passed object, against the passed version in the datastore.
protected void	registerStoreData(StoreData data) Method to register some data with the store.
abstract void	removeAllClasses(ClassLoaderResolver clr) Drops all tables in the datastore.
boolean	supportsQueryLanguage(java.lang.String language) Accessor for whether this query language is supported.
boolean	supportsValueStrategy(java.lang.String strategy) Accessor for whether this value strategy is supported.
boolean	usesDatastoreClass()

Methods inherited from class java.lang.Object

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

Field Detail

LOCALISER

protected static final Localiser LOCALISER

Localiser for messages.

storeManagerKey

protected final java.lang.String storeManagerKey

Key for this StoreManager e.g "rdbms", "db4o"

readOnlyDatastore

protected final boolean readOnlyDatastore

Whether this datastore is read only.

readOnlyDatastoreAction

protected final java.lang.String readOnlyDatastoreAction

What should happen if read-only and an update is invoked.

fixedDatastore

protected final boolean fixedDatastore

Whether this datastore is fixed (no mods to datastore classes allowed).

starter

protected AutoStartMechanism starter

Auto-Start mechanism to use.

starterInitialised

protected boolean starterInitialised

Whether the AutoStart mechanism is initialised

omfContext

protected final OMFContext omfContext

ObjectManagerFactory context.

poidManager

protected final PoidManager poidManager

Manager for identity generation.

storeManagerRuntime

protected StoreManagerRuntime storeManagerRuntime

StoreManager Runtime. Used when providing management of services.

storeDataMgr

protected StoreDataManager storeDataMgr

Manager for the data definition in the datastore.

autoStartMechanism

protected java.lang.String autoStartMechanism

Name of the AutoStart mechanism.

persistenceHandler

protected StorePersistenceHandler persistenceHandler

Persistence handler.

schemaHandler

protected StoreSchemaHandler schemaHandler

Schema handler.

txConnectionFactoryName

protected java.lang.String txConnectionFactoryName

Name of transactional connection factory.

nontxConnectionFactoryName

protected java.lang.String nontxConnectionFactoryName

Name of non-transactional connection factory (null if not present).

Constructor Detail

AbstractStoreManager

protected AbstractStoreManager(java.lang.String key,
                               ClassLoaderResolver clr,
                               OMFContext omfContext)

Constructor for a new StoreManager. Stores the basic information required for the datastore management.

Parameters:

key - Key for this StoreManager

clr - the ClassLoaderResolver

omfContext - The corresponding ObjectManagerFactory context.

See Also:

StoreManagerFactory

Method Detail

close

public void close()

Description copied from interface: StoreManager

Release of resources.

Specified by:

close in interface StoreManager

getConnection

public ManagedConnection getConnection(ObjectManager om)

Accessor for a transactional connection for the specified ObjectManager, using its current transaction.

Specified by:

getConnection in interface StoreManager

Parameters:

om - The ObjectManager

Returns:

The Connection

Throws:

JPOXException - Thrown if an error occurs getting the connection

getRuntimeManager

public StoreManagerRuntime getRuntimeManager()

Description copied from interface: StoreManager

Accessor for the runtime management of this component (if specified as required to the PMF/EMF).

Specified by:

getRuntimeManager in interface StoreManager

Returns:

Runtime manager (JMX) for this store

getPersistenceHandler

public StorePersistenceHandler getPersistenceHandler()

Description copied from interface: StoreManager

Accessor for the store persistence handler.

Specified by:

getPersistenceHandler in interface StoreManager

Returns:

Store persistence handler.

getSchemaHandler

public StoreSchemaHandler getSchemaHandler()

Description copied from interface: StoreManager

Accessor for the store schema handler (if this datastore supports the concept of a schema).

Specified by:

getSchemaHandler in interface StoreManager

Returns:

Store schema handler.

getJPOXSequence

public JPOXSequence getJPOXSequence(ObjectManager om,
                                    SequenceMetaData seqmd)

Method to return a datastore sequence for this datastore matching the passed sequence MetaData.

Specified by:

getJPOXSequence in interface StoreManager

Parameters:

om - The Object Manager

seqmd - SequenceMetaData

Returns:

The Sequence

getJPOXConnection

public abstract JPOXConnection getJPOXConnection(ObjectManager om)

Description copied from interface: StoreManager

Method to return a JPOX connection for the ObjectManager.

Specified by:

getJPOXConnection in interface StoreManager

Parameters:

om - ObjectManager

Returns:

The JPOX Connection

getPoidManager

public PoidManager getPoidManager()

Description copied from interface: StoreManager

Accessor for the POIDManager for obtaining sequences.

Specified by:

getPoidManager in interface StoreManager

Returns:

The POID manager for this datastore

getApiAdapter

public ApiAdapter getApiAdapter()

Description copied from interface: StoreManager

Accessor for the API adapter.

Specified by:

getApiAdapter in interface StoreManager

Returns:

API adapter

getStoreManagerKey

public java.lang.String getStoreManagerKey()

Description copied from interface: StoreManager

Accessor for the key for this store manager.

Specified by:

getStoreManagerKey in interface StoreManager

Returns:

StoreManager key

getOMFContext

public OMFContext getOMFContext()

Description copied from interface: StoreManager

Accessor for the context in which this RDBMSManager is running

Specified by:

getOMFContext in interface StoreManager

Returns:

Returns the context.

getMetaDataManager

public MetaDataManager getMetaDataManager()

getDatastoreDate

public abstract java.util.Date getDatastoreDate()

Description copied from interface: StoreManager

Get the date/time of the datastore.

Specified by:

getDatastoreDate in interface StoreManager

Returns:

Date/time of the datastore

registerStoreData

protected void registerStoreData(StoreData data)

Method to register some data with the store. This will also register the data with the starter process.

Parameters:

data - The StoreData to add

deregisterAllStoreData

protected void deregisterAllStoreData()

Method to deregister all existing store data so that we are managing nothing.

outputDatastoreInformation

public abstract void outputDatastoreInformation(java.io.PrintStream ps)
                                         throws java.lang.Exception

Description copied from interface: StoreManager

Method to output the datastore information to the specified PrintStream.

Specified by:

outputDatastoreInformation in interface StoreManager

Parameters:

ps - PrintStream

Throws:

java.lang.Exception - If an error occurs obtaining the datastore info

outputSchemaInformation

public abstract void outputSchemaInformation(java.io.PrintStream ps)
                                      throws java.lang.Exception

Description copied from interface: StoreManager

Method to output the schema information to the specified PrintStream.

Specified by:

outputSchemaInformation in interface StoreManager

Parameters:

ps - PrintStream

Throws:

java.lang.Exception - If an error occurs obtaining the schema info

initialiseAutoStart

protected void initialiseAutoStart(java.lang.String mechanism,
                                   java.lang.String mode,
                                   ClassLoaderResolver clr)
                            throws DatastoreInitialisationException

Method to initialise the auto-start mechanism, loading up the classes from its store into memory so that we start from where we got to last time.

Parameters:

mechanism - Auto-Start mechanism

mode - Mode of operation

clr - The ClassLoaderResolver

Throws:

DatastoreInitialisationException

clearAutoStarter

protected void clearAutoStarter()

Method to clear the Auto-Starter status.

getAutoStartMechanism

public AutoStartMechanism getAutoStartMechanism()

Description copied from interface: StoreManager

Accessor for the AutoStartMechanism

Specified by:

getAutoStartMechanism in interface StoreManager

Returns:

may return null if auto start mechanism is not initialized

managesClass

public boolean managesClass(java.lang.String className)

Description copied from interface: StoreManager

Accessor for whether the specified class is managed currently

Specified by:

managesClass in interface StoreManager

Parameters:

className - The name of the class

Returns:

Whether it is managed

addClass

public void addClass(java.lang.String className,
                     ClassLoaderResolver clr)

Description copied from interface: StoreManager

Method to add a class to the managed list for this datastore manager.

Specified by:

addClass in interface StoreManager

Parameters:

className - Name of the class

clr - The ClassLoaderResolver

addClasses

public abstract void addClasses(java.lang.String[] classes,
                                ClassLoaderResolver clr,
                                java.io.Writer writer,
                                boolean completeDdl)

Description copied from interface: StoreManager

Add classes to the persistence model for the datastore. In the case of an RDBMS, this will map these classes to RDBMS tables. In the case of XML, this will map these classes to XML datafiles.

This method is primarily useful for applications that wish to perform all of their datastore initialization up front, rather than wait for the JPOX runtime to do it on-demand.

Specified by:

addClasses in interface StoreManager

Parameters:

classes - The class(es) to be added.

clr - The ClassLoaderResolver

writer - Optional writer when you just want the DDL for persisting the specified classes

completeDdl - whether complete DDL will be created when writing DDL to a file, or only for missing elements

addClasses

public void addClasses(java.lang.String[] classNames,
                       ClassLoaderResolver clr)

Description copied from interface: StoreManager

Add classes to the persistence model for the datastore. In the case of an RDBMS, this will map these classes to RDBMS tables. In the case of XML, this will map these classes to XML datafiles.

This method is primarily useful for applications that wish to perform all of their datastore initialization up front, rather than wait for the JPOX runtime to do it on-demand.

Specified by:

addClasses in interface StoreManager

Parameters:

classNames - The class(es) to be added.

clr - The ClassLoaderResolver

removeAllClasses

public abstract void removeAllClasses(ClassLoaderResolver clr)

Description copied from interface: StoreManager

Drops all tables in the datastore. This empties the datastore of all datastore objects managed by JPOX. All objects not managed by JPOX are left untouched.

Specified by:

removeAllClasses in interface StoreManager

Parameters:

clr - The ClassLoaderResolver

manageClassForIdentity

public java.lang.String manageClassForIdentity(java.lang.Object id,
                                               ClassLoaderResolver clr)

Description copied from interface: StoreManager

Convenience method to ensure that the class defined by the passed OID/SingleFIeldIdentity is managed by the store.

Specified by:

manageClassForIdentity in interface StoreManager

Parameters:

id - OID

clr - ClassLoader resolver

Returns:

The class name of the class associated to this identity

usesDatastoreClass

public boolean usesDatastoreClass()

getExtent

public abstract Extent getExtent(ObjectManager om,
                                 java.lang.Class c,
                                 boolean subclasses)

Description copied from interface: StoreManager

Interface to getting an Extent for a class.

Specified by:

getExtent in interface StoreManager

Parameters:

om - The Object Manager

c - The class requiring the Extent

subclasses - Whether to include subclasses of 'c'

Returns:

The Extent.

supportsQueryLanguage

public boolean supportsQueryLanguage(java.lang.String language)

Description copied from interface: StoreManager

Accessor for whether this query language is supported.

Specified by:

supportsQueryLanguage in interface StoreManager

Parameters:

language - The language

Returns:

Whether it is supported.

supportsValueStrategy

public boolean supportsValueStrategy(java.lang.String strategy)

Accessor for whether this value strategy is supported.

Specified by:

supportsValueStrategy in interface StoreManager

Parameters:

strategy - The strategy

Returns:

Whether it is supported.

getClassNameForObjectID

public java.lang.String getClassNameForObjectID(java.lang.Object id,
                                                ClassLoaderResolver clr,
                                                ObjectManager om)

Description copied from interface: StoreManager

Returns the class corresponding to the given object identity. If the object is an OID (datastore-identity), return the PC class specified in the identity. If the object is SingleFieldIdentity, return the PC class specified in the identity If the object is an AppID PK, return the PC class that uses it. If the object is a SCOID, return the SCO class. If the object is a PersistenceCapable class, return the class.

Specified by:

getClassNameForObjectID in interface StoreManager

Parameters:

id - The identity of some object.

clr - ClassLoader resolver

om - Object Manager

Returns:

For datastore identity, return the class of the corresponding object. For application identity, return the class of the corresponding object or null if object does not exist.

isStrategyDatastoreAttributed

public boolean isStrategyDatastoreAttributed(IdentityStrategy identityStrategy,
                                             boolean datastoreIdentityField)

Description copied from interface: StoreManager

Check if the strategy is attributed by the database when the PersistenceCapable object is inserted into the database

Specified by:

isStrategyDatastoreAttributed in interface StoreManager

Parameters:

identityStrategy - the identityStrategy

datastoreIdentityField - Whether this is for the surrogate datastore identity field

Returns:

if the object for the strategy is attributed by the database

getStrategyValue

public java.lang.Object getStrategyValue(ObjectManager om,
                                         AbstractClassMetaData cmd,
                                         int absoluteFieldNumber)

Description copied from interface: StoreManager

Method to retrieve the value for a strategy for a particular field.

Specified by:

getStrategyValue in interface StoreManager

Parameters:

om - The Object Manager

cmd - AbstractClassMetaData for the class

absoluteFieldNumber - The field number

Returns:

The value

getStrategyForNative

protected java.lang.String getStrategyForNative(java.lang.String sequence)

Method defining which value-strategy to use when the user specifies "native".

Parameters:

sequence - Sequence name if specified

Returns:

Just returns "increment". Should be overridden by all store managers that have other behaviour.

getStrategyValueForGenerator

protected java.lang.Object getStrategyValueForGenerator(PoidGenerator generator,
                                                        ObjectManager om)

Accessor for the next value from the specified generator. This implementation simply returns generator.next(). Any case where the generator requires datastore connections should override this method.

Parameters:

generator - The generator

om - ObjectManager

Returns:

The next value.

getPropertiesForGenerator

protected java.util.Properties getPropertiesForGenerator(AbstractClassMetaData cmd,
                                                         int absoluteFieldNumber,
                                                         ObjectManager om,
                                                         SequenceMetaData seqmd,
                                                         TableGeneratorMetaData tablegenmd)

Method to return the properties to pass to the generator for the specified field.

Parameters:

cmd - MetaData for the class

absoluteFieldNumber - Number of the field (-1 = datastore identity)

om - Object Manager

seqmd - Any sequence metadata

tablegenmd - Any table generator metadata

Returns:

The properties to use for this field

performVersionCheck

public void performVersionCheck(StateManager sm,
                                java.lang.Object versionDatastore,
                                VersionMetaData versionMetaData)

Description copied from interface: StoreManager

Perform an optimistic version check on the passed object, against the passed version in the datastore.

Specified by:

performVersionCheck in interface StoreManager

Parameters:

sm - StateManager of the object to check

versionDatastore - Version of the object in the datastore

versionMetaData - VersionMetaData to use for checking

getSubClassesForClass

public java.util.HashSet getSubClassesForClass(java.lang.String className,
                                               boolean includeDescendents,
                                               ClassLoaderResolver clr)

Description copied from interface: StoreManager

Utility to return the names of the classes that are known subclasses of the provided class. Actually uses the MetaDataManager for determining what is a subclass since the MetaData is often registered before being needed by the Store.

Specified by:

getSubClassesForClass in interface StoreManager

Parameters:

className - Class for which we search for subclasses.

includeDescendents - Whether to include subclasses of subclasses etc

clr - The ClassLoaderResolver

Returns:

Set of classes that are subclasses of the input class. TODO Use method in MetaDataManager and remove this

notifyObjectIsOutdated

public void notifyObjectIsOutdated(StateManager sm)

Description copied from interface: StoreManager

Notifies this store manager that the main memory (RAM, heap) copy of the PC object of the supplied StateManager may not be regarded as valid anymore. (The most common case is that the state of the PC becomes HOLLOW). This is especially important for object databases employing implicit storing from the main memory to the database (like DB4O). These databases may stop tracking the main memory copy and linking it with its on-disk copy, thus releasing memory. More importantly, these databases then know that the object should be reloaded when it is (maybe even implicitly) accessed again. To be clear: There may be multiple copies of the data of one PC object (from the user perspective), namely a copy in main memory (on the Java heap) and a copy in the database (usually on disk). As there may be multiple copies, some of these copies may be outdated or invalid. In case such a copy is to be accessed, its contents should not be used. Rather than that, the outdated copy should be overwritten by an authorative copy. This method marks the main memory copy of the object (on the Java heap) to be outdated in that sense.

Specified by:

notifyObjectIsOutdated in interface StoreManager

getBackingStoreForField

public Store getBackingStoreForField(ClassLoaderResolver clr,
                                     AbstractMemberMetaData fmd,
                                     java.lang.Class type)

Description copied from interface: StoreManager

Accessor for the backing store for the specified field. Override it if the store needs this

Specified by:

getBackingStoreForField in interface StoreManager

Parameters:

clr - ClassLoader resolver

fmd - MetaData for the field/property

type - Type

Returns:

Backing store

getSupportedOptions

public java.util.Collection getSupportedOptions()

Accessor for the supported options in string form.

Specified by:

getSupportedOptions in interface StoreManager