blackboard.persist
Class BbPersistenceManager

java.lang.Object
  blackboard.persist.BbPersistenceManager

public class BbPersistenceManager
extends java.lang.Object

The BbPersistenceManager class is the central provider of both loader and persister implementation instances in the persistence framework.

The BbPersistenceManager is created specific to a particular Container and thus returns only loader/persister implementations specific to that container. If cross-container loading/persisting is required, multiple instances of BbPersistenceManager (one for each container) should be created.

Since:

Bb 5.5

Version:

$Revision: #1 $ $Date: 2005/06/27 $

Method Summary

void	addConfigurationBindings(java.io.InputStream in) Adds new persister/loader bindings to this pm's config.
void	addConfigurationBindings(java.lang.String filePath) Adds new persister/loader bindings to this pm's config.
Id	generateId(DataType dataType, int nKey1) Generates an Id instance specific to the Container associated with this persistence manager.
Id	generateId(DataType dataType, int nKey1, int nKey2) Generates an Id instance specific to the Container associated with this persistence manager.
Id	generateId(DataType dataType, java.lang.String strKey) Generates an Id instance specific to the Container associated with this persistence manager.
Cache	getCache() Returns the Cache associated with this persistence manager.
Container	getContainer() Returns the Container associated with this persistence manager.
PersistenceContext	getContext() Returns the PersistenceContext associated with this persistence manager.
static BbPersistenceManager	getInstance(Container targetContainer) Returns an instance of BbPersistenceManager associated with the given target container.
static BbPersistenceManager	getInstance(Container targetContainer, PersistenceContext context) Returns an instance of BbPersistenceManager associated with the given target container and persistence content.
Loader	getLoader(java.lang.String loaderType) Returns a loader implementation as specified by the given type value and using the default AppVersion specifier.
Loader	getLoader(java.lang.String loaderType, AppVersion appVersion) Returns a loader implementation as specified by the given type value and using the provided AppVersion specifier.
LogService	getLogService() Returns the LogService for this persistence manager.
Persister	getPersister(java.lang.String persisterType) Returns a persister implementation as specified by the given type value and using the default AppVersion specifier.
Persister	getPersister(java.lang.String persisterType, AppVersion appVersion) Returns a persister implementation as specified by the given type value and using the provided AppVersion specifier.
protected void	initLoadersAndPersisters() Initialize loaders/persisters
boolean	isValidId(Id id) Convenience method to determines if the provided Id is a "valid" Id for this BbPersistenceManager's Container .
void	refreshLoader(java.lang.String loaderType) Method to signal the cache for the specified type to refresh from the database.
protected void	runCacheUpdate() Performs an update for caching loaders that rely on signalling.
void	runDbQuery(BbQuery query) Convenience method for executing a query on the persistence manager's associated database using a connection obtained through this persistence manager's database context.
void	runDbQuery(BbQuery query, java.sql.Connection con) Convenience method for executing a query on the persistence manager's associated database using the supplied connection.

Methods inherited from class java.lang.Object

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

Method Detail

initLoadersAndPersisters

protected void initLoadersAndPersisters()
                                 throws InitializationException

Initialize loaders/persisters

Throws:

InitializationException

getInstance

public static BbPersistenceManager getInstance(Container targetContainer)
                                        throws InitializationException

Returns an instance of BbPersistenceManager associated with the given target container.

Parameters:

targetContainer - the Container with which the returned persistence manager should be associated

Returns:

an instance of BbPersistenceManager associated with the given Container

Throws:

InitializationException

getInstance

public static BbPersistenceManager getInstance(Container targetContainer,
                                               PersistenceContext context)
                                        throws InitializationException

Returns an instance of BbPersistenceManager associated with the given target container and persistence content.

Parameters:

targetContainer - the Container with which the returned persistence manager should be associated.

context - the PersistenceContext with which the returned persistence manager should be associated.

Returns:

an instance of BbPersistenceManager associated with the given Container and PersistenceContext

Throws:

InitializationException

getContainer

public final Container getContainer()

Returns the Container associated with this persistence manager.

Returns:

the Container associated with this persistence manager when it was initially created.

getCache

public final Cache getCache()

Returns the Cache associated with this persistence manager.

Returns:

the Cache associated with this persistence manager when it was initially created.

getContext

public final PersistenceContext getContext()

Returns the PersistenceContext associated with this persistence manager.

Returns:

the PersistenceContext associated with this persistence manager when it was initially created.

getLogService

public final LogService getLogService()

Returns the LogService for this persistence manager.

Returns:

the LogService associated with this persistence manager

getLoader

public final Loader getLoader(java.lang.String loaderType)
                       throws PersistenceException

Returns a loader implementation as specified by the given type value and using the default AppVersion specifier. The default version is the one contained in the PersistenceContext associated with this BbPersistenceManager. If the default AppVersion is not appropriate use getLoader(String,AppVersion).

Parameters:

loaderType - a String specifying the loader that should be returned

Returns:

a loader instance capable of loading objects of the specified loaderType and the default AppVersion

Throws:

PersistenceException - if an errors occurs while trying to retrieve a loader instance for the given type

getLoader

public final Loader getLoader(java.lang.String loaderType,
                              AppVersion appVersion)
                       throws PersistenceException

Returns a loader implementation as specified by the given type value and using the provided AppVersion specifier. This can be useful because it gives a great deal of flexibility, allowing a caller to load multiple versions of a given data object from a container all using the same instance of a BbPersistenceManager.

Parameters:

loaderType - a String specifying the loader that should be returned

appVersion - an AppVersion specifying the version information for the loader that should be returned

Returns:

a loader instance capable of loading objects of the specified loaderType and the given AppVersion

Throws:

PersistenceException - if an errors occurs while trying to retrieve a loader instance for the given type

getPersister

public final Persister getPersister(java.lang.String persisterType)
                             throws PersistenceException

Returns a persister implementation as specified by the given type value and using the default AppVersion specifier. The default version is the one contained in the PersistenceContext associated with this BbPersistenceManager. If the default AppVersion is not appropriate use getPersister(String,AppVersion).

Parameters:

persisterType - a String specifying the persister that should be returned

Returns:

a persister instance capable of persisting objects of the specified persisterType and the default AppVersion

Throws:

PersistenceException - if an errors occurs while trying to retrieve a persister instance for the given type

getPersister

public final Persister getPersister(java.lang.String persisterType,
                                    AppVersion appVersion)
                             throws PersistenceException

Returns a persister implementation as specified by the given type value and using the provided AppVersion specifier. This can be useful because it gives a great deal of flexibility, allowing a caller to load multiple versions of a given data object from a container all using the same instance of a BbPersistenceManager.

Parameters:

persisterType - a String specifying the persister that should be returned

appVersion - an AppVersion specifying the version information for the persister that should be returned

Returns:

a persister instance capable of persisting objects of the specified persisterType and the given AppVersion

Throws:

PersistenceException - if an errors occurs while trying to retrieve a persister instance for the given type

generateId

public Id generateId(DataType dataType,
                     java.lang.String strKey)
              throws PersistenceException

Generates an Id instance specific to the Container associated with this persistence manager. The format of the provided string is determined by the container type and should be of the form produced by the toExternalString() method on the Ids generated through the container. The resulting Id will be valid to use in a load operation on this persistence manager.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

strKey - the String value to use when generating the key value of the Id instance

Returns:

an Id implementation instance, appropriate to the Container associated with this persistence manager, whose key value is generated from the given value

Throws:

PersistenceException - if the target container does not support the creation of an Id using the given key argument

See Also:

DatabaseContainer.generateId(DataType,String), XmlContainer#generateId(DataType,String), Id.toExternalString()

generateId

public Id generateId(DataType dataType,
                     int nKey1,
                     int nKey2)
              throws PersistenceException

Generates an Id instance specific to the Container associated with this persistence manager. The key value created from the provided integer key values is determined by the container type. The resulting Id will be valid to use in a load operation on this persistence manager.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

nKey1 - an integer value to use when generating the key value of the Id instance

nKey2 - another integer value to use when generating the key value of the Id instance

Returns:

an Id implementation instance, appropriate to the Container associated with this persistence manager, whose key value is generated from the given integer values

Throws:

PersistenceException - if the target container does not support the creation of an Id using the given key arguments

See Also:

DatabaseContainer.generateId(DataType,int,int), XmlContainer#generateId(DataType,int,int)

generateId

public Id generateId(DataType dataType,
                     int nKey1)
              throws PersistenceException

Generates an Id instance specific to the Container associated with this persistence manager. The key value created from the provided integer key values is determined by the container type. The resulting Id will be valid to use in a load operation on this persistence manager.

Parameters:

dataType - the DataType of the object that the generated Id instance will refer to

nKey1 - an integer value to use when generating the key value of the Id instance

Returns:

an Id implementation instance, appropriate to the Container associated with this persistence manager, whose key value is generated from the given integer values

Throws:

PersistenceException - if the target container does not support the creation of an Id using the given key arguments

See Also:

DatabaseContainer.generateId(DataType,int,int), XmlContainer#generateId(DataType,int,int)

isValidId

public boolean isValidId(Id id)

Convenience method to determines if the provided Id is a "valid" Id for this BbPersistenceManager's Container .

An Id is considered valid for a Container if it is "set" (see Id.isSet()), if it originates from the container, and if it is an instance of the appropriate Id subclass for the container.

Parameters:

id - the Id to examine for validity

Returns:

true if the provided id is a valid id for the container, false otherwise

runDbQuery

public void runDbQuery(BbQuery query)
                throws PersistenceException

Convenience method for executing a query on the persistence manager's associated database using a connection obtained through this persistence manager's database context. The query is initialized, executed, and closed.

Parameters:

query - the BbQuery that should be executed

Throws:

PersistenceExceptino - thrown if an error occurs during query execution

PersistenceException

runDbQuery

public void runDbQuery(BbQuery query,
                       java.sql.Connection con)
                throws PersistenceException

Convenience method for executing a query on the persistence manager's associated database using the supplied connection. The query is initialized, executed, and closed.

Parameters:

query - the BbQuery that should be executed

con - the Connection to execute the query on

Throws:

PersistenceExceptino - thrown if an error occurs during query execution

PersistenceException

addConfigurationBindings

public void addConfigurationBindings(java.lang.String filePath)
                              throws InitializationException

Adds new persister/loader bindings to this pm's config. Impl classes must be in system class path.

Parameters:

filePath - Target file path for config xml.

Throws:

InitializationException

addConfigurationBindings

public void addConfigurationBindings(java.io.InputStream in)
                              throws InitializationException

Adds new persister/loader bindings to this pm's config. Impl classes must be in system class path.

Parameters:

in - An input stream from which to read the xml.

Throws:

InitializationException

runCacheUpdate

protected void runCacheUpdate()

Performs an update for caching loaders that rely on signalling. First it retrieves the times for all of the keys, then loops over cache tokens, comparing the in-memory timestamp with the loaded timestamp. If the loaded timestamp is greater, a refresh is performed, and the in-memory timestamp synchronized with the stored timestamp.

refreshLoader

public void refreshLoader(java.lang.String loaderType)
                   throws PersistenceException

Method to signal the cache for the specified type to refresh from the database. This method does not perform an actual reload; it simply notifies the cache

Parameters:

loaderType - Key for the loader to actually refresh; this in turn is used to find the actual cache key.

Throws:

PersistenceException