GigaSpaces XAP 8.0 API

com.sun.jini.reliableLog
Class ReliableLog

java.lang.Object
  extended by 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:
LogHandler

Constructor Summary
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
 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;


GigaSpaces XAP 8.0 API

Copyright © GigaSpaces.