org.dellroad.stuff.pobj
Class PersistentObjectSchemaUpdater<T>

java.lang.Object
  org.dellroad.stuff.schema.AbstractSchemaUpdater<File,PersistentFileTransaction>
      org.dellroad.stuff.pobj.PersistentObjectSchemaUpdater<T>

Type Parameters:

T - type of the root persistent object

Direct Known Subclasses:

SpringPersistentObjectSchemaUpdater

public class PersistentObjectSchemaUpdater<T>
extends AbstractSchemaUpdater<File,PersistentFileTransaction>

Support superclass for PersistentObject schema updaters.

This class holds a nested PersistentObject and ensures that it's up to date when started. Use getPersistentObject() to access it.

Updates are tracked by "secretly" inserting <pobj:updates> elements into the serialized XML document; these updates are transparently removed when the document is read back. In this way the document and its set of applied updates always travel together.

Subclasses will typically override getInitialValue() for when there is no persistent file yet.

Field Summary

protected boolean	allowEmptyStart
protected long	checkInterval
static long	DEFAULT_CHECK_INTERVAL Default check interval for "out-of-band" updates to the persistent file (1000Lms).
protected PersistentObjectDelegate<T>	delegate
protected File	file
static String	NAMESPACE_URI XML namespace URI used for nested update elements.
protected int	numBackups
static QName	UPDATE_ELEMENT_NAME XML element name for a single update.
static QName	UPDATES_ELEMENT_NAME XML element name for the updates list.
protected long	writeDelay
static String	XML_PREFIX Preferred XML namespace prefix for NAMESPACE_URI elements.
static QName	XMLNS_ATTRIBUTE_NAME XML namespace URI used for namespace declarations.

Fields inherited from class org.dellroad.stuff.schema.AbstractSchemaUpdater

log

Constructor Summary

PersistentObjectSchemaUpdater()

Method Summary

protected void	commitTransaction(PersistentFileTransaction transaction) Commit a previously opened transaction.
protected boolean	databaseNeedsInitialization(PersistentFileTransaction transaction) Determine if the database needs initialization.
protected Set<String>	getAppliedUpdateNames(PersistentFileTransaction transaction) Determine which updates have already been applied to the database.
protected T	getInitialValue() Get the initial value for the persistent object when no persistent file is found.
PersistentObject<T>	getPersistentObject() Get the PersistentObject.
protected void	initializeDatabase(PersistentFileTransaction transaction) Initialize an uninitialized database.
protected PersistentFileTransaction	openTransaction(File file) Begin a transaction on the given database.
protected void	recordUpdateApplied(PersistentFileTransaction transaction, String name) Record an update as having been applied to the database.
protected void	rollbackTransaction(PersistentFileTransaction transaction) Roll back a previously opened transaction.
void	setAllowEmptyStart(boolean allowEmptyStart) Configure whether to all "empty starts".
void	setCheckInterval(long checkInterval) Configure the check interval for "out-of-band" updates to the persistent file.
void	setDelegate(PersistentObjectDelegate<T> delegate) Configure the PersistentObjectDelegate.
void	setFile(File file) Configure the file used to store this object persistently.
void	setNumBackups(int numBackups) Configure the number of backups to make of the persistent file.
void	setWriteDelay(long writeDelay) Configure the maximum delay after an update operation before a write-back to the persistent file must be initiated.
void	start() Start this instance.
void	stop() Stop this instance.

Methods inherited from class org.dellroad.stuff.schema.AbstractSchemaUpdater

apply, applyInTransaction, generateMultiUpdateName, getOrderingTieBreaker, getUpdates, initializeAndUpdateDatabase, isIgnoreUnrecognizedUpdates, isValidUpdateName, setIgnoreUnrecognizedUpdates, setUpdates

Methods inherited from class java.lang.Object

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

Field Detail

NAMESPACE_URI

public static final String NAMESPACE_URI

XML namespace URI used for nested update elements.

See Also:

Constant Field Values

XML_PREFIX

public static final String XML_PREFIX

Preferred XML namespace prefix for NAMESPACE_URI elements.

See Also:

Constant Field Values

UPDATES_ELEMENT_NAME

public static final QName UPDATES_ELEMENT_NAME

XML element name for the updates list.

UPDATE_ELEMENT_NAME

public static final QName UPDATE_ELEMENT_NAME

XML element name for a single update.

XMLNS_ATTRIBUTE_NAME

public static final QName XMLNS_ATTRIBUTE_NAME

XML namespace URI used for namespace declarations.

DEFAULT_CHECK_INTERVAL

public static final long DEFAULT_CHECK_INTERVAL

Default check interval for "out-of-band" updates to the persistent file (1000Lms).

See Also:

Constant Field Values

file

protected File file

writeDelay

protected long writeDelay

checkInterval

protected long checkInterval

numBackups

protected int numBackups

allowEmptyStart

protected boolean allowEmptyStart

delegate

protected PersistentObjectDelegate<T> delegate

Constructor Detail

PersistentObjectSchemaUpdater

public PersistentObjectSchemaUpdater()

Method Detail

setFile

public void setFile(File file)

Configure the file used to store this object persistently. Required property.

setWriteDelay

public void setWriteDelay(long writeDelay)

Configure the maximum delay after an update operation before a write-back to the persistent file must be initiated. Default is zero.

setCheckInterval

public void setCheckInterval(long checkInterval)

Configure the check interval for "out-of-band" updates to the persistent file. Default is DEFAULT_CHECK_INTERVAL.

setDelegate

public void setDelegate(PersistentObjectDelegate<T> delegate)

Configure the PersistentObjectDelegate. Required property.

setNumBackups

public void setNumBackups(int numBackups)

Configure the number of backups to make of the persistent file.

See Also:

PersistentObject.getNumBackups()

setAllowEmptyStart

public void setAllowEmptyStart(boolean allowEmptyStart)

Configure whether to all "empty starts". Default is false.

See Also:

PersistentObject

start

public void start()

Start this instance. Does nothing if already started.

Throws:

IllegalArgumentException - if an invalid file, write delay, or delegate is configured

PersistentObjectException - if an error occurs

stop

public void stop()

Stop this instance. Does nothing if already stopped.

Throws:

PersistentObjectException - if a delayed write back is pending and error occurs during writing

getPersistentObject

public PersistentObject<T> getPersistentObject()

Get the PersistentObject.

Throws:

IllegalStateException - if this instance is not started

getInitialValue

protected T getInitialValue()

Get the initial value for the persistent object when no persistent file is found.

The implementation in PersistentObjectSchemaUpdater just returns null, which leaves the initial root object unset. Subclasses should override as desired to provide an initial value.

The returned value must properly validate.

databaseNeedsInitialization

protected boolean databaseNeedsInitialization(PersistentFileTransaction transaction)
                                       throws Exception

Description copied from class: AbstractSchemaUpdater

Determine if the database needs initialization.

If so, AbstractSchemaUpdater.initializeDatabase(T) will eventually be invoked.

Specified by:

databaseNeedsInitialization in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction

Throws:

Exception - if an error occurs while accessing the database

initializeDatabase

protected void initializeDatabase(PersistentFileTransaction transaction)
                           throws Exception

Description copied from class: AbstractSchemaUpdater

Initialize an uninitialized database. This should create and initialize the database schema and content, including whatever portion of that is used to track schema updates.

Specified by:

initializeDatabase in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction

Throws:

Exception - if an error occurs while accessing the database

openTransaction

protected PersistentFileTransaction openTransaction(File file)
                                             throws Exception

Description copied from class: AbstractSchemaUpdater

Begin a transaction on the given database. The transaction will always eventually either be committed or rolled back.

Specified by:

openTransaction in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

file - database

Returns:

transaction handle

Throws:

Exception - if an error occurs while accessing the database

commitTransaction

protected void commitTransaction(PersistentFileTransaction transaction)
                          throws Exception

Description copied from class: AbstractSchemaUpdater

Commit a previously opened transaction.

Specified by:

commitTransaction in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction previously returned from openTransaction()

Throws:

Exception - if an error occurs while accessing the database

rollbackTransaction

protected void rollbackTransaction(PersistentFileTransaction transaction)
                            throws Exception

Description copied from class: AbstractSchemaUpdater

Roll back a previously opened transaction. This method will also be invoked if commitTransaction() throws an exception.

Specified by:

rollbackTransaction in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction previously returned from openTransaction()

Throws:

Exception - if an error occurs while accessing the database

getAppliedUpdateNames

protected Set<String> getAppliedUpdateNames(PersistentFileTransaction transaction)
                                     throws Exception

Description copied from class: AbstractSchemaUpdater

Determine which updates have already been applied to the database.

Specified by:

getAppliedUpdateNames in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction

Throws:

Exception - if an error occurs while accessing the database

recordUpdateApplied

protected void recordUpdateApplied(PersistentFileTransaction transaction,
                                   String name)
                            throws Exception

Description copied from class: AbstractSchemaUpdater

Record an update as having been applied to the database.

Specified by:

recordUpdateApplied in class AbstractSchemaUpdater<File,PersistentFileTransaction>

Parameters:

transaction - open transaction

name - update name

Throws:

IllegalStateException - if the update has already been recorded in the database

Exception - if an error occurs while accessing the database