Package com.sun.jini.reliableLog

Class ReliableLog

java.lang.Object
com.sun.jini.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:

  • Constructor Summary

    Constructors
    Constructor
    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
    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 Details

    • 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 Details

    • 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;