org.prevayler
Class PrevaylerFactory<P>

java.lang.Object
  org.prevayler.PrevaylerFactory<P>

Type Parameters:

P - The type of object you intend to persist as a Prevalent System.

public class PrevaylerFactory<P>
extends Object

Provides easy access to all Prevayler configurations and implementations available in this distribution. Static methods are also provided as short-cuts for the most common configurations.

By default, the Prevayler instances created by this class will write their Transactions to .journal files before executing them. The FileDescriptor.sync() method is called to make sure the Java file write-buffers have been written to the operating system. Many operating systems, including most recent versions of Linux and Windows, allow the hard-drive's write-cache to be disabled. This guarantees no executed Transaction will be lost in the event of a power shortage, for example.

Also by default, the Prevayler instances created by this class will execute deep copies of transactions, not the transactions themselves, so that unrecoverable changes to the prevalent system and unrecoverable uses of reference equality inside transactions fail fast as they would upon recovery.

See Also:

Prevayler

Field Summary

static int

DEFAULT_REPLICATION_PORT

Constructor Summary

PrevaylerFactory()
Example:

PrevaylerFactory<MyObjectToPersist> f = new PrevaylerFactory<MyObjectToPersist>();

Use if you want access to any configuration options not available via the static method short-cuts.

Method Summary

void	configureClock(Clock clock) Configures the Clock that will be used by the created Prevayler.
void	configureJournalDiskSync(boolean journalDiskSync) Configures whether the journal will sync writes to disk.
void	configureJournalFileAgeThreshold(long ageInMilliseconds) Sets the age (in milliseconds) of the journal file.
void	configureJournalFileSizeThreshold(long sizeInBytes) Configures the size (in bytes) of the journal file.
void	configureJournalSerializer(JavaSerializer serializer)
void	configureJournalSerializer(String suffix, Serializer serializer) Configures the transaction journal Serializer to be used by the Prevayler created by this factory.
void	configureJournalSerializer(XStreamSerializer serializer)
void	configureMonitor(Monitor monitor) Assigns a monitor object to receive notifications from Prevayler.
void	configurePrevalenceDirectory(String prevalenceDirectory) Configures the directory where the created Prevayler will read and write its .journal and .snapshot files.
void	configurePrevalentSystem(P newPrevalentSystem) Configures the prevalent system that will be used by the Prevayler created by this factory.
void	configureReplicationClient(String remoteServerIpAddress, int remoteServerPort) Reserved for future implementation.
void	configureReplicationServer(int port) Reserved for future implementation.
void	configureSnapshotSerializer(JavaSerializer serializer)
void	configureSnapshotSerializer(String suffix, Serializer serializer) Configure a serialization strategy for snapshots.
void	configureSnapshotSerializer(XStreamSerializer serializer)
void	configureTransactionDeepCopy(boolean transactionDeepCopyMode) Configures whether deep copies of transactions are executed instead of the transactions themselves, upon calling ".execute" on the created Prevayler.
void	configureTransientMode(boolean transientMode) Determines whether the Prevayler created by this factory should be transient or persistent.
Prevayler<P>	create() Returns a Prevayler created according to what was defined by calls to the configuration methods above.
static <P> Prevayler<P>	createCheckpointPrevayler(P newPrevalentSystem, String snapshotDirectory) Creates a Prevayler that will execute Transactions WITHOUT writing them to disk.
static <P> Prevayler<P>	createPrevayler(P newPrevalentSystem) Creates a Prevayler that will use a directory called "PrevalenceBase" under the current directory to read and write its .snapshot and .journal files, using standard Java serialization.
static <P> Prevayler<P>	createPrevayler(P newPrevalentSystem, String prevalenceBase) Creates a Prevayler that will use the given prevalenceBase directory to read and write its .snapshot and .journal files, using standard Java serialization.
static <P> Prevayler<P>	createTransientPrevayler(P newPrevalentSystem) Creates a Prevayler that will execute Transactions WITHOUT writing them to disk.
static <P> Prevayler<P>	createTransientPrevayler(P newPrevalentSystem, String snapshotDirectory) Deprecated. Use createCheckpointPrevayler() instead of this method. Deprecated since Prevayler2.00.001.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_REPLICATION_PORT

public static final int DEFAULT_REPLICATION_PORT

See Also:

Constant Field Values

Constructor Detail

PrevaylerFactory

public PrevaylerFactory()

Example:

PrevaylerFactory<MyObjectToPersist> f = new PrevaylerFactory<MyObjectToPersist>();

Use if you want access to any configuration options not available via the static method short-cuts.

Method Detail

createPrevayler

public static <P> Prevayler<P> createPrevayler(P newPrevalentSystem,
                                               String prevalenceBase)
                                    throws Exception

Creates a Prevayler that will use the given prevalenceBase directory to read and write its .snapshot and .journal files, using standard Java serialization. This requires that the Prevalent System and all Transaction implementations used by the Prevayler are Java-Serializable.

Example:

//Your object:
MyObjectToPersist newPrevalentSystem = new MyObjectToPersist();
String prevalenceBase = "myDirectory";
Prevayler<MyObjectToPersist> prevayler = PrevaylerFactory.createPrevayler(newPrevalentSystem, prevalenceBase);


Parameters:

newPrevalentSystem - The newly started, "empty" prevalent system that will be used as a starting point for every system startup, until the first snapshot is taken.

prevalenceBase - The directory where the .snapshot files and .journal files will be read and written.

Throws:

Exception

createPrevayler

public static <P> Prevayler<P> createPrevayler(P newPrevalentSystem)
                                    throws Exception

Creates a Prevayler that will use a directory called "PrevalenceBase" under the current directory to read and write its .snapshot and .journal files, using standard Java serialization. This requires that the Prevalent System and all Transaction implementations used by the Prevayler are Java-Serializable.

Parameters:

newPrevalentSystem - The newly started, "empty" prevalent system that will be used as a starting point for every system startup, until the first snapshot is taken.

Throws:

Exception

See Also:

createPrevayler(Object, String)

createCheckpointPrevayler

public static <P> Prevayler<P> createCheckpointPrevayler(P newPrevalentSystem,
                                                         String snapshotDirectory)

Creates a Prevayler that will execute Transactions WITHOUT writing them to disk. Snapshots will work as "checkpoints" for the system, therefore. This is useful for stand-alone applications that have a "Save" button, for example. The Prevayler will use standard Java serialization for reading and writing its .snapshot files, which requires that the Prevalent System is Java-Serializable.

Parameters:

newPrevalentSystem - The newly started, "empty" prevalent system that will be used as a starting point for every system startup, until the first snapshot is taken.

snapshotDirectory - The directory where the .snapshot files will be read and written.

See Also:

createPrevayler(Object, String)

createTransientPrevayler

public static <P> Prevayler<P> createTransientPrevayler(P newPrevalentSystem)

Creates a Prevayler that will execute Transactions WITHOUT writing them to disk. This is useful for running automated tests or demos MUCH faster than with a regular Prevayler. Attempts to take snapshots on this transient Prevayler will throw an IOException.

Parameters:

newPrevalentSystem - The newly started, "empty" prevalent system.

See Also:

createCheckpointPrevayler(Object, String)

createTransientPrevayler

public static <P> Prevayler<P> createTransientPrevayler(P newPrevalentSystem,
                                                        String snapshotDirectory)

Deprecated. Use createCheckpointPrevayler() instead of this method. Deprecated since Prevayler2.00.001.

configurePrevalentSystem

public void configurePrevalentSystem(P newPrevalentSystem)

Configures the prevalent system that will be used by the Prevayler created by this factory.

Parameters:

newPrevalentSystem - If the default Serializer is used, this prevalentSystem must be Serializable. If another Serializer is used, this prevalentSystem must be compatible with it.

See Also:

configureSnapshotSerializer(String, Serializer)

configurePrevalenceDirectory

public void configurePrevalenceDirectory(String prevalenceDirectory)

Configures the directory where the created Prevayler will read and write its .journal and .snapshot files. The default is a directory called "PrevalenceBase" under the current directory.

Parameters:

prevalenceDirectory - Will be ignored for the .snapshot files if a SnapshotManager is configured.

configureTransactionDeepCopy

public void configureTransactionDeepCopy(boolean transactionDeepCopyMode)

Configures whether deep copies of transactions are executed instead of the transactions themselves, upon calling ".execute" on the created Prevayler. The default is true.

Parameters:

transactionDeepCopyMode -

If false, references passed in to transactions are used naturally, as they are during ordinary Java method calls, allowing their underlying objects to be changed inside transactions. However, any unrecoverable changes to the prevalent system and unrecoverable uses of reference equality inside transactions will not fail fast as they would upon recovery.

If true (default), a deep copy of the transaction is executed each time. This allows any unrecoverable changes to the prevalent system and unrecoverable uses of reference equality inside transactions to fail fast as they would upon recovery. However, it only allows changes to deep copies of the objects passed in, not the original objects.

configureClock

public void configureClock(Clock clock)

Configures the Clock that will be used by the created Prevayler. The Clock interface can be implemented by the application if it requires Prevayler to use a special time source other than the machine clock (default).

configureMonitor

public void configureMonitor(Monitor monitor)

Assigns a monitor object to receive notifications from Prevayler. This is useful for logging or sending eMails to system administrators, for example. If this method is not called or if null is passed as a parameter, a SimpleMonitor will be used to log notification on System.err.

Parameters:

monitor - the Monitor implementation to use.

See Also:

SimpleMonitor

configureTransientMode

public void configureTransientMode(boolean transientMode)

Determines whether the Prevayler created by this factory should be transient or persistent. The default is false (persistent).

Parameters:

transientMode -

If true, a "transient" Prevayler will be created, which will execute its Transactions WITHOUT writing them to disk. This is useful for stand-alone applications which have a "Save" button, for example, or for running automated tests MUCH faster than with a persistent Prevayler.

If false (default), a persistent Prevayler will be created.

configureReplicationClient

public void configureReplicationClient(String remoteServerIpAddress,
                                       int remoteServerPort)

Reserved for future implementation.

configureReplicationServer

public void configureReplicationServer(int port)

Reserved for future implementation.

configureJournalFileSizeThreshold

public void configureJournalFileSizeThreshold(long sizeInBytes)

Configures the size (in bytes) of the journal file. When the current journal exceeds this size, a new journal is created.

configureJournalFileAgeThreshold

public void configureJournalFileAgeThreshold(long ageInMilliseconds)

Sets the age (in milliseconds) of the journal file. When the current journal expires, a new journal is created.

configureJournalDiskSync

public void configureJournalDiskSync(boolean journalDiskSync)

Configures whether the journal will sync writes to disk. The default is true.

Parameters:

journalDiskSync -

If false, transactions may execute without necessarily being written to the physical disk. Transactions are still flushed to the operating system before being executed, but FileDescriptor.sync() is never called. This increases transaction throughput dramatically, but allows transactions to be lost if the system does not shut down cleanly. Calling Prevayler.close() will close the underlying journal file and therefore cause all transactions to be written to disk.

If true (default), every transaction is forced to be written to the physical disk before it is executed (using FileDescriptor.sync()). (Many transactions may be written at once, but no transaction will be executed before it is written to disk.)

configureJournalSerializer

public void configureJournalSerializer(JavaSerializer serializer)

configureJournalSerializer

public void configureJournalSerializer(XStreamSerializer serializer)

configureJournalSerializer

public void configureJournalSerializer(String suffix,
                                       Serializer serializer)

Configures the transaction journal Serializer to be used by the Prevayler created by this factory. Only one Serializer is supported at a time. If you want to change the Serializer of a system in production, you will have to take a snapshot first because the journal files written by the previous Serializer will not be read.

configureSnapshotSerializer

public void configureSnapshotSerializer(JavaSerializer serializer)

configureSnapshotSerializer

public void configureSnapshotSerializer(XStreamSerializer serializer)

configureSnapshotSerializer

public void configureSnapshotSerializer(String suffix,
                                        Serializer serializer)

Configure a serialization strategy for snapshots. This may be called any number of times with different suffixes to configure different strategies for reading existing snapshots. The first call to this method establishes the primary strategy, which will be used for writing snapshots as well as for deep-copying the prevalent system whenever necessary.

create

public Prevayler<P> create()
                    throws Exception

Returns a Prevayler created according to what was defined by calls to the configuration methods above.

Throws:

IOException - If there is trouble creating the Prevalence Base directory or reading a .journal or .snapshot file.

ClassNotFoundException - If a class of a serialized Object is not found when reading a .journal or .snapshot file.

Exception