org.cougaar.core.persist
Class DatabasePersistence

java.lang.Object
  org.cougaar.core.persist.PersistencePluginAdapter
      org.cougaar.core.persist.DatabasePersistence

All Implemented Interfaces:

PersistencePlugin

public class DatabasePersistence
extends PersistencePluginAdapter
implements PersistencePlugin

This PersistencePlugin saves blackboard objects in a database. It saves and restores persistence deltas in RDB tables.

We store the deltas for each agent in a separate table named after the agent: delta_<agentName>. The table has three columns:

 
 seqno  -- has an INTEGER delta sequence number
 active -- has a CHAR indicating the kind of delta stored
           x -- full delta (all data)
           t -- incremental delta
           a -- archive delta (full but not active)
           f -- inactive incremental
   The above codes were selected for backward compatibility with the
   former t/f meaning active was true/false
 data   -- has a LONG RAW with the serialized data
 

System Properties:

org.cougaar.core.persistence.database.url	Specify the database to use for DatabasePersistence.
org.cougaar.core.persistence.database.user	Specify the database user to use for DatabasePersistence.
org.cougaar.core.persistence.database.password	Specify the database password to use for DatabasePersistence.
org.cougaar.core.persistence.database.driver	Specify the database driver to use for DatabasePersistence.

Field Summary

static java.lang.String[]	NAMES
static java.lang.String	PERSISTENCE_ARCHIVE_COUNT_NAME
static java.lang.String	PERSISTENCE_ARCHIVE_COUNT_PREFIX
static java.lang.String	PERSISTENCE_ARCHIVE_COUNT_PROP
static java.lang.String	PERSISTENCE_ARCHIVE_NUMBER_NAME
static java.lang.String	PERSISTENCE_ARCHIVE_NUMBER_PREFIX
static java.lang.String	PERSISTENCE_ARCHIVE_NUMBER_PROP
static java.lang.String	PERSISTENCE_CLASS_NAME
static java.lang.String	PERSISTENCE_CLASS_PREFIX
static java.lang.String	PERSISTENCE_CLASS_PROP
static java.lang.String	PERSISTENCE_CONSOLIDATION_PERIOD_NAME
static java.lang.String	PERSISTENCE_CONSOLIDATION_PERIOD_PREFIX
static java.lang.String	PERSISTENCE_CONSOLIDATION_PERIOD_PROP
static java.lang.String	PERSISTENCE_DB_DRIVER_NAME
static java.lang.String	PERSISTENCE_DB_DRIVER_PREFIX
static java.lang.String	PERSISTENCE_DB_DRIVER_PROP
static java.lang.String	PERSISTENCE_DB_INTDEF_NAME
static java.lang.String	PERSISTENCE_DB_INTDEF_PREFIX
static java.lang.String	PERSISTENCE_DB_INTDEF_PROP
static java.lang.String	PERSISTENCE_DB_LONGBINARYDEF_NAME
static java.lang.String	PERSISTENCE_DB_LONGBINARYDEF_PREFIX
static java.lang.String	PERSISTENCE_DB_LONGBINARYDEF_PROP
static java.lang.String	PERSISTENCE_DB_PASSWORD_NAME
static java.lang.String	PERSISTENCE_DB_PASSWORD_PREFIX
static java.lang.String	PERSISTENCE_DB_PASSWORD_PROP
static java.lang.String	PERSISTENCE_DB_URL_NAME
static java.lang.String	PERSISTENCE_DB_URL_PREFIX
static java.lang.String	PERSISTENCE_DB_URL_PROP
static java.lang.String	PERSISTENCE_DB_USER_NAME
static java.lang.String	PERSISTENCE_DB_USER_PREFIX
static java.lang.String	PERSISTENCE_DB_USER_PROP
static java.lang.String	PERSISTENCE_DISABLE_WRITE_NAME
static java.lang.String	PERSISTENCE_DISABLE_WRITE_PREFIX
static java.lang.String	PERSISTENCE_DISABLE_WRITE_PROP
static java.lang.String	PERSISTENCE_ENABLE_NAME
static java.lang.String	PERSISTENCE_ENABLE_PREFIX
static java.lang.String	PERSISTENCE_ENABLE_PROP
static java.lang.String	PERSISTENCE_INTERVAL_NAME
static java.lang.String	PERSISTENCE_INTERVAL_PREFIX
static java.lang.String	PERSISTENCE_INTERVAL_PROP
static java.lang.String	PERSISTENCE_PARAMETERS_NAME
static java.lang.String	PERSISTENCE_PARAMETERS_PREFIX
static java.lang.String	PERSISTENCE_PARAMETERS_PROP
static java.lang.String	PERSISTENCE_PROP_PREFIX
static java.lang.String	PERSISTENCE_ROOT_NAME
static java.lang.String	PERSISTENCE_ROOT_PREFIX
static java.lang.String	PERSISTENCE_ROOT_PROP
static java.lang.String	PERSISTENCE_VERIFY_JAVA_IO_PATCH_NAME
static java.lang.String	PERSISTENCE_VERIFY_JAVA_IO_PATCH_PREFIX
static java.lang.String	PERSISTENCE_VERIFY_JAVA_IO_PATCH_PROP

Fields inherited from class org.cougaar.core.persist.PersistencePluginAdapter

archiveCount, consolidationPeriod, controlNames, emptyOMCRangeList, emptyStringArray, name, params, persistenceInterval, pps, writable

Constructor Summary

DatabasePersistence()

Method Summary

void	abortOutputStream(SequenceNumbers retainNumbers) Clean up after output was aborted.
void	cleanupArchive() Delete old archives
void	cleanupOldDeltas(SequenceNumbers cleanupNumbers) Cleanup old deltas as specified by cleanupNumbers.
void	finishInputStream(int deltaNumber) Clean up after closing the input stream
void	finishOutputStream(SequenceNumbers retainNumbers, boolean full) Clean up after closing the output stream.
java.sql.Connection	getDatabaseConnection(java.lang.Object locker) Override adapter version since we actually have a database connection we can return instead of throwing an exception.
protected void	handleParameter(java.lang.String param)
void	init(PersistencePluginSupport pps, java.lang.String name, java.lang.String[] params, boolean deleteOldPersistence) Initialize the plugin with PersistencePluginSupport and parameters.
java.io.InputStream	openInputStream(int deltaNumber) Open an InputStream from which a persistence delta can be read.
java.io.OutputStream	openOutputStream(int deltaNumber, boolean full) Open an OutputStream onto which a persistence delta can be written.
SequenceNumbers[]	readSequenceNumbers(java.lang.String suffix) Read the specified set of sequence numbers.
void	releaseDatabaseConnection(java.lang.Object locker) Release the connection to the database into which persistence deltas are being written for coordinated transaction management.
DataProtectionKey	retrieveDataProtectionKey(int deltaNumber) Retrieve an encrypted key for a particular delta number
void	storeDataProtectionKey(int deltaNumber, DataProtectionKey key) Store an encrypted key for a particular delta number

Methods inherited from class org.cougaar.core.persist.PersistencePluginAdapter

checkOwnership, getConsolidationPeriod, getControlNames, getControlValues, getName, getParam, getParamCount, getPersistenceInterval, init, isWritable, lockOwnership, parseParamValue, setConsolidationPeriod, setControl, setPersistenceInterval, setWritable, unlockOwnership

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.cougaar.core.persist.PersistencePlugin

checkOwnership, getConsolidationPeriod, getControlNames, getControlValues, getName, getParam, getParamCount, getPersistenceInterval, isWritable, lockOwnership, setConsolidationPeriod, setControl, setPersistenceInterval, setWritable, unlockOwnership

Field Detail

PERSISTENCE_PROP_PREFIX

public static final java.lang.String PERSISTENCE_PROP_PREFIX

See Also:

Constant Field Values

PERSISTENCE_ARCHIVE_COUNT_NAME

public static final java.lang.String PERSISTENCE_ARCHIVE_COUNT_NAME

See Also:

Constant Field Values

PERSISTENCE_CONSOLIDATION_PERIOD_NAME

public static final java.lang.String PERSISTENCE_CONSOLIDATION_PERIOD_NAME

See Also:

Constant Field Values

PERSISTENCE_INTERVAL_NAME

public static final java.lang.String PERSISTENCE_INTERVAL_NAME

See Also:

Constant Field Values

PERSISTENCE_ENABLE_NAME

public static final java.lang.String PERSISTENCE_ENABLE_NAME

See Also:

Constant Field Values

PERSISTENCE_VERIFY_JAVA_IO_PATCH_NAME

public static final java.lang.String PERSISTENCE_VERIFY_JAVA_IO_PATCH_NAME

See Also:

Constant Field Values

PERSISTENCE_DISABLE_WRITE_NAME

public static final java.lang.String PERSISTENCE_DISABLE_WRITE_NAME

See Also:

Constant Field Values

PERSISTENCE_ARCHIVE_NUMBER_NAME

public static final java.lang.String PERSISTENCE_ARCHIVE_NUMBER_NAME

See Also:

Constant Field Values

PERSISTENCE_CLASS_NAME

public static final java.lang.String PERSISTENCE_CLASS_NAME

See Also:

Constant Field Values

PERSISTENCE_ROOT_NAME

public static final java.lang.String PERSISTENCE_ROOT_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_DRIVER_NAME

public static final java.lang.String PERSISTENCE_DB_DRIVER_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_URL_NAME

public static final java.lang.String PERSISTENCE_DB_URL_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_USER_NAME

public static final java.lang.String PERSISTENCE_DB_USER_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_PASSWORD_NAME

public static final java.lang.String PERSISTENCE_DB_PASSWORD_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_INTDEF_NAME

public static final java.lang.String PERSISTENCE_DB_INTDEF_NAME

See Also:

Constant Field Values

PERSISTENCE_DB_LONGBINARYDEF_NAME

public static final java.lang.String PERSISTENCE_DB_LONGBINARYDEF_NAME

See Also:

Constant Field Values

PERSISTENCE_PARAMETERS_NAME

public static final java.lang.String PERSISTENCE_PARAMETERS_NAME

See Also:

Constant Field Values

NAMES

public static final java.lang.String[] NAMES

PERSISTENCE_ARCHIVE_COUNT_PREFIX

public static final java.lang.String PERSISTENCE_ARCHIVE_COUNT_PREFIX

See Also:

Constant Field Values

PERSISTENCE_CONSOLIDATION_PERIOD_PREFIX

public static final java.lang.String PERSISTENCE_CONSOLIDATION_PERIOD_PREFIX

See Also:

Constant Field Values

PERSISTENCE_INTERVAL_PREFIX

public static final java.lang.String PERSISTENCE_INTERVAL_PREFIX

See Also:

Constant Field Values

PERSISTENCE_ENABLE_PREFIX

public static final java.lang.String PERSISTENCE_ENABLE_PREFIX

See Also:

Constant Field Values

PERSISTENCE_VERIFY_JAVA_IO_PATCH_PREFIX

public static final java.lang.String PERSISTENCE_VERIFY_JAVA_IO_PATCH_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DISABLE_WRITE_PREFIX

public static final java.lang.String PERSISTENCE_DISABLE_WRITE_PREFIX

See Also:

Constant Field Values

PERSISTENCE_ARCHIVE_NUMBER_PREFIX

public static final java.lang.String PERSISTENCE_ARCHIVE_NUMBER_PREFIX

See Also:

Constant Field Values

PERSISTENCE_CLASS_PREFIX

public static final java.lang.String PERSISTENCE_CLASS_PREFIX

See Also:

Constant Field Values

PERSISTENCE_ROOT_PREFIX

public static final java.lang.String PERSISTENCE_ROOT_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_DRIVER_PREFIX

public static final java.lang.String PERSISTENCE_DB_DRIVER_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_URL_PREFIX

public static final java.lang.String PERSISTENCE_DB_URL_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_USER_PREFIX

public static final java.lang.String PERSISTENCE_DB_USER_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_PASSWORD_PREFIX

public static final java.lang.String PERSISTENCE_DB_PASSWORD_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_INTDEF_PREFIX

public static final java.lang.String PERSISTENCE_DB_INTDEF_PREFIX

See Also:

Constant Field Values

PERSISTENCE_DB_LONGBINARYDEF_PREFIX

public static final java.lang.String PERSISTENCE_DB_LONGBINARYDEF_PREFIX

See Also:

Constant Field Values

PERSISTENCE_PARAMETERS_PREFIX

public static final java.lang.String PERSISTENCE_PARAMETERS_PREFIX

See Also:

Constant Field Values

PERSISTENCE_ARCHIVE_COUNT_PROP

public static final java.lang.String PERSISTENCE_ARCHIVE_COUNT_PROP

See Also:

Constant Field Values

PERSISTENCE_CONSOLIDATION_PERIOD_PROP

public static final java.lang.String PERSISTENCE_CONSOLIDATION_PERIOD_PROP

See Also:

Constant Field Values

PERSISTENCE_INTERVAL_PROP

public static final java.lang.String PERSISTENCE_INTERVAL_PROP

See Also:

Constant Field Values

PERSISTENCE_ENABLE_PROP

public static final java.lang.String PERSISTENCE_ENABLE_PROP

See Also:

Constant Field Values

PERSISTENCE_VERIFY_JAVA_IO_PATCH_PROP

public static final java.lang.String PERSISTENCE_VERIFY_JAVA_IO_PATCH_PROP

See Also:

Constant Field Values

PERSISTENCE_DISABLE_WRITE_PROP

public static final java.lang.String PERSISTENCE_DISABLE_WRITE_PROP

See Also:

Constant Field Values

PERSISTENCE_ARCHIVE_NUMBER_PROP

public static final java.lang.String PERSISTENCE_ARCHIVE_NUMBER_PROP

See Also:

Constant Field Values

PERSISTENCE_CLASS_PROP

public static final java.lang.String PERSISTENCE_CLASS_PROP

See Also:

Constant Field Values

PERSISTENCE_ROOT_PROP

public static final java.lang.String PERSISTENCE_ROOT_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_DRIVER_PROP

public static final java.lang.String PERSISTENCE_DB_DRIVER_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_URL_PROP

public static final java.lang.String PERSISTENCE_DB_URL_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_USER_PROP

public static final java.lang.String PERSISTENCE_DB_USER_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_PASSWORD_PROP

public static final java.lang.String PERSISTENCE_DB_PASSWORD_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_INTDEF_PROP

public static final java.lang.String PERSISTENCE_DB_INTDEF_PROP

See Also:

Constant Field Values

PERSISTENCE_DB_LONGBINARYDEF_PROP

public static final java.lang.String PERSISTENCE_DB_LONGBINARYDEF_PROP

See Also:

Constant Field Values

PERSISTENCE_PARAMETERS_PROP

public static final java.lang.String PERSISTENCE_PARAMETERS_PROP

See Also:

Constant Field Values

Constructor Detail

DatabasePersistence

public DatabasePersistence()

Method Detail

handleParameter

protected void handleParameter(java.lang.String param)

Specified by:

handleParameter in class PersistencePluginAdapter

init

public void init(PersistencePluginSupport pps,
                 java.lang.String name,
                 java.lang.String[] params,
                 boolean deleteOldPersistence)
          throws PersistenceException

Description copied from interface: PersistencePlugin

Initialize the plugin with PersistencePluginSupport and parameters. After initialization, the plugin should be ready to service all methods.

Specified by:

init in interface PersistencePlugin

Parameters:

pps - the persistence plugin support specifies the context within which persistence is being performed.

name - the name of this plugin.

params - String parameters to configure the plugin. The parameters come from configuration information and interpretation is up to the plugin.

Throws:

PersistenceException

readSequenceNumbers

public SequenceNumbers[] readSequenceNumbers(java.lang.String suffix)

Description copied from interface: PersistencePlugin

Read the specified set of sequence numbers. These numbers should identify a complete set of persistence deltas needed to restore the specified state. A specific archive may be specified using the suffix argument.

Specified by:

readSequenceNumbers in interface PersistencePlugin

Parameters:

suffix - identifies which set of persistence deltas are wanted. A non-empty suffix specifies an specific, archived state. An empty suffix specifies all available sets.

Returns:

an array of possible rehydration sets. The timestamp of each indicates how recent each rehydration set is.

cleanupOldDeltas

public void cleanupOldDeltas(SequenceNumbers cleanupNumbers)

Description copied from interface: PersistencePlugin

Cleanup old deltas as specified by cleanupNumbers. These deltas are never part of the current state. When archiving is enabled, the old deltas constituting an archive are not discarded.

Specified by:

cleanupOldDeltas in interface PersistencePlugin

Parameters:

cleanupNumbers - the numbers to be discarded (or archived).

cleanupArchive

public void cleanupArchive()

Description copied from interface: PersistencePlugin

Delete old archives

Specified by:

cleanupArchive in interface PersistencePlugin

openOutputStream

public java.io.OutputStream openOutputStream(int deltaNumber,
                                             boolean full)
                                      throws java.io.IOException

Description copied from interface: PersistencePlugin

Open an OutputStream onto which a persistence delta can be written. The stream returned should be relatively non-blocking since it is possible for the entire agent to be blocked waiting for completion. Implementations that may block indefinitely should perform buffering as needed. Also, the OutputStream should be unique relative to other instances of the same agent

Specified by:

openOutputStream in interface PersistencePlugin

Parameters:

deltaNumber - the number of the delta that will be written. Numbers are never re-used so this number can be used to uniquely identify the delta.

full - indicates that the information to be written is a complete state dump and does not depend on any earlier deltas. It may be useful to distinctively mark such deltas.

Throws:

java.io.IOException

finishOutputStream

public void finishOutputStream(SequenceNumbers retainNumbers,
                               boolean full)

Description copied from interface: PersistencePlugin

Clean up after closing the output stream. This method is called within a mutual exclusion semaphore such that multiple instances of the same agent cannot both be calling this or related methods. This is the opportunity to rename the output stream to its real identity.

Specified by:

finishOutputStream in interface PersistencePlugin

Parameters:

retainNumbers - the numbers of the deltas including the one just written that comprise a complete rehydration set. Subsequent calls to readSequenceNumbers should return these values.

abortOutputStream

public void abortOutputStream(SequenceNumbers retainNumbers)

Description copied from interface: PersistencePlugin

Clean up after output was aborted. Called in response to an exception during the writing of the current stream.

Specified by:

abortOutputStream in interface PersistencePlugin

Parameters:

retainNumbers - the numbers of the deltas excluding the one just written that comprise a complete rehydration set. Subsequent calls to readSequenceNumbers should return these values.

openInputStream

public java.io.InputStream openInputStream(int deltaNumber)
                                    throws java.io.IOException

Description copied from interface: PersistencePlugin

Open an InputStream from which a persistence delta can be read.

Specified by:

openInputStream in interface PersistencePlugin

Parameters:

deltaNumber - the number of the delta to be opened

Throws:

java.io.IOException

finishInputStream

public void finishInputStream(int deltaNumber)

Description copied from interface: PersistencePlugin

Clean up after closing the input stream

Specified by:

finishInputStream in interface PersistencePlugin

Parameters:

deltaNumber - the number of the delta being closed. Provided as a convenience to the method

storeDataProtectionKey

public void storeDataProtectionKey(int deltaNumber,
                                   DataProtectionKey key)
                            throws java.io.IOException

Description copied from interface: PersistencePlugin

Store an encrypted key for a particular delta number

Specified by:

storeDataProtectionKey in interface PersistencePlugin

Parameters:

deltaNumber - the number of the delta for which the key is used.

key - has the encrypted key to be stored

Throws:

java.io.IOException

retrieveDataProtectionKey

public DataProtectionKey retrieveDataProtectionKey(int deltaNumber)
                                            throws java.io.IOException

Description copied from interface: PersistencePlugin

Retrieve an encrypted key for a particular delta number

Specified by:

retrieveDataProtectionKey in interface PersistencePlugin

Parameters:

deltaNumber - the number of the delta for which the key is used.

Throws:

java.io.IOException

getDatabaseConnection

public java.sql.Connection getDatabaseConnection(java.lang.Object locker)

Override adapter version since we actually have a database connection we can return instead of throwing an exception.

Specified by:

getDatabaseConnection in interface PersistencePlugin

Overrides:

getDatabaseConnection in class PersistencePluginAdapter

releaseDatabaseConnection

public void releaseDatabaseConnection(java.lang.Object locker)

Description copied from interface: PersistencePlugin

Release the connection to the database into which persistence deltas are being written for coordinated transaction management. Non-database implementations should throw an UnsupportedOperationException

Specified by:

releaseDatabaseConnection in interface PersistencePlugin

Overrides:

releaseDatabaseConnection in class PersistencePluginAdapter