com.sun.jini.reggie

Class RegistrarImpl.LocalLogHandler

java.lang.Object

com.sun.jini.reliableLog.LogHandler

com.sun.jini.reggie.RegistrarImpl.LocalLogHandler

Enclosing class:

RegistrarImpl

private class RegistrarImpl.LocalLogHandler
extends LogHandler

Handler class for the persistent storage facility.

At any point during processing in a persistent Registrar instance, there will exist both a 'snapshot' of the Registrar's state and a set of records detailing each significant change that has occurred to the state since the snapshot was taken. The snapshot information and the incremental change information will be stored in separate files called, respectively, the snapshot file and the log file. Together, these files are used to recover the state of the Registrar when it is restarted or reactivated (for example, after a crash or network outage).

This class contains the methods that are used to record and recover the snapshot of the Registrar's state; as well as the method used to apply the state changes that were recorded in the log file.

When the ReliableLog class is instantiated, a new instance of this class is passed to its constructor so that the methods of this class may be invoked by the methods defined in the ReliableLog. Because this class extends the LogHandler class associated with the ReliableLog class, this class must provide implementations of the abstract methods declared in the LogHandler. Also, some of the methods defined in this class override the methods of the LogHandler in order to customize the handling of snapshot creation and retrieval.

Each significant change to the persistent Registrar's state is written to the log file as an individual record (when addLogRecord() is invoked). After the number of records logged exceeds a pre-defined threshold, a snapshot of the state is recorded by invoking -- through the ReliableLog and its LogHandler -- the snapshot() method defined in this class. After the snapshot is taken, the log file is cleared and the incremental log process starts over.

The contents of the snapshot file reflect the DATA contained in the fields making up the current state of the Registrar. That data represents many changes -- over time -- to the Registrar's state. On the other hand, each record written to the log file is an object that reflects both the data used and the ACTIONS taken to make one change to the Registrar's state at a particular point in time.

The data written to the snapshot file is shown below:

• our service ID
• current event ID
• current values of administrable parameters
• contents of the container holding the current registered services
• null (termination 'marker' for the set of registered services)
• contents of the container holding the current registered events
• null (termination 'marker' for the set of registered events)

The type of state changes that will generate a new record in the log file are:

• a new service was registered
• a new event was registered
• new attributes were added to an existing service
• existing attributes of a service were modified
• a service lease was cancelled
• a service lease was renewed
• an event lease was cancelled
• an event lease was renewed
• an administrable parameter was changed

During recovery, the state of the Registrar at the time of a crash or outage is re-constructed by first retrieving the 'base' state from the snapshot file; and then modifying that base state according to the records retrieved from the log file. The reconstruction of the base state is achieved by invoking the recover() method defined in this class. The modifications recorded in the log file are then applied to the base state by invoking the applyUpdate() method defined in this class. Both recover() and applyUpdate() are invoked through the ReliableLog and its associated LogHandler.

NOTE: The following lines must be added to the Registrar's policy file

     permission java.io.FilePermission "dirname",   "read,write,delete";
     permission java.io.FilePermission "dirname/-", "read,write,delete";
 

where 'dirname' is the name of the directory path (relative or absolute) where the snapshot and log file will be maintained.

Constructor Summary

Constructors

Constructor and Description
RegistrarImpl.LocalLogHandler() Simple constructor

Method Summary

Methods

Modifier and Type	Method and Description
void	applyUpdate(Object logRecObj) Required method implementing the abstract applyUpdate() defined in ReliableLog's associated LogHandler class.
void	recover(InputStream in) Read the snapshot from a stream.
void	snapshot(OutputStream out) Writes the snapshot to a stream.

Methods inherited from class com.sun.jini.reliableLog.LogHandler

readUpdate, writeUpdate

Methods inherited from class java.lang.Object

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

Constructor Detail

RegistrarImpl.LocalLogHandler

public RegistrarImpl.LocalLogHandler()

Simple constructor

Method Detail

snapshot

public void snapshot(OutputStream out)
              throws IOException

Description copied from class: LogHandler

Writes the snapshot to a stream. This callback is invoked when the client calls the snaphot method of ReliableLog.

Specified by:

snapshot in class LogHandler

Parameters:

out - the output stream

Throws:

IOException

recover

public void recover(InputStream in)
             throws IOException,
                    ClassNotFoundException

Description copied from class: LogHandler

Read the snapshot from a stream. This callback is invoked when the client calls the recover method of ReliableLog.

Specified by:

recover in class LogHandler

Parameters:

in - the input stream

Throws:

IOException

ClassNotFoundException

applyUpdate

public void applyUpdate(Object logRecObj)

Required method implementing the abstract applyUpdate() defined in ReliableLog's associated LogHandler class.

During state recovery, the recover() method defined in the ReliableLog class is invoked. That method invokes the method recoverUpdates() which invokes the method readUpdates(). Both of those methods are defined in ReliableLog. The method readUpdates() retrieves a record from the log file and then invokes this method.

This method invokes the version of the method apply() that corresponds to the particular type of 'log record' object that is input as the first argument. The log record object and its corresponding apply() method are defined in one of the so-called LogObj classes. Any instance of one the LogObj classes is an implementation of the LogRecord interface. The particular implementation that is input to this method is dependent on the type of record that was originally logged. The apply() method will then modify the state of the Registrar in a way dictated by the type of record that was retrieved.

Specified by:

applyUpdate in class LogHandler

Parameters:

logRecObj - the update object