public class

ReliableLog

extends Object
java.lang.Object
   ↳ sun.rmi.log.ReliableLog

Class Overview

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 checkpoints and log records. This implementation ensures that the current value of the data stored (via a ReliableLog) is recoverable after a system crash.

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 (all it "log") by calling log.update. Periodically, the client calls log.snapshot to provide the current value of the data structure. 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.

The current logfile format is:

  1. a format version number (two 4-octet integers, major and minor), followed by
  2. a sequence of log records. Each log record contains, in order,
    1. a 4-octet integer representing the length of the following log data,
    2. the log data (variable length).

See Also

Summary

Nested Classes
class ReliableLog.LogFile ReliableLog's log file implementation. 
Constants
int PreferredMajorVersion
int PreferredMinorVersion
Public Constructors
ReliableLog(String dirPath, LogHandler handler, boolean pad)
Creates a ReliableLog to handle checkpoints and logging in a stable storage directory.
ReliableLog(String dirPath, LogHandler handler)
Creates a ReliableLog to handle checkpoints and logging in a stable storage directory.
Public Methods
synchronized void close()
Close the stable storage directory in an orderly manner.
long logSize()
Returns the size of the log file in bytes;
synchronized Object recover()
Returns an object which is the value recorded in the current snapshot.
synchronized void snapshot(Object value)
Records this value as the current snapshot by invoking the client supplied "snapshot" callback and then empties the log.
long snapshotSize()
Returns the size of the snapshot file in bytes;
synchronized void update(Object value)
Records this update in the log file (does not force update to disk).
synchronized void update(Object value, boolean forceToDisk)
Records this update in the log file.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int PreferredMajorVersion

Constant Value: 0 (0x00000000)

public static final int PreferredMinorVersion

Constant Value: 2 (0x00000002)

Public Constructors

public ReliableLog (String dirPath, LogHandler handler, boolean pad)

Creates a ReliableLog to handle checkpoints and logging in a stable storage directory.

Parameters
dirPath path to the stable storage directory
pad ignored
Throws
IOException If a directory creation error has occurred or if initialSnapshot callback raises an exception or if an exception occurs during invocation of the handler's snapshot method or if other IOException occurs.

public ReliableLog (String dirPath, LogHandler handler)

Creates a ReliableLog to handle checkpoints and logging in a stable storage directory.

Parameters
dirPath path to the stable storage directory
Throws
IOException If a directory creation error has occurred or if initialSnapshot callback raises an exception

Public Methods

public synchronized void close ()

Close the stable storage directory in an orderly manner.

Throws
IOException If an I/O error occurs when the log is closed

public long logSize ()

Returns the size of the log file in bytes;

public synchronized Object recover ()

Returns an object which is the value recorded in the current snapshot. This snapshot is recovered by calling the client supplied callback "recover" and then subsequently invoking the "readUpdate" callback to apply any logged updates to the state.

Throws
IOException If recovery fails due to serious log corruption, read update failure, or if an exception occurs during the recover callback

public synchronized void snapshot (Object value)

Records this value as the current snapshot by invoking the client supplied "snapshot" callback and then empties the log.

Parameters
value the object representing the new snapshot
Throws
IOException If an exception occurred during the snapshot callback or if other I/O error has occurred during the snapshot process

public long snapshotSize ()

Returns the size of the snapshot file in bytes;

public synchronized void update (Object value)

Records this update in the log file (does not force 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
IOException If an exception occurred during a writeUpdate callback or if other I/O error has occurred.

public synchronized void update (Object value, boolean forceToDisk)

Records this update in the log file. 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 ignored; changes are always forced to disk
Throws
IOException If force-write to log failed or an exception occurred during the writeUpdate callback or if other I/O error occurs while updating the log.