org.jpox.store
Interface StoreManager

All Known Implementing Classes:

AbstractStoreManager, FederationManager, MappedStoreManager

public interface StoreManager

Interface defining management of a datastore. To be implemented by all new datastore support. Please use AbstractStoreManager and extend it.

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.
void	addClasses(java.lang.String[] classes, ClassLoaderResolver clr, java.io.Writer writer, boolean completeDdl) Add classes to the persistence model for the datastore.
void	close() Release of resources.
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.
java.util.Date	getDatastoreDate() Get the date/time of the datastore.
Extent	getExtent(ObjectManager om, java.lang.Class c, boolean subclasses) Interface to getting an Extent for a class.
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.
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.
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.
java.lang.Object	getStrategyValue(ObjectManager om, AbstractClassMetaData cmd, int absoluteFieldNumber) Method to retrieve the value for a strategy for a particular field.
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
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.
void	outputDatastoreInformation(java.io.PrintStream ps) Method to output the datastore information to the specified PrintStream.
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.
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.

Method Detail

getSupportedOptions

java.util.Collection getSupportedOptions()

Accessor for the supported options in string form

close

void close()

Release of resources.

getRuntimeManager

StoreManagerRuntime getRuntimeManager()

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

Returns:

Runtime manager (JMX) for this store

getPersistenceHandler

StorePersistenceHandler getPersistenceHandler()

Accessor for the store persistence handler.

Returns:

Store persistence handler.

getSchemaHandler

StoreSchemaHandler getSchemaHandler()

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

Returns:

Store schema handler.

getJPOXSequence

JPOXSequence getJPOXSequence(ObjectManager om,
                             SequenceMetaData seqmd)

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

Parameters:

om - The Object Manager

seqmd - SequenceMetaData

Returns:

The Sequence

getJPOXConnection

JPOXConnection getJPOXConnection(ObjectManager om)

Method to return a JPOX connection for the ObjectManager.

Parameters:

om - ObjectManager

Returns:

The JPOX Connection

getConnection

ManagedConnection getConnection(ObjectManager om)

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

Parameters:

om - The ObjectManager

Returns:

The Connection

Throws:

JPOXException - Thrown if an error occurs getting the connection

getPoidManager

PoidManager getPoidManager()

Accessor for the POIDManager for obtaining sequences.

Returns:

The POID manager for this datastore

getApiAdapter

ApiAdapter getApiAdapter()

Accessor for the API adapter.

Returns:

API adapter

getStoreManagerKey

java.lang.String getStoreManagerKey()

Accessor for the key for this store manager.

Returns:

StoreManager key

getOMFContext

OMFContext getOMFContext()

Accessor for the context in which this RDBMSManager is running

Returns:

Returns the context.

getDatastoreDate

java.util.Date getDatastoreDate()

Get the date/time of the datastore.

Returns:

Date/time of the datastore

outputDatastoreInformation

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

Method to output the datastore information to the specified PrintStream.

Parameters:

ps - PrintStream

Throws:

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

outputSchemaInformation

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

Method to output the schema information to the specified PrintStream.

Parameters:

ps - PrintStream

Throws:

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

getAutoStartMechanism

AutoStartMechanism getAutoStartMechanism()

Accessor for the AutoStartMechanism

Returns:

may return null if auto start mechanism is not initialized

managesClass

boolean managesClass(java.lang.String className)

Accessor for whether the specified class is managed currently

Parameters:

className - The name of the class

Returns:

Whether it is managed

addClass

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

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

Parameters:

className - Name of the class

clr - The ClassLoaderResolver

addClasses

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

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.

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

Throws:

DatastoreValidationException - If there is some mismatch between the current datastore contents and those necessary to enable persistence of the given classes.

addClasses

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

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.

Parameters:

classNames - The class(es) to be added.

clr - The ClassLoaderResolver

Throws:

DatastoreValidationException - If there is some mismatch between the current datastore contents and those necessary to enable persistence of the given classes.

removeAllClasses

void removeAllClasses(ClassLoaderResolver clr)

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.

Parameters:

clr - The ClassLoaderResolver

manageClassForIdentity

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.

Parameters:

id - OID

clr - ClassLoader resolver

Returns:

The class name of the class associated to this identity

Throws:

JPOXUserException - if the identity is assigned to the wrong class

getExtent

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

Interface to getting an Extent for a class.

Parameters:

om - The Object Manager

c - The class requiring the Extent

subclasses - Whether to include subclasses of 'c'

Returns:

The Extent.

supportsQueryLanguage

boolean supportsQueryLanguage(java.lang.String language)

Accessor for whether this query language is supported.

Parameters:

language - The language

Returns:

Whether it is supported.

supportsValueStrategy

boolean supportsValueStrategy(java.lang.String strategy)

Accessor for whether this value strategy is supported.

Parameters:

strategy - The strategy

Returns:

Whether it is supported.

getClassNameForObjectID

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

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.

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.

Throws:

java.lang.ClassCastException - If the type of ID is not recognized (OID or SCOID).

isStrategyDatastoreAttributed

boolean isStrategyDatastoreAttributed(IdentityStrategy identityStrategy,
                                      boolean datastoreIdentityField)

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

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

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

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

Parameters:

om - The Object Manager

cmd - AbstractClassMetaData for the class

absoluteFieldNumber - The field number

Returns:

The value

performVersionCheck

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.

Parameters:

sm - StateManager of the object to check

versionDatastore - Version of the object in the datastore

versionMetaData - VersionMetaData to use for checking

Throws:

JPOXUserException - thrown when an invalid strategy is specified

JPOXOptimisticException - thrown when the version check fails

getSubClassesForClass

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. Actually uses the MetaDataManager for determining what is a subclass since the MetaData is often registered before being needed by the Store.

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

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. (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.

getBackingStoreForField

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

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

Parameters:

clr - ClassLoader resolver

fmd - MetaData for the field/property

type - Type

Returns:

Backing store

Throws:

IncompatibleFieldTypeException - raises the exception if the field is not compatible if the store

java.lang.UnsupportedOperationException - if BackingStore is not supported