org.processmining.framework.log.rfb.io
Class ATERandomFileBuffer

java.lang.Object
  extended by org.processmining.framework.log.rfb.io.ATERandomFileBuffer

public class ATERandomFileBuffer
extends java.lang.Object

This class provides a random-access interface to a sequential set of audit trail entries. These audit trail entries are buffered not in heap space, but in a binary buffer file, whose encoding is implemented in this class as well.

The structure of a buffer file is a sequence of binary records, one for each audit trail entry, where records are encoded as follows:

This fixed part is followed by a number of string pairs describing the audit trail entry's attributes. The number of subsequent strings is obviously the value for size of the data section (see above) multiplied with 2.

Author:
christian

Nested Class Summary
protected  class ATERandomFileBuffer.ATERandomFileBufferIterator
          This class implements a lightweight iterator on a file-buffered random access collection of audit trail entries, as represented by the enclosing class.
 
Field Summary
protected  int index
          The current logical index (in number of audit trail entries) in the buffer.
protected  long lastInsertPosition
          The position at which the last audit trail entry was inserted into the backing buffer storage.
protected  long position
          The current actual position in the backing buffer storage, in bytes offset from the beginning of the storage.
protected  StorageProvider provider
          Storage provider which is used to allocate new buffer storages.
protected  int size
          The number of audit trail entries contained in a buffer.
protected  RandomAccessStorage storage
          The random access storage to back the buffer of audit trail entries.
protected static java.lang.String STRING_ENCODING
          Encoding used for storing strings in buffer storages.
 
Constructor Summary
ATERandomFileBuffer(ATERandomFileBuffer template)
          Creates a new instance of this class, which is an exact copy, or clone, of the provided template instance.
ATERandomFileBuffer(StorageProvider aProvider)
          Creates and initializes a new instance of this class.
 
Method Summary
 void append(AuditTrailEntry ate)
          Appends a new audit trail entry to the end of this collection.
 void cleanup()
          Cleans up any non-volatile resources (e.g.
 ATERandomFileBuffer cloneInstance()
          Clones this instance.
protected  byte[] encode(AuditTrailEntry ate)
          Encodes the given audit trail entry object into a sequence of bytes.
protected  void finalize()
          Remove buffer file when this instance is garbage collected.
 AuditTrailEntry get(int ateIndex)
          Retrieves the audit trail entry recorded at the specified position
 int index()
          Retrieves the current internal, logical position of this collection.
 java.util.Iterator iterator()
          Returns an iterator on the audit trail entries buffered in this collection.
protected  void navigateToIndex(int reqIndex)
          Repositions the low-level layer to read from the specified index.
protected  AuditTrailEntry read()
          Reads an audit trail entry from the current position of the data access layer.
protected  void resetPosition()
          Resets the position of the data access layer to read the next audit trail entry from the first position.
 int size()
          Retrieves the number of audit trail entries recorded in this instance.
protected  void skipBackward(int atesToSkip)
          Repositions the position of the data access layer to skip the specified number of records towards the beginning of the file.
protected  void skipForward(int atesToSkip)
          Repositions the position of the data access layer to skip the specified number of records towards the end of the file.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STRING_ENCODING

protected static final java.lang.String STRING_ENCODING
Encoding used for storing strings in buffer storages.

See Also:
Constant Field Values

size

protected int size
The number of audit trail entries contained in a buffer.


index

protected int index
The current logical index (in number of audit trail entries) in the buffer.


position

protected long position
The current actual position in the backing buffer storage, in bytes offset from the beginning of the storage.


lastInsertPosition

protected long lastInsertPosition
The position at which the last audit trail entry was inserted into the backing buffer storage. Initialized with -1.


storage

protected RandomAccessStorage storage
The random access storage to back the buffer of audit trail entries.


provider

protected StorageProvider provider
Storage provider which is used to allocate new buffer storages.

Constructor Detail

ATERandomFileBuffer

public ATERandomFileBuffer(StorageProvider aProvider)
                    throws java.io.IOException
Creates and initializes a new instance of this class.

Parameters:
aProvider - storage provider used for backing this buffer.
Throws:
java.io.IOException

ATERandomFileBuffer

public ATERandomFileBuffer(ATERandomFileBuffer template)
                    throws java.io.IOException
Creates a new instance of this class, which is an exact copy, or clone, of the provided template instance. The created clone will be independent, i.e. backed by a distinct persistent storage, and changes will not be synchronized between template and clone.

Parameters:
template - The template instance to be cloned.
Throws:
java.io.IOException
Method Detail

size

public int size()
Retrieves the number of audit trail entries recorded in this instance.

Returns:
number of audit trail entries recorded in this instance

index

public int index()
Retrieves the current internal, logical position of this collection.

Returns:

append

public void append(AuditTrailEntry ate)
            throws java.io.IOException
Appends a new audit trail entry to the end of this collection.

Notice that a call to this method does not affect the current position audit trail entries are read from.

Parameters:
ate - The audit trail entry to append
Throws:
java.io.IOException

get

public AuditTrailEntry get(int ateIndex)
                    throws java.io.IOException,
                           java.lang.IndexOutOfBoundsException
Retrieves the audit trail entry recorded at the specified position

Parameters:
ateIndex - Position of the requested audit trail entry, defined to be within [0, size()-1].
Returns:
The requested audit trail entry object.
Throws:
java.io.IOException
java.lang.IndexOutOfBoundsException

iterator

public java.util.Iterator iterator()
Returns an iterator on the audit trail entries buffered in this collection.

Returns:
an iterator interface to the managed audit trail entries.

cleanup

public void cleanup()
             throws java.io.IOException
Cleans up any non-volatile resources (e.g. temporary files) associated with this instance and resets the instance to an initial state.

Throws:
java.io.IOException

navigateToIndex

protected void navigateToIndex(int reqIndex)
                        throws java.io.IOException
Repositions the low-level layer to read from the specified index.

Parameters:
reqIndex - Index to position the file pointer to.
Throws:
java.io.IOException

resetPosition

protected void resetPosition()
Resets the position of the data access layer to read the next audit trail entry from the first position.


skipForward

protected void skipForward(int atesToSkip)
                    throws java.io.IOException
Repositions the position of the data access layer to skip the specified number of records towards the end of the file.

Parameters:
atesToSkip - Number of records to be skipped.
Throws:
java.io.IOException

skipBackward

protected void skipBackward(int atesToSkip)
                     throws java.io.IOException
Repositions the position of the data access layer to skip the specified number of records towards the beginning of the file.

Parameters:
atesToSkip - Number of records to be skipped.
Throws:
java.io.IOException

read

protected AuditTrailEntry read()
                        throws java.io.IOException
Reads an audit trail entry from the current position of the data access layer. Calling this method implies the advancement of the data access layer, so that the next call will yield the subsequent audit trail entry.

Returns:
Throws:
java.io.IOException

encode

protected byte[] encode(AuditTrailEntry ate)
                 throws java.io.IOException
Encodes the given audit trail entry object into a sequence of bytes. This byte array corresponds to the structure of an audit trail entry record, as specified in the beginning of this document, excluding the back-/forward offsets used for navigation.

Parameters:
ate - The audit trail entry to be encoded.
Returns:
byte array representing the audit trail entry without navigation offsets.
Throws:
java.io.IOException

cloneInstance

public ATERandomFileBuffer cloneInstance()
                                  throws java.io.IOException
Clones this instance.

Returns:
a clone of this instance
Throws:
java.io.IOException

finalize

protected void finalize()
                 throws java.lang.Throwable
Remove buffer file when this instance is garbage collected.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable