org.processmining.framework.log
Interface AuditTrailEntryList

All Known Implementing Classes:
AuditTrailEntryListImpl, AuditTrailEntryListProxy, ProxyAuditTrailEntryList

public interface AuditTrailEntryList

Defines abstract access and modification methods to an ordered set of audit trail entries.

The order of the list is defined by given indices, a natural order based on timestamps or creation time of the contained audit trail entries is not enforced. Note: The performance and optimized usage pattern of the represented instances is dependent on the respective implementation of this interface. The interface makes no assumption about the efficiency or cost of provided methods. You are strongly advised to consult the documentation for the implementation of this list in your context, if you want or need to optimize your application for performance.

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

Method Summary
 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.
 boolean consolidate()
          Consolidates this object, and transforms it into an optimized state.
 AuditTrailEntry get(int index)
          Retrieves the audit trail entry located at the given position, i.e.
 void insert(AuditTrailEntry ate, int index)
          Inserts the given audit trail entry at the given logical position, or index, within the list.
 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
 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.
 

Method Detail

size

int size()
Returns the current size of this audit trail entry list.

Returns:
The number of (valid) audit trail entries contained in this list.

get

AuditTrailEntry get(int index)
                    throws java.lang.IndexOutOfBoundsException,
                           java.io.IOException
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].

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

java.util.Iterator iterator()
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.

Returns:
An iterator over the contained audit trail entries.

append

int append(AuditTrailEntry ate)
           throws java.io.IOException
Appends a given audit trail entry to the end of the list.

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

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

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

int insertOrdered(AuditTrailEntry ate)
                  throws java.io.IOException
Inserts the given audit trail entry at the correct order position, depending on its timestamp.

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

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

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

AuditTrailEntry replace(AuditTrailEntry ate,
                        int index)
                        throws java.lang.IndexOutOfBoundsException,
                               java.io.IOException
Replaces the audit trail entry at the given position by another provided audit trail entry

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

boolean isTainted()
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.

Returns:
Whether this object is tainted.

consolidate

boolean consolidate()
                    throws java.io.IOException
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.

Returns:
Throws:
java.io.IOException

cloneInstance

AuditTrailEntryList cloneInstance()
                                  throws java.io.IOException
Returns a deep copy of this list of audit trail entries.

Modifications are not synchronized between original and clone.

Returns:
A deep copy of this list of audit trail entries.
Throws:
java.io.IOException

cleanup

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!

Throws:
java.io.IOException