EQUIP2 Logging

Chris Greenhalgh, 2006-04-27

Contents:

Introduction

One of the potential benefits of using the EQUIP2 approach is that the dataspace(s) provide a standard point for logging much of the internal activity of an application, and the standard state/event model allows the historical state(s) and evolution of a dataspace to be recreated from a log of actions on the dataspace. This document describes EQUIP2's current support for logging and the log files produced.

Logging internal API

All of the current dataspace implementation extends equip2.core.impl.DefaultDataspace, which in turn supports the following constructor option and method:
package equip2.core.impl;
import equip2.core.impl.IDataspaceLogger;
public class DefaultDataspace {
  protected DefaultDataspace(IDataspaceLogger dataspaceLogger); 
  public void setLogger(IDataspaceLogger dataspaceLogger); 
}

Either of these can be used to attach a dataspace logger to that dataspace, to log or otherwise record potentially all changes made to that dataspace.

The equip2.core.impl.IDataspaceLogger internal interface (to be implemented by a logger) is as follows:

package equip2.core.impl;
public interface IDataspaceLogger {
    public void logBegin(IDataspace dataspace);
    public void logChange(IDataspace dataspace, SessionManagedObject changedObjects[]);
    public void logEnd(IDataspace dataspace);
}

Note that logEnd will not be called unless the dataspace shuts down in a well-defined manner (none of them do at present!), or the logger is replaced or reset (e.g. a call to the dataspace setLogger(null)). Consequently, many log files may not be cleanly terminated.

Logging a dataspace

There is currently a common abstract implementation of the dataspace logger API, equip2.core.logging.AbstractDataspaceLogger, which can be extended to support different log output methods. The implement(s) are currently:

To log a dataspace, a dataspace logger object is created and initialised, and then passed to the dataspace to be logged, either via its constructor (not support on all dataspace implementations) or using the setLogger method (see API section, above).

The test equip2.core.logging.test.j2se.SimpleFileDataspaceLoggerTest gives an example of logging a dataspace.

Log file format

The default log file format (e.g. as supported by equip2.core.logging.AbstractDataspaceLogger) uses autogenerated java beans to represent the log file contents:

A log file should always start with a single LogHeader object, followed by any number of LogEntry objects, followed by a  single LogTrailer object (although, as noted above, the LogTrailer and file ending may often be missing).

An actual file is generated or read using the standard EQUIP2 object marshalling framework. Currently this supports:

Logging tools

The following tool(s) exist to support working with log files and/or provide code samples for future tool development:
Note that the log file reader(s) can use custom object helper registry(s) to allow them to read classes (or versions of classes) which they do not actually have class files for. E.g. the registry equip2.core.logging.j2se.HashtableFallbackObjectHelperRegistry will use the generic Hashtable object helper to handle any unknown (not found) class.

Change log

2006-04-27