org.processmining.framework.log.rfb
Class BufferedLogReader

java.lang.Object
  extended by org.processmining.framework.log.LogReader
      extended by org.processmining.framework.log.rfb.BufferedLogReader

public class BufferedLogReader
extends LogReader

This class implements a fast, SAX-based, log reader buffering log data partly on binary files residing in persistent storage. The purpose of using this log reader is to reduce the memory footprint of log data management, speed up general access and in particular sequential read access, and to allow random access to all data, including write access.

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

Field Summary
protected  LogData data
          Contains the currently valid processes, process instances, and log summary of the encapsulated log.
protected  LogFile file
          The log file from which event data is read.
protected  LogFilter filter
          LogFilter instance applied to this log.
protected  int instanceIteratorIndex
          The index for the built-in iterator over the contained process instances.
protected  boolean isValid
          Marker for thread synchronization; only after this attribute has been set to true, the data stored in this collection can be used.
protected  LogData originalData
          Contains the processes, process instances, and log summary as contained in the original log this reader is derived from.
protected  BufferedLogReader parent
          Parent log reader, from whose data and settings the respective instance has been derived.
protected  java.lang.Thread processingThread
          This thread is created and configured in the respective constructor.
protected  boolean processingThreadStarted
          Internal marker.
protected  int[] processInstancesToKeep
          Marks the indices of process instances in the parent's collection which this instance inherits.
 
Constructor Summary
protected BufferedLogReader(BufferedLogReader reader, int[] pitk)
          Create a deep clone of the provided buffered log reader, which only has the instances indicated in the provided integer array as indices.
protected BufferedLogReader(BufferedLogReader aReader, LogFilter aFilter)
          Creates a new instance, based on the original log data used by the provided parameter instance, but filtered with the provided log filter.
protected BufferedLogReader(LogFile aFile, LogFilter aFilter)
          Creates a new instance, parses the given log file and builds the log's data structures as random access swap files.
 
Method Summary
 void cleanup()
          Cleans up the log collection, removing all traces from the file system (buffers etc.)
 LogReader clone(int[] pitk)
          Clones this log reader, including all contained processes and process instances.
static LogReader createInstance(LogFilter aFilter, LogFile aFile)
          Creates a new instance, parses the given log file and builds the log's data structures as random access swap files.
static LogReader createInstance(LogReader reader, int[] pitk)
          Create a deep clone of the provided buffered log reader, which only has the instances indicated in the provided integer array as indices.
static LogReader createInstance(LogReader reader, LogFilter filter)
          Creates a new instance, based on the original log data used by the provided parameter instance, but filtered with the provided log filter.
protected  void ensureValidData()
          Helper method, which blocks passively until the log data container's data becomes available for reading.
protected  void filter()
          Applies the contained filter to the log data.
protected  void flagDataValid()
          Helper method, which flags this reader's data valid and notifies, i.e.
 LogFile getFile()
          Returns the log file instance that was given in the constructor.
 ProcessInstance getInstance(int index)
          Retrieves the process instance located at the given index within the encapsulated log file.
 LogData getLogData()
          Retrieves the set of log data underlying this log reader's current state.
 LogFilter getLogFilter()
          Returns the filter instance that was given in the constructor.
 LogSummary getLogSummary()
          Returns a LogSummary object with summarized info about the workflow log.
 LogData getOriginalData()
          Retrieves the set of log data contained in the original log, from which this log reader has been derived.
 Process getProcess(int index)
          Retrieves the process located at the given index within the encapsulated log file.
 int hashCode()
          Returns the hash code of this log reader.
 boolean hasNext()
          Iterator interface method.
 java.util.Iterator instanceIterator()
          Retrieves an iterator over the process instances contained in the encapsulated log file.
 boolean isSelection()
          Tells whether or not this logReader object represents a selection of a log, instead of a complete log.
 boolean isValid()
          Inquires, whether the respective instance is valid, i.e.
 ProcessInstance next()
          Iterator interface method.
 int numberOfInstances()
          Retrieves the number of process instances contained in this log file.
 int numberOfProcesses()
          Retrieves the number of processes contained in this log file.
 int[] processInstancesToKeep()
          Retrieves the indices of process instances which are not excluded from reading.
 java.util.Iterator processIterator()
          Retrieves an iterator over the processes contained in the encapsulated log file.
 void reset()
          Iterator interface method.
 java.lang.String toString()
          Returns a string representation of this log reader.
 
Methods inherited from class org.processmining.framework.log.LogReader
getInstances
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

file

protected LogFile file
The log file from which event data is read.


filter

protected LogFilter filter
LogFilter instance applied to this log.


processInstancesToKeep

protected int[] processInstancesToKeep
Marks the indices of process instances in the parent's collection which this instance inherits. This is only relevant for log readers, that are created as a selection of other log readers, and can be null otherwise.


parent

protected BufferedLogReader parent
Parent log reader, from whose data and settings the respective instance has been derived. Can be null, if the instance has been derived directly from an MXML log file.


processingThread

protected java.lang.Thread processingThread
This thread is created and configured in the respective constructor. Its purpose is to derive the instance's data set from either the original log, or a parent log reader. Invocation of the thread is suspended until the first access is attempted on the instance's data set.


processingThreadStarted

protected boolean processingThreadStarted
Internal marker. Remebers, whether the internal processing thread has already been started. Serves as synchronization when concurrent access is attempted, but still blocked by data acquisition.


data

protected LogData data
Contains the currently valid processes, process instances, and log summary of the encapsulated log.


originalData

protected LogData originalData
Contains the processes, process instances, and log summary as contained in the original log this reader is derived from.


instanceIteratorIndex

protected int instanceIteratorIndex
The index for the built-in iterator over the contained process instances.


isValid

protected boolean isValid
Marker for thread synchronization; only after this attribute has been set to true, the data stored in this collection can be used.

Constructor Detail

BufferedLogReader

protected BufferedLogReader(LogFile aFile,
                            LogFilter aFilter)
                     throws java.io.IOException,
                            org.xml.sax.SAXException,
                            javax.xml.parsers.ParserConfigurationException
Creates a new instance, parses the given log file and builds the log's data structures as random access swap files.

Parameters:
aFile - LogFile from which to read event data.
aFilter - LogFilter, which is to be applied to the contained log data.
Throws:
java.io.IOException
org.xml.sax.SAXException
javax.xml.parsers.ParserConfigurationException
javax.xml.parsers.ParserConfigurationException

BufferedLogReader

protected BufferedLogReader(BufferedLogReader aReader,
                            LogFilter aFilter)
                     throws java.io.IOException
Creates a new instance, based on the original log data used by the provided parameter instance, but filtered with the provided log filter. This constructor helps to speed up re-filtering of event log data, as the MXML parsing step can be omitted.

Parameters:
aReader - Buffered log reader from which to obtain the event log data.
aFilter - Log filter to be applied to the obtained event log data.
Throws:
java.io.IOException

BufferedLogReader

protected BufferedLogReader(BufferedLogReader reader,
                            int[] pitk)
                     throws java.lang.IndexOutOfBoundsException,
                            java.io.IOException
Create a deep clone of the provided buffered log reader, which only has the instances indicated in the provided integer array as indices.

Parameters:
reader - Template buffered log reader.
pitk - Process instance indices to keep.
Throws:
java.lang.IndexOutOfBoundsException
java.io.IOException
Method Detail

createInstance

public static LogReader createInstance(LogReader reader,
                                       LogFilter filter)
                                throws java.lang.Exception
Creates a new instance, based on the original log data used by the provided parameter instance, but filtered with the provided log filter. This factory method helps to speed up re-filtering of event log data, as the MXML parsing step can be omitted.

Parameters:
reader - Buffered log reader from which to obtain the event log data.
filter - Log filter to be applied to the obtained event log data.
Throws:
java.lang.Exception

createInstance

public static LogReader createInstance(LogFilter aFilter,
                                       LogFile aFile)
                                throws java.lang.Exception
Creates a new instance, parses the given log file and builds the log's data structures as random access swap files.

Parameters:
aFile - LogFile from which to read event data.
aFilter - LogFilter, which is to be applied to the contained log data.
Throws:
java.io.IOException
org.xml.sax.SAXException
javax.xml.parsers.ParserConfigurationException
javax.xml.parsers.ParserConfigurationException
java.lang.Exception

createInstance

public static LogReader createInstance(LogReader reader,
                                       int[] pitk)
                                throws java.lang.Exception
Create a deep clone of the provided buffered log reader, which only has the instances indicated in the provided integer array as indices.

Parameters:
reader - Template buffered log reader.
pitk - Process instance indices to keep.
Throws:
java.lang.IndexOutOfBoundsException
java.io.IOException
java.lang.Exception

isValid

public boolean isValid()
Inquires, whether the respective instance is valid, i.e. its data structures have been set up and processed, and its data has become readable.

Returns:
Validity of the instance.

flagDataValid

protected void flagDataValid()
Helper method, which flags this reader's data valid and notifies, i.e. wakes up, all waiting threads that want to access this data.


ensureValidData

protected void ensureValidData()
Helper method, which blocks passively until the log data container's data becomes available for reading.


getLogData

public LogData getLogData()
Retrieves the set of log data underlying this log reader's current state.

Returns:
a LogData container.

getOriginalData

public LogData getOriginalData()
Retrieves the set of log data contained in the original log, from which this log reader has been derived.

Returns:
a LogData container.

clone

public LogReader clone(int[] pitk)
Description copied from class: LogReader
Clones this log reader, including all contained processes and process instances. The contained process instances, whose indices are contained in the given integer array, are excluded and will not be contained in the returned clone.

Notice that this method will yield a deep copy of the cloned instance. This implies doubling this instance's memory consumption (either in random access memory or filesystem space consumption, depending on the implementation) and no synchronization of changes between original and clone.

Specified by:
clone in class LogReader
Parameters:
pitk - The contained process instances, whose indices are contained in the given integer array, are excluded and will not be contained in the returned clone.
Returns:
A clone of this log reader, excluding the process instances whose indices are given in the supplied array.

getFile

public LogFile getFile()
Description copied from class: LogReader
Returns the log file instance that was given in the constructor.

Specified by:
getFile in class LogReader
Returns:
the log file instance that was given in the constructor

getInstance

public ProcessInstance getInstance(int index)
Description copied from class: LogReader
Retrieves the process instance located at the given index within the encapsulated log file.

Specified by:
getInstance in class LogReader
Parameters:
index - index of the requested process instance in the log
Returns:
referenced process instance.

getLogFilter

public LogFilter getLogFilter()
Description copied from class: LogReader
Returns the filter instance that was given in the constructor.

Specified by:
getLogFilter in class LogReader
Returns:
the filter instance that was given in the constructor

getLogSummary

public LogSummary getLogSummary()
Description copied from class: LogReader
Returns a LogSummary object with summarized info about the workflow log. Note that, if a filter is used, any information provided in this object is based on the filtered log, not on the real contents of the log file.

Specified by:
getLogSummary in class LogReader
Returns:
a LogSummary object with summarized info about the workflow log

getProcess

public Process getProcess(int index)
Description copied from class: LogReader
Retrieves the process located at the given index within the encapsulated log file.

Specified by:
getProcess in class LogReader
Parameters:
index - index of the requested process in the log
Returns:
referenced process.

hasNext

public boolean hasNext()
Description copied from class: LogReader
Iterator interface method.

Probes whether the log reader has another process instance available for reading.

Specified by:
hasNext in class LogReader
Returns:

instanceIterator

public java.util.Iterator instanceIterator()
Description copied from class: LogReader
Retrieves an iterator over the process instances contained in the encapsulated log file.

Specified by:
instanceIterator in class LogReader
Returns:
an iterator over the contained process instances.

isSelection

public boolean isSelection()
Description copied from class: LogReader
Tells whether or not this logReader object represents a selection of a log, instead of a complete log.

Specified by:
isSelection in class LogReader
Returns:
true if it it a selection

next

public ProcessInstance next()
Description copied from class: LogReader
Iterator interface method.

Retrieves the next process instance from the log.

Specified by:
next in class LogReader
Returns:
The next process instance from the log.

numberOfInstances

public int numberOfInstances()
Description copied from class: LogReader
Retrieves the number of process instances contained in this log file.

Specified by:
numberOfInstances in class LogReader
Returns:
the number of process instances contained in this log file.

numberOfProcesses

public int numberOfProcesses()
Description copied from class: LogReader
Retrieves the number of processes contained in this log file.

Specified by:
numberOfProcesses in class LogReader
Returns:
the number of processes contained in this log file.

processInstancesToKeep

public int[] processInstancesToKeep()
Description copied from class: LogReader
Retrieves the indices of process instances which are not excluded from reading.

Specified by:
processInstancesToKeep in class LogReader
Returns:

processIterator

public java.util.Iterator processIterator()
Description copied from class: LogReader
Retrieves an iterator over the processes contained in the encapsulated log file.

Specified by:
processIterator in class LogReader
Returns:
an iterator over the contained processes.

reset

public void reset()
Description copied from class: LogReader
Iterator interface method.

Resets the main iterator to the first process instance.

Specified by:
reset in class LogReader

cleanup

public void cleanup()
             throws java.io.IOException
Cleans up the log collection, removing all traces from the file system (buffers etc.)

Warning: After calling this method, the respective log reader instance becomes unusable! All method calls subsequent to this one will return undefined results!

Throws:
java.io.IOException

filter

protected void filter()
               throws java.lang.IndexOutOfBoundsException,
                      java.io.IOException
Applies the contained filter to the log data. The log will be altered, and the sets of processes and instances, and the log summary will be changed.

Throws:
java.lang.IndexOutOfBoundsException
java.io.IOException

toString

public java.lang.String toString()
Returns a string representation of this log reader.

Specified by:
toString in class LogReader

hashCode

public int hashCode()
Returns the hash code of this log reader.

Overrides:
hashCode in class java.lang.Object