org.deckfour.xes.model.buffered
Class XSequentialEventBuffer

java.lang.Object
  org.deckfour.xes.model.buffered.XSequentialEventBuffer

All Implemented Interfaces:

Cloneable

public class XSequentialEventBuffer
extends Object
implements Cloneable

This class provides a random-access interface to a sequential set of events. These events 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 events, where records are encoded as follows:

• Offset in bytes to next record / size of record (4-byte integer)
• Offset in bytes to previous record (4-byte integer)
• ID of the event (serialization provided by XID class)

This fixed part is followed by the attribute map serialization for this event. Note that attribute maps may be recursive, i.e. attributes in an attribute map each have their own attribute map with meta-events. The depth of this recursion is not limited. An attribute map is serialized as follows:

• Number of attributes (as 4-byte integer)
• A corresponding number of attribute serializations

Attribute serializations are composed as follows:

• Attribute key (UTF-8 encoded String)
• Attribute value (UTF-8 encoded String)
• Attribute type (UTF-8 encoded String)
• Attribute extension URI (UTF-8 encoded String)
• Serialization of the attribute's attribute map (meta-attributes)

Author:

Christian W. Guenther (christian@deckfour.org)

Field Summary

protected static int

EXTENSION_GENERIC Encoding for non-existent extension (generic attributes)

Constructor Summary

protected	XSequentialEventBuffer()
	XSequentialEventBuffer(NikeFS2StorageProvider aProvider, XAttributeMapSerializer attributeMapSerializer) Creates and initializes a new instance of this class.

Method Summary

void	append(XEvent event) Appends a new event to the end of this collection.
void	cleanup() Cleans up any non-volatile resources (e.g.
Object	clone() Creates an identical clone of this buffer.
protected byte[]	encode(XEvent event) Encodes the given event into a sequence of bytes.
protected void	finalize() Remove buffer file when this instance is garbage collected.
XEvent	get(int eventIndex) Retrieves the event recorded at the specified position
NikeFS2StorageProvider	getProvider() Returns the storage provider used by this instance
NikeFS2RandomAccessStorage	getStorage() Returns the random access storage this instance is based on
int	index() Retrieves the current internal, logical position of this collection.
long	lastInsert() Returns the last insert position of this instance
protected void	navigateToIndex(int reqIndex) Repositions the low-level layer to read from the specified index.
long	position() Returns the current position of this instance
protected XEvent	read() Reads an event from the current position of the data access layer.
boolean	replace(XEvent event, int index) Replaces an event at the given position.
protected void	resetPosition() Resets the position of the data access layer to read the next event from the first position.
int	size() Retrieves the number of events recorded in this instance.
protected void	skipBackward(int eventsToSkip) 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 eventsToSkip) 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

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

Field Detail

EXTENSION_GENERIC

protected static final int EXTENSION_GENERIC

Encoding for non-existent extension (generic attributes)

See Also:

Constant Field Values

Constructor Detail

XSequentialEventBuffer

public XSequentialEventBuffer(NikeFS2StorageProvider aProvider,
                              XAttributeMapSerializer attributeMapSerializer)
                       throws IOException

Creates and initializes a new instance of this class.

Parameters:

aProvider - Storage provider used for backing this buffer.

attributeMapSerializer - Attribute map serializer to be used.

Throws:

IOException

XSequentialEventBuffer

protected XSequentialEventBuffer()

Method Detail

getProvider

public NikeFS2StorageProvider getProvider()

Returns the storage provider used by this instance

position

public long position()

Returns the current position of this instance

lastInsert

public long lastInsert()

Returns the last insert position of this instance

getStorage

public NikeFS2RandomAccessStorage getStorage()

Returns the random access storage this instance is based on

size

public int size()

Retrieves the number of events 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.

append

public void append(XEvent event)
            throws IOException

Appends a new event to the end of this collection.

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

Parameters:

ate - The event to append

Throws:

IOException

replace

public boolean replace(XEvent event,
                       int index)
                throws IOException

Replaces an event at the given position.

Parameters:

event - The new event to be inserted.

index - Index to replace at.

Returns:

The former event, having been replaced.

Throws:

IOException

get

public XEvent get(int eventIndex)
           throws IOException,
                  IndexOutOfBoundsException

Retrieves the event recorded at the specified position

Parameters:

eventIndex - Position of the requested event, defined to be within [0, size()-1].

Returns:

The requested event.

Throws:

IOException

IndexOutOfBoundsException

cleanup

public void cleanup()
             throws IOException

Cleans up any non-volatile resources (e.g. temporary files) associated with this instance and resets the instance to an initial state.

Throws:

IOException

navigateToIndex

protected void navigateToIndex(int reqIndex)
                        throws IOException

Repositions the low-level layer to read from the specified index.

Parameters:

reqIndex - Index to position the file pointer to.

Throws:

IOException

resetPosition

protected void resetPosition()

Resets the position of the data access layer to read the next event from the first position.

skipForward

protected void skipForward(int eventsToSkip)
                    throws IOException

Repositions the position of the data access layer to skip the specified number of records towards the end of the file.

Parameters:

eventsToSkip - Number of records to be skipped.

Throws:

IOException

skipBackward

protected void skipBackward(int eventsToSkip)
                     throws IOException

Repositions the position of the data access layer to skip the specified number of records towards the beginning of the file.

Parameters:

eventsToSkip - Number of records to be skipped.

Throws:

IOException

read

protected XEvent read()
               throws IOException

Reads an event 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 event.

Throws:

IOException

encode

protected byte[] encode(XEvent event)
                 throws IOException

Encodes the given event into a sequence of bytes. This byte array corresponds to the structure of an event record, as specified in the beginning of this document, excluding the back-/forward offsets used for navigation.

Parameters:

ate - The event to be encoded.

Returns:

byte Array representing the event without navigation offsets.

Throws:

IOException

clone

public Object clone()

Creates an identical clone of this buffer.

Overrides:

clone in class Object

finalize

protected void finalize()
                 throws Throwable

Remove buffer file when this instance is garbage collected.

Overrides:

finalize in class Object

Throws:

Throwable