org.apache.river.reliableLog

Class ReliableLog

java.lang.Object

org.apache.river.reliableLog.ReliableLog

public class ReliableLog
extends Object

This class is a simple implementation of a reliable Log. The client of a ReliableLog must provide a set of callbacks (via a LogHandler) that enables a ReliableLog to read and write snapshots (checkpoints) and log records. This implementation ensures that the data stored (via a ReliableLog) is recoverable after a system crash. The implementation is unsynchronized; the client must synchronize externally.

The secondary storage strategy is to record values in files using a representation of the caller's choosing. Two sorts of files are kept: snapshots and logs. At any instant, one snapshot is current. The log consists of a sequence of updates that have occurred since the current snapshot was taken. The current stable state is the value of the snapshot, as modified by the sequence of updates in the log. From time to time, the client of a ReliableLog instructs the package to make a new snapshot and clear the log. A ReliableLog arranges disk writes such that updates are stable (as long as the changes are force-written to disk) and atomic: no update is lost, and each update either is recorded completely in the log or not at all. Making a new snapshot is also atomic.

Normal use for maintaining the recoverable store is as follows: The client maintains the relevant data structure in virtual memory. As updates happen to the structure, the client informs the ReliableLog (call it "log") by calling log.update. Periodically, the client calls log.snapshot to provide the current complete contents of the data. On restart, the client calls log.recover to obtain the latest snapshot and the following sequences of updates; the client applies the updates to the snapshot to obtain the state that existed before the crash.

Author:

Sun Microsystems, Inc.

See Also:

LogHandler

Constructor Summary

Constructors

Constructor and Description
ReliableLog(String dirPath, LogHandler handler) Creates a ReliableLog to handle snapshots and logging in a stable storage directory, and sets up to recover any existing data from the stable storage directory.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the stable storage directory in an orderly manner.
void	deletePersistentStore() Closes the incremental update log file, removes all ReliableLog-related files from the stable storage directory, and deletes the directory.
long	logSize() Returns the current size of the incremental update log file in bytes;
void	recover() Retrieves the contents of the snapshot file by calling the client supplied recover callback and then applies the incremental updates by calling the readUpdate callback for each logged updated.
void	snapshot() Records the client-defined current snapshot by invoking the client supplied snapshot callback, and then empties the log of incremental updates.
long	snapshotSize() Returns the size of the current snapshot file in bytes;
void	update(Object value) Records this update in the log file and forces the update to disk.
void	update(Object value, boolean forceToDisk) Records this update in the log file and optionally forces the update to disk.

Methods inherited from class java.lang.Object

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

Constructor Detail

ReliableLog

public ReliableLog(String dirPath,
                   LogHandler handler)
            throws IOException

Creates a ReliableLog to handle snapshots and logging in a stable storage directory, and sets up to recover any existing data from the stable storage directory. If there is no existing data, snapshot must be called next, otherwise recover must be called next.

Parameters:

dirPath - path to the stable storage directory

handler - the handler for log callbacks

Throws:

LogException - if the directory cannot be created or the current version in the directory is corrupted

IOException - if any other I/O error occurs

Method Detail

recover

public void recover()
             throws IOException

Retrieves the contents of the snapshot file by calling the client supplied recover callback and then applies the incremental updates by calling the readUpdate callback for each logged updated.

Throws:

LogException - if recovery fails due to serious log corruption, or if an exception is thrown by the recover or readUpdate callbacks

IOException - if an other I/O error occurs

update

public void update(Object value)
            throws IOException

Records this update in the log file and forces the update to disk. The update is recorded by calling the client's writeUpdate callback. This method must not be called until this log's recover method has been invoked (and completed).

Parameters:

value - the object representing the update

Throws:

LogException - if an exception is thrown by the writeUpdate callback, or forcing the update to disk fails

IOException - if any other I/O error occurs

update

public void update(Object value,
                   boolean forceToDisk)
            throws IOException

Records this update in the log file and optionally forces the update to disk. The update is recorded by calling the client's writeUpdate callback. This method must not be called until this log's recover method has been invoked (and completed).

Parameters:

value - the object representing the update

forceToDisk - true if the update should be forced to disk, false if the updates should be buffered

Throws:

LogException - if an exception is thrown by the writeUpdate callback, or forcing the update to disk fails

IOException - if any other I/O error occurs

snapshot

public void snapshot()
              throws IOException

Records the client-defined current snapshot by invoking the client supplied snapshot callback, and then empties the log of incremental updates.

Throws:

LogException - if the snapshot callback throws an exception

IOException - if any other I/O error occurs

close

public void close()
           throws IOException

Closes the stable storage directory in an orderly manner.

Throws:

IOException - if an I/O error occurs

deletePersistentStore

public void deletePersistentStore()

Closes the incremental update log file, removes all ReliableLog-related files from the stable storage directory, and deletes the directory.

snapshotSize

public long snapshotSize()

Returns the size of the current snapshot file in bytes;

logSize

public long logSize()

Returns the current size of the incremental update log file in bytes;