org.cougaar.core.persist
Class FilePersistenceBase

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

All Implemented Interfaces:

PersistencePlugin

Direct Known Subclasses:

BufferedFilePersistence, FilePersistence

public abstract class FilePersistenceBase
extends PersistencePluginAdapter
implements PersistencePlugin

This PersistencePlugin abstract base class saves and restores blackboard objects in files. The actual opening of the input and output streams remains abstract.

There is one optional parameter naming the persistence root directory. If the parameter is omitted, the persistence root is specified by system properties.

System Properties:

org.cougaar.install.path	Used by FilePersistence as the parent directory for persistence snapshots when there is no directory specified in configuration parameters and org.cougaar.core.persistence.path is a relative pathname. This property is not used if the plugin is configured with a specific parameter specifying the location of the persistence root.
org.cougaar.core.persistence.path	Specifies the directory in which persistence snapshots should be saved. If this is a relative path, it the base will be the value or org.cougaar.install.path. This property is not used if the plugin is configured with a specific parameter specifying the location of the persistence root.

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

FilePersistenceBase()

Method Summary

void	abortOutputStream(SequenceNumbers retainNumbers) Clean up after output was aborted.
boolean	checkOwnership() Check that this agent instance still owns the persistence data
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.
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.
void	lockOwnership() Lock out other instances of this agent.
protected abstract java.io.InputStream	openFileInputStream(java.io.File file)
protected abstract java.io.OutputStream	openFileOutputStream(java.io.File file)
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.
protected abstract boolean	rename(java.io.File from, java.io.File to)
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
void	unlockOwnership() Release the lockout of other instances of this agent.

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

getConsolidationPeriod, getControlNames, getControlValues, getDatabaseConnection, getName, getParam, getParamCount, getPersistenceInterval, init, isWritable, parseParamValue, releaseDatabaseConnection, setConsolidationPeriod, setControl, setPersistenceInterval, setWritable

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

getConsolidationPeriod, getControlNames, getControlValues, getDatabaseConnection, getName, getParam, getParamCount, getPersistenceInterval, isWritable, releaseDatabaseConnection, setConsolidationPeriod, setControl, setPersistenceInterval, setWritable

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

FilePersistenceBase

public FilePersistenceBase()

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

checkOwnership

public boolean checkOwnership()

Description copied from interface: PersistencePlugin

Check that this agent instance still owns the persistence data

Specified by:

checkOwnership in interface PersistencePlugin

Overrides:

checkOwnership in class PersistencePluginAdapter

lockOwnership

public void lockOwnership()

Description copied from interface: PersistencePlugin

Lock out other instances of this agent.

Specified by:

lockOwnership in interface PersistencePlugin

Overrides:

lockOwnership in class PersistencePluginAdapter

unlockOwnership

public void unlockOwnership()

Description copied from interface: PersistencePlugin

Release the lockout of other instances of this agent.

Specified by:

unlockOwnership in interface PersistencePlugin

Overrides:

unlockOwnership in class PersistencePluginAdapter

openFileInputStream

protected abstract java.io.InputStream openFileInputStream(java.io.File file)
                                                    throws java.io.FileNotFoundException

Throws:

java.io.FileNotFoundException

openFileOutputStream

protected abstract java.io.OutputStream openFileOutputStream(java.io.File file)
                                                      throws java.io.FileNotFoundException

Throws:

java.io.FileNotFoundException

rename

protected abstract boolean rename(java.io.File from,
                                  java.io.File to)

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