Package org.deckfour.xes.model.buffered

Class XSequentialEventBuffer

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class XSequentialEventBuffer
extends java.lang.Object
implements java.lang.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

      Fields 
      Modifier and Type Field Description
      protected static int EXTENSION_GENERIC
      Encoding for non-existent extension (generic attributes)

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void append​(XEvent event)
      Appends a new event to the end of this collection.
      void cleanup()
      Cleans up any non-volatile resources (e.g.
      java.lang.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 java.io.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:
        java.io.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

      • 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 java.io.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:
        java.io.IOException

      • replace

        public boolean replace​(XEvent event,
                       int index)
                throws java.io.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:
        java.io.IOException

      • get

        public XEvent get​(int eventIndex)
           throws java.io.IOException,
                  java.lang.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:
        java.io.IOException
        java.lang.IndexOutOfBoundsException

      • 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 event from the first position.

      • skipForward

        protected void skipForward​(int eventsToSkip)
                    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:
        eventsToSkip - Number of records to be skipped.
        Throws:
        java.io.IOException

      • skipBackward

        protected void skipBackward​(int eventsToSkip)
                     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:
        eventsToSkip - Number of records to be skipped.
        Throws:
        java.io.IOException

      • read

        protected XEvent read()
               throws java.io.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:
        java.io.IOException

      • encode

        protected byte[] encode​(XEvent event)
                 throws java.io.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:
        java.io.IOException

      • clone

        public java.lang.Object clone()
        Creates an identical clone of this buffer.
        Overrides:
        clone in class java.lang.Object

      • 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