de.aristaflow.adept2.core.logmanager.logs

Interface ExecutionHistory

All Superinterfaces:

Log

public interface ExecutionHistory
extends Log

This is the defining interface for the execution history and its data structure. This interface directly only defines methods for read access. Write access can be gain through getWriteAccess().

Implementing classes must return SCHEMA in their Log.getSchema() method and NAME in their Log.getName() method.

Author:

Patrick Schmidt

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ExecutionHistory.ColumnName Contains constants for the names of all columns in the SCHEMA of the execution history.
static class	ExecutionHistory.StateChange Allowed values for the stateChange column.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	NAME The name of the execution history.
static Schema	SCHEMA The schema of the execution history.

Method Summary

Modifier and Type	Method and Description
long	countInstanceHistoryEntries(SessionToken session, java.util.UUID instanceLogID)
ExecutionHistoryWriteAccess	getWriteAccess() Returns the interface for write access to the execution history.
LogEntrySet	readAllNodeErrorInformation(SessionToken session, java.util.UUID instanceLogId, int nodeId, int iteration) Gets the log entries containing all error information for the specified instance, node and iteration starting with the most recent error.
java.util.List<WorkHistoryEntry>	readCompletedSteps(SessionToken session, long agentID, java.util.Collection<java.lang.Long> orgPositionIDs, long startEntryID, boolean newerEntries, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads all steps completed by the specified agent in the specified org position within the given time frame.
java.util.List<WorkHistoryEntry>	readCompletedSteps(SessionToken session, long agentID, java.util.Collection<java.lang.Long> orgPositionIDs, long fromTimestamp, long toTimestamp, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads all steps completed by the specified agent in the specified org position within the given time frame.
java.util.List<WorkHistoryEntry>	readCompletedSteps(SessionToken session, long agentID, long orgPositionID, long startEntryID, boolean newerEntries, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads all steps completed by the specified agent in the specified org position within the given time frame.
java.util.List<WorkHistoryEntry>	readCompletedSteps(SessionToken session, long agentID, long orgPositionID, long fromTimestamp, long toTimestamp, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads all steps completed by the specified agent in the specified org position within the given time frame.
java.util.List<ExecutionHistoryEntry>	readHistory(SessionToken session, java.lang.String whereClause, long startEntryID, boolean newerEntries, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads all logged events filtered by the designated where clause.
LogEntry	readInstanceErrorInformation(SessionToken session, java.util.UUID instanceLogID) ExecutionHistory.ColumnName.ERROR_CODE ExecutionHistory.ColumnName.ERROR_STATE ExecutionHistory.ColumnName.ERROR_MESSAGE
java.util.List<ExecutionHistoryEntry>	readInstanceHistory(SessionToken session, java.util.UUID instanceLogID, long startEntryID, boolean newerEntries, int maxEntries, boolean sortAscending, java.util.Locale... preferredLocales) Reads logged events for the instance with the given log ID.
LogEntry	readNodeErrorInformation(SessionToken session, java.util.UUID instanceLogID, int nodeID, int nodeIteration) Returns the log entry containing the most recent error information for the specified instance, node and iteration or null if there is no error information available.
LogEntrySet	readPreviousSteps(SessionToken session, java.util.UUID instanceLogID, int nodeID, int iteration) Reads the past finished steps in the specified instance that occurred before the specified node in its specified iteration.

Methods inherited from interface de.aristaflow.adept2.core.logmanager.Log

count, formatCondition, getName, getSchema, query, read, read, read

Field Detail

NAME

static final java.lang.String NAME

The name of the execution history. Implementing classes must return this constant in their Log.getName() method.

See Also:

Constant Field Values

SCHEMA

static final Schema SCHEMA

The schema of the execution history. Implementing classes must return this constant in their Log.getSchema() method.

Method Detail

readHistory

java.util.List<ExecutionHistoryEntry> readHistory(SessionToken session,
                                                  java.lang.String whereClause,
                                                  long startEntryID,
                                                  boolean newerEntries,
                                                  int maxEntries,
                                                  boolean sortAscending,
                                                  java.util.Locale... preferredLocales)
                                           throws DataSourceException

Reads all logged events filtered by the designated where clause.

Parameters:

session - The session which is used to check for access rights on this method.

whereClause - The where clause (without starting "WHERE" with which to filter the execution history log entries.

startEntryID - ID of the entry with which to start; it is not necessary that an entry with exactly this ID actually exists, so using Long.MAX_VALUE and 0 to start at an process instance's end or beginning respectively is common practise. Please note: This is not the index within the instance's history, but the unique ID for every entry in the execution history.

newerEntries - if true the start entry and all newer entries are retrieved; if false the start entry and all older entries are retrieved

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

The list of all execution history entries that match the designated where clause and the other specified parameters.

Throws:

DataSourceException - if a problem occurs related to accessing the data source

readInstanceHistory

java.util.List<ExecutionHistoryEntry> readInstanceHistory(SessionToken session,
                                                          java.util.UUID instanceLogID,
                                                          long startEntryID,
                                                          boolean newerEntries,
                                                          int maxEntries,
                                                          boolean sortAscending,
                                                          java.util.Locale... preferredLocales)
                                                   throws DataSourceException

Reads logged events for the instance with the given log ID.

Parameters:

session - The session which is used to check for access rights on this method.

instanceLogID - The log ID of the instance for which to retrieve the execution history (i.e. all logged events related to this instance). Do NOT use the logical ID of the instance here.

startEntryID - ID of the entry with which to start; it is not necessary that an entry with exactly this ID actually exists, so using Long.MAX_VALUE and 0 to start at an process instance's end or beginning respectively is common practise. Please note: This is not the index within the instance's history, but the unique ID for every entry in the execution history.

newerEntries - if true the start entry and all newer entries are retrieved; if false the start entry and all older entries are retrieved

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

the list of execution history entries for the instance that match the specified parameters

Throws:

DataSourceException - if a problem occurs related to accessing the data source

countInstanceHistoryEntries

long countInstanceHistoryEntries(SessionToken session,
                                 java.util.UUID instanceLogID)
                          throws DataSourceException

Throws:

DataSourceException

readPreviousSteps

LogEntrySet readPreviousSteps(SessionToken session,
                              java.util.UUID instanceLogID,
                              int nodeID,
                              int iteration)
                       throws DataSourceException

Reads the past finished steps in the specified instance that occurred before the specified node in its specified iteration. The entries are sorted in descending order (i.e. the latest steps are at the top).

If the specified node in the specified instance hasn't yet finished in the specified iteration, null is returned. This is also the case when instance ID or node ID are unknown.

Parameters:

session - The session which is used to check for access rights on this method.

instanceLogID - The log ID of the instance for which to read the finished steps. Do NOT use the logical ID of the instance here.

Throws:

DataSourceException

readCompletedSteps

java.util.List<WorkHistoryEntry> readCompletedSteps(SessionToken session,
                                                    long agentID,
                                                    long orgPositionID,
                                                    long fromTimestamp,
                                                    long toTimestamp,
                                                    int maxEntries,
                                                    boolean sortAscending,
                                                    java.util.Locale... preferredLocales)

Reads all steps completed by the specified agent in the specified org position within the given time frame.

Parameters:

session - The session which is used to check for access rights on this method.

agentID - the ID of the agent for whom to retrieve the completed steps

orgPositionID - the ID of the org position for which to retrieve the completed steps

fromTimestamp - the timestamp of the start of the desired time frame

toTimestamp - the timestamp of the end of the desired time frame

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

the list of completed steps that match the specified parameters

Throws:

InternalServiceException - if a problem occurs related to accessing the data source

readCompletedSteps

java.util.List<WorkHistoryEntry> readCompletedSteps(SessionToken session,
                                                    long agentID,
                                                    java.util.Collection<java.lang.Long> orgPositionIDs,
                                                    long fromTimestamp,
                                                    long toTimestamp,
                                                    int maxEntries,
                                                    boolean sortAscending,
                                                    java.util.Locale... preferredLocales)

Reads all steps completed by the specified agent in the specified org position within the given time frame.

Parameters:

session - The session which is used to check for access rights on this method.

agentID - the ID of the agent for whom to retrieve the completed steps

orgPositionIDs - optional list of org position IDs of the agent for which to retrieve the completed steps; if null or empty, all completed steps will be retrieved regardless of the org position

fromTimestamp - the timestamp of the start of the desired time frame

toTimestamp - the timestamp of the end of the desired time frame

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

the list of completed steps that match the specified parameters

Throws:

InternalServiceException - if a problem occurs related to accessing the data source

readCompletedSteps

java.util.List<WorkHistoryEntry> readCompletedSteps(SessionToken session,
                                                    long agentID,
                                                    long orgPositionID,
                                                    long startEntryID,
                                                    boolean newerEntries,
                                                    int maxEntries,
                                                    boolean sortAscending,
                                                    java.util.Locale... preferredLocales)

Reads all steps completed by the specified agent in the specified org position within the given time frame.

Parameters:

session - The session which is used to check for access rights on this method.

agentID - the ID of the agent for whom to retrieve the completed steps

orgPositionID - the ID of the org position for which to retrieve the completed steps

startEntryID - ID of the execution history entry with which to start; it is not necessary that an entry with exactly this ID actually exists, so using Long.MAX_VALUE and 0 to start at the present or past respectively is common practise

newerEntries - if true the start entry and all newer entries are retrieved; if false the start entry and all older entries are retrieved

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

the list of completed steps that match the specified parameters

Throws:

InternalServiceException - if a problem occurs related to accessing the data source

readCompletedSteps

java.util.List<WorkHistoryEntry> readCompletedSteps(SessionToken session,
                                                    long agentID,
                                                    java.util.Collection<java.lang.Long> orgPositionIDs,
                                                    long startEntryID,
                                                    boolean newerEntries,
                                                    int maxEntries,
                                                    boolean sortAscending,
                                                    java.util.Locale... preferredLocales)

Reads all steps completed by the specified agent in the specified org position within the given time frame.

Parameters:

session - The session which is used to check for access rights on this method.

agentID - the ID of the agent for whom to retrieve the completed steps

orgPositionIDs - optional list of org position IDs of the agent for which to retrieve the completed steps; if null or empty, all completed steps will be retrieved regardless of the org position

startEntryID - ID of the execution history entry with which to start; it is not necessary that an entry with exactly this ID actually exists, so using Long.MAX_VALUE and 0 to start at the present or past respectively is common practise

newerEntries - if true the start entry and all newer entries are retrieved; if false the start entry and all older entries are retrieved

maxEntries - the maximum number of entries to be returned; 0 will return all found entries

sortAscending - whether to sort the entries in ascending chronological order; will be sorted in descending order otherwise

preferredLocales - the desired locales in order of their preference for localised template, instance and node names. For each locale the typical fallbacks will automatically occur (e.g. de_DE -> de) before the next specified locale is considered. If no localisation is found the default (locale-less) names will be returned.

Returns:

the list of completed steps that match the specified parameters

Throws:

InternalServiceException - if a problem occurs related to accessing the data source

readInstanceErrorInformation

LogEntry readInstanceErrorInformation(SessionToken session,
                                      java.util.UUID instanceLogID)
                               throws DataSourceException

• ExecutionHistory.ColumnName.ERROR_CODE
• ExecutionHistory.ColumnName.ERROR_STATE
• ExecutionHistory.ColumnName.ERROR_MESSAGE

Returns:

... or null if no log entry with the specified instance log ID and ExecutionHistory.StateChange.INSTANCE_FAILED was found

Throws:

DataSourceException

readNodeErrorInformation

LogEntry readNodeErrorInformation(SessionToken session,
                                  java.util.UUID instanceLogID,
                                  int nodeID,
                                  int nodeIteration)
                           throws DataSourceException

Returns the log entry containing the most recent error information for the specified instance, node and iteration or null if there is no error information available. The contained columns are

• ExecutionHistory.ColumnName.ERROR_CODE
• ExecutionHistory.ColumnName.ERROR_STATE
• ExecutionHistory.ColumnName.ERROR_MESSAGE

Parameters:

session - The session which is used to check for access rights on this method.

instanceLogID - The log ID of the instance. Do NOT use the logical ID of the instance here.

nodeID - The ID of the node of which to retrieve the error information.

nodeIteration - The iteration of the node of which to retrieve the error information.

Returns:

The log entry containing the most recent error information or null if there is no error information available.

Throws:

DataSourceException

See Also:

ExecutionHistory.ColumnName.ERROR_CODE, ExecutionHistory.ColumnName.ERROR_STATE, ExecutionHistory.ColumnName.ERROR_MESSAGE

readAllNodeErrorInformation

LogEntrySet readAllNodeErrorInformation(SessionToken session,
                                        java.util.UUID instanceLogId,
                                        int nodeId,
                                        int iteration)
                                 throws DataSourceException

Gets the log entries containing all error information for the specified instance, node and iteration starting with the most recent error. The contained column on top-level is

• ExecutionHistory.ColumnName.ERROR

on second level there are the following columns:

• ExecutionHistory.ColumnName.ERROR_CODE
• ExecutionHistory.ColumnName.ERROR_STATE
• ExecutionHistory.ColumnName.ERROR_MESSAGE

Parameters:

session - The session which is used to check for access rights on this method.

instanceLogId - The log ID of the instance. Do NOT use the logical ID of the instance here.

nodeId - The ID of the node of which to retrieve the error information.

iteration - The iteration of the node of which to retrieve the error information.

Returns:

The log entries containing all error information of the designated node and iteration. This will be the empty if the node iteration has not failed yet.

Throws:

DataSourceException - If there are problems retrieving the node error information from the data source, a DataSourceException will be thrown.

See Also:

ExecutionHistory.ColumnName.ERROR_CODE, ExecutionHistory.ColumnName.ERROR_STATE, ExecutionHistory.ColumnName.ERROR_MESSAGE

getWriteAccess

ExecutionHistoryWriteAccess getWriteAccess()

Returns the interface for write access to the execution history.

Returns:

the interface for write access to the execution history