org.processmining.framework.log.rfb
Class AuditTrailEntryListImpl

java.lang.Object
  extended by org.processmining.framework.log.rfb.AuditTrailEntryListImpl
All Implemented Interfaces:
AuditTrailEntryList

public class AuditTrailEntryListImpl
extends java.lang.Object
implements AuditTrailEntryList

This class implements the AuditTrailEntryList interface in an efficient way. Efficient in this context may be read as best-effort approach to limit runtime overhead when accessing and modifying a collection of audit trail entries. Runtime overhead has been optimized following an expected typical usage pattern, which makes the following assumptions.

Author:
Christian W. Guenther (christian at deckfour dot org)

Field Summary
static int DEFAULT_FRAGMENTATION_LIMIT
          Default maximal fragmentation to allow, as sum of removed and inserted (not appended!) audit trail entries
protected  ATERandomFileBuffer fileBuffer
          Underlying file buffer holding the main audit trail entry stock.
protected  int fragLimit
          Maximal fragmentation to allow, as sum of removed and inserted (not appended!) audit trail entries
protected  int[] overflowIndices
          Array containing the (virtual) indices of inserted (but not yet consolidated) audit trail entries.
protected  java.util.ArrayList<AuditTrailEntryImpl> overflowList
          Ordered list containing the inserted audit trail entries, which have not yet been consolidated.
protected  int removedCounter
          Counts the number of removed audit trail entries which are ignored in the file buffer.
protected  int[] removedIndices
          Array containing the (file buffer based) indices of removed, i.e.
 
Constructor Summary
AuditTrailEntryListImpl()
          Creates a new, empty list of audit trail entries with the default fragmentation limit.
AuditTrailEntryListImpl(ATERandomFileBuffer initialBuffer, int maxFragment)
          Creates a new list of audit trail entries.
AuditTrailEntryListImpl(AuditTrailEntryListImpl template)
          Creates a new list of audit trail entries, which is a clone of the provided template instance.
AuditTrailEntryListImpl(AuditTrailEntryListImpl template, int maxFragment)
          Creates a new list of audit trail entries, which is a clone of the provided template instance.
 
Method Summary
protected  int addEntryToOverflowIndicesVirtual(int index)
          Inserts a given virtual index into the list of overflow entry positions; Implies incrementing the subsequent entries by 1 each.
protected  int addEntryToRemovedListFb(int index)
          Inserts a given file buffer based index into the list of removed entry positions;
 int append(AuditTrailEntry ate)
          Appends a given audit trail entry to the end of the list.
 void cleanup()
          Frees all resources associated with this instance.
 AuditTrailEntryList cloneInstance()
          Returns a deep copy of this list of audit trail entries, which is backed by exact copies of the underlying swap file.
 boolean consolidate()
          Consolidates this object, and transforms it into an optimized state.
protected  boolean consolidate(boolean force)
          Performs a consolidation of the internal data structures.
 int fragmentation()
           
 AuditTrailEntry get(int index)
          Retrieves the audit trail entry located at the given position, i.e.
protected  AuditTrailEntry getFromOverflowVirt(int index)
          Retrieves the audit trail entry with the given virtual index from the overflow list.
 void insert(AuditTrailEntry ate, int index)
          Inserts the given audit trail entry at the given logical position, or index, within the list.
protected  void insert(AuditTrailEntry ate, int index, boolean consolidate)
           
 int insertOrdered(AuditTrailEntry ate)
          Inserts the given audit trail entry at the correct order position, depending on its timestamp.
 boolean isTainted()
          Probes whether the implementing structure is in a tainted state.
 java.util.Iterator iterator()
          Retrieves an iterator on this list.
 AuditTrailEntry remove(int index)
          Removes the audit trail entry at the given position, or index, from the list
protected  AuditTrailEntry remove(int index, boolean consolidate)
           
 AuditTrailEntry replace(AuditTrailEntry ate, int index)
          Replaces the audit trail entry at the given position by another provided audit trail entry
 int size()
          Returns the current size of this audit trail entry list.
protected  int translateFileBufferIndexToVirtual(int fbIndex)
          Translates a given index within the file buffer to the virtual index the referenced audit trail entry represents.
protected  int translateVirtualIndexToFileBuffer(int virtualIndex)
          Translates a given virtual index, as used by using classes, into the actual index of the requested audit trail entry within the file buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_FRAGMENTATION_LIMIT

public static int DEFAULT_FRAGMENTATION_LIMIT
Default maximal fragmentation to allow, as sum of removed and inserted (not appended!) audit trail entries


fragLimit

protected int fragLimit
Maximal fragmentation to allow, as sum of removed and inserted (not appended!) audit trail entries


overflowIndices

protected int[] overflowIndices
Array containing the (virtual) indices of inserted (but not yet consolidated) audit trail entries. Their position in this array corresponds to their position in the overflow list.


removedIndices

protected int[] removedIndices
Array containing the (file buffer based) indices of removed, i.e. ignored, audit trail entries within the file buffer object


removedCounter

protected int removedCounter
Counts the number of removed audit trail entries which are ignored in the file buffer.


overflowList

protected java.util.ArrayList<AuditTrailEntryImpl> overflowList
Ordered list containing the inserted audit trail entries, which have not yet been consolidated.


fileBuffer

protected ATERandomFileBuffer fileBuffer
Underlying file buffer holding the main audit trail entry stock. When addressing the file buffer, virtual indices (as interpreted by using classes) need to be adjusted based on the structure of removed, i.e. ignored, and inserted (but not yet consolidated) audit trail entries.

Constructor Detail

AuditTrailEntryListImpl

public AuditTrailEntryListImpl()
                        throws java.io.IOException
Creates a new, empty list of audit trail entries with the default fragmentation limit.

Throws:
java.io.IOException

AuditTrailEntryListImpl

public AuditTrailEntryListImpl(ATERandomFileBuffer initialBuffer,
                               int maxFragment)
Creates a new list of audit trail entries.

Parameters:
initialBuffer - File buffer containing the initial set of audit trail entries. This file buffer must be in a consolidated state.
maxFragment - Maximal level of fragmentation for the created instance. Fragmentation is the sum of inserted (but not yet consolidated) and removed, i.e. ignored, audit trail entries in an AuditTrailEntryList.

AuditTrailEntryListImpl

public AuditTrailEntryListImpl(AuditTrailEntryListImpl template)
                        throws java.io.IOException
Creates a new list of audit trail entries, which is a clone of the provided template instance. The clone will hold the exactly same state as the template, but further changes will not be synchronized between template and clone.

Clones will be non-tainted, which is achieved by consolidating the cloned template instance in advance. Be aware, that your template is consolidated after using it as template in this constructor.

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

AuditTrailEntryListImpl

public AuditTrailEntryListImpl(AuditTrailEntryListImpl template,
                               int maxFragment)
                        throws java.io.IOException
Creates a new list of audit trail entries, which is a clone of the provided template instance. The clone will hold the exactly same state as the template, but further changes will not be synchronized between template and clone.

Clones will be non-tainted, which is achieved by consolidating the cloned template instance in advance. Be aware, that your template is consolidated after using it as template in this constructor.

Parameters:
template - The template instance to be cloned.
maxFragment - Maximal level of fragmentation for the created instance. Fragmentation is the sum of inserted (but not yet consolidated) and removed, i.e. ignored, audit trail entries in an AuditTrailEntryList.
Throws:
java.io.IOException
Method Detail

size

public int size()
Description copied from interface: AuditTrailEntryList
Returns the current size of this audit trail entry list.

Specified by:
size in interface AuditTrailEntryList
Returns:
The number of (valid) audit trail entries contained in this list.

get

public AuditTrailEntry get(int index)
                    throws java.lang.IndexOutOfBoundsException,
                           java.io.IOException
Description copied from interface: AuditTrailEntryList
Retrieves the audit trail entry located at the given position, i.e. index, in the list.

The usage contract for indices in this context is, that the given value must reside within [0, size() - 1].

Specified by:
get in interface AuditTrailEntryList
Parameters:
index - Position of the requested audit trail entry (within [0, size() - 1])
Returns:
The requested audit trail entry object
Throws:
java.lang.IndexOutOfBoundsException - Thrown when given index is invalid
java.io.IOException - Thrown on general I/O failures

iterator

public java.util.Iterator iterator()
Description copied from interface: AuditTrailEntryList
Retrieves an iterator on this list.

Warning: Iterators on audit trail entry lists are not required to be consistent. When the list is modified during the lifetime of an iterator, this iterator becomes inconsistent and may return wrong results or perform in unexpected manner. You are advised to use modifying iterators exclusively, and not perform modifying operations on the list while using the iterator. Multiple read-only iterators on the same list will perform independently, each as expected.

Specified by:
iterator in interface AuditTrailEntryList
Returns:
An iterator over the contained audit trail entries.

append

public int append(AuditTrailEntry ate)
           throws java.io.IOException
Description copied from interface: AuditTrailEntryList
Appends a given audit trail entry to the end of the list.

Specified by:
append in interface AuditTrailEntryList
Parameters:
ate - The audit trail entry to append to the list.
Returns:
The index, or position, within the list at which the audit trail entry has been inserted.
Throws:
java.io.IOException - Thrown on I/O failure

insert

public void insert(AuditTrailEntry ate,
                   int index)
            throws java.lang.IndexOutOfBoundsException,
                   java.io.IOException
Description copied from interface: AuditTrailEntryList
Inserts the given audit trail entry at the given logical position, or index, within the list.

Specified by:
insert in interface AuditTrailEntryList
Parameters:
ate - The audit trail entry to be inserted.
index - Index, or position within the list, at which to insert the audit trail entry. Must be within [0, size()].
Throws:
java.lang.IndexOutOfBoundsException - Thrown if the given index is not within [0, size()].
java.io.IOException - Thrown on I/O failure.

insertOrdered

public int insertOrdered(AuditTrailEntry ate)
                  throws java.io.IOException
Description copied from interface: AuditTrailEntryList
Inserts the given audit trail entry at the correct order position, depending on its timestamp.

Specified by:
insertOrdered in interface AuditTrailEntryList
Parameters:
ate - The audit trail entry to be inserted
Returns:
Index, at which the audit trail entry has been inserted in the list
Throws:
java.io.IOException

remove

public AuditTrailEntry remove(int index)
                       throws java.lang.IndexOutOfBoundsException,
                              java.io.IOException
Description copied from interface: AuditTrailEntryList
Removes the audit trail entry at the given position, or index, from the list

Specified by:
remove in interface AuditTrailEntryList
Parameters:
index - Position of the audit trail entry to be removed (within [0, size() - 1]).
Returns:
The removed audit trail entry.
Throws:
java.lang.IndexOutOfBoundsException - Thrown if the given index is not within [0, size() - 1].
java.io.IOException

replace

public AuditTrailEntry replace(AuditTrailEntry ate,
                               int index)
                        throws java.lang.IndexOutOfBoundsException,
                               java.io.IOException
Description copied from interface: AuditTrailEntryList
Replaces the audit trail entry at the given position by another provided audit trail entry

Specified by:
replace in interface AuditTrailEntryList
Parameters:
ate - Audit trail entry to be inserted at the specified index.
index - Index at which the current audit trail entry is removed, and the provided one is inserted. Must be within [0, size() - 1].
Returns:
The previous audit trail entry which was replaced and removed from the log.
Throws:
java.lang.IndexOutOfBoundsException - Thrown if the index is not within [0, size() - 1].
java.io.IOException - Thrown on I/O failure.

isTainted

public boolean isTainted()
Description copied from interface: AuditTrailEntryList
Probes whether the implementing structure is in a tainted state.

Tainted, in this context, is defined as not being structured in an optimal fashion. Tainted instances can be identified using their method isTainted(). They may be transformed into an optimized state by calling their consolidate() method.

In general, consolidation is supposed to be expensive. Implementations of this interface are expected to consolidate themselves at specified events or intervals. You should not manually consolidate an instance other than if you know what you are doing, and what for.

One situation where manual consolidation is suggested is, when you stop modifying a list of audit trail entries and want to start excessive read operations on it (which are not interleaved with modifying operations). For details to tainting and consolidation, refer to the documentation of the implementing classes.

Specified by:
isTainted in interface AuditTrailEntryList
Returns:
Whether this object is tainted.

consolidate

public boolean consolidate()
                    throws java.io.IOException
Description copied from interface: AuditTrailEntryList
Consolidates this object, and transforms it into an optimized state.

Tainted, in this context, is defined as not being structured in an optimal fashion. Tainted instances can be identified using their method isTainted(). They may be transformed into an optimized state by calling their consolidate() method.

In general, consolidation is supposed to be expensive. Implementations of this interface are expected to consolidate themselves at specified events or intervals. You should not manually consolidate an instance other than if you know what you are doing, and what for.

One situation where manual consolidation is suggested is, when you stop modifying a list of audit trail entries and want to start excessive read operations on it (which are not interleaved with modifying operations). For details to tainting and consolidation, refer to the documentation of the implementing classes.

Specified by:
consolidate in interface AuditTrailEntryList
Returns:
Throws:
java.io.IOException

fragmentation

public int fragmentation()
Returns:
the fragmentation degree of this instance, as sum of the number of removed, i.e. ignored, audit trail entries and the number of newly inserted audit trail entries, which have not yet been consolidated.

cloneInstance

public AuditTrailEntryList cloneInstance()
                                  throws java.io.IOException
Returns a deep copy of this list of audit trail entries, which is backed by exact copies of the underlying swap file. Changes between this instance and the created clone are not synchronized!

Specified by:
cloneInstance in interface AuditTrailEntryList
Returns:
A deep copy of this list.
Throws:
java.io.IOException

cleanup

public void cleanup()
             throws java.io.IOException
Frees all resources associated with this instance.

This method should be invoked, when it is foreseeable that this instance will no longer be accessed in any way. Do not attempt to access this instance after this method has been invoked, as things are about to get ugly otherwise!

Specified by:
cleanup in interface AuditTrailEntryList
Throws:
java.io.IOException

remove

protected AuditTrailEntry remove(int index,
                                 boolean consolidate)
                          throws java.lang.IndexOutOfBoundsException,
                                 java.io.IOException
Throws:
java.lang.IndexOutOfBoundsException
java.io.IOException

insert

protected void insert(AuditTrailEntry ate,
                      int index,
                      boolean consolidate)
               throws java.io.IOException
Throws:
java.io.IOException

getFromOverflowVirt

protected AuditTrailEntry getFromOverflowVirt(int index)
Retrieves the audit trail entry with the given virtual index from the overflow list.

Parameters:
index - Index of the requested audit trail entry.
Returns:
the requested audit trail entry, or null if the requested index is not contained in the overflow list.

translateVirtualIndexToFileBuffer

protected int translateVirtualIndexToFileBuffer(int virtualIndex)
                                         throws java.lang.IndexOutOfBoundsException
Translates a given virtual index, as used by using classes, into the actual index of the requested audit trail entry within the file buffer.

Warning: This method assumes that the requested audit trail entry is indeed located within the file buffer. Failure to comply to this assumption will yield wrong results.

Parameters:
virtualIndex - virtual index
Returns:
actual file buffer based index
Throws:
java.lang.IndexOutOfBoundsException

translateFileBufferIndexToVirtual

protected int translateFileBufferIndexToVirtual(int fbIndex)
Translates a given index within the file buffer to the virtual index the referenced audit trail entry represents.

Parameters:
fbIndex - actual index of the ATE entry within the file buffer.
Returns:
virtual index of the referenced ATE entry.

addEntryToOverflowIndicesVirtual

protected int addEntryToOverflowIndicesVirtual(int index)
Inserts a given virtual index into the list of overflow entry positions; Implies incrementing the subsequent entries by 1 each.

Parameters:
index - The requested virtual index of the ATE to be inserted.
Returns:
the index of the given index entry within the overflow array.

addEntryToRemovedListFb

protected int addEntryToRemovedListFb(int index)
                               throws java.lang.IndexOutOfBoundsException
Inserts a given file buffer based index into the list of removed entry positions;

Parameters:
index - The requested virtual index of the ATE to be removed.
Returns:
the index of the given index entry within the overflow array.
Throws:
java.lang.IndexOutOfBoundsException

consolidate

protected boolean consolidate(boolean force)
                       throws java.lang.IndexOutOfBoundsException,
                              java.io.IOException
Performs a consolidation of the internal data structures. Overflow and removal lists will be cleared and merged with the file buffer into a new file buffer. This operation is pretty expensive, but can gain speed improvements when the instance becomes too fragmented between file buffer and overflow / removal structures.

Parameters:
force - If this parameter is set to true, consolidation is performed also when the specified fragmentation limit has not been exceeded yet. When set to false, the fragmentation limit is respected for runtime optimization.
Returns:
Throws:
java.lang.IndexOutOfBoundsException
java.io.IOException