de.aristaflow.adept2.core.logmanager

Interface Log

All Known Subinterfaces:

DataHistory, ExecutionHistory

public interface Log

The common superinterface for all specialised logs. It exclusively defines read-only methods. Specialised methods for reading and writing are defined in subinterfaces.

Author:

Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
long	count(SessionToken session, java.lang.String sqlWhereClause) Counts all log entries that match the specified WHERE clause.
java.lang.String	formatCondition(SessionToken session, java.lang.String conditionFormat, java.io.Serializable... values) Formats the given condition format string and values to an SQL condition that can e.g. be used in the WHERE clause of query(SessionToken, String, int) or read(SessionToken, String, String, int, String...).
java.lang.String	getName() Returns the name of this log.
Schema	getSchema() Returns the schema of this log.
java.sql.ResultSet	query(SessionToken session, java.lang.String sqlQuery, int maxEntries) Executes a user-defined SQL query on the data source of the associated log manager.
LogEntry	read(SessionToken session, long logEntryID, java.lang.String... columnNames) Reads the log entry with the specified ID.
LogEntrySet	read(SessionToken session, java.lang.String sqlWhereClause, java.lang.String sqlOrderByClause, int startEntry, int maxEntries, java.lang.String... columnNames) Reads all log entries that match the specified WHERE clause.
LogEntrySet	read(SessionToken session, java.lang.String sqlWhereClause, java.lang.String sqlOrderByClause, int maxEntries, java.lang.String... columnNames) Reads all log entries that match the specified WHERE clause.

Method Detail

getName

java.lang.String getName()

Returns the name of this log.

Returns:

the name of this log

getSchema

Schema getSchema()

Returns the schema of this log.

Returns:

the schema of this log

read

LogEntry read(SessionToken session,
              long logEntryID,
              java.lang.String... columnNames)
       throws DataSourceException

Reads the log entry with the specified ID. Only the specified columns are selected and contained in the returned log entry. If no columns are specified, all will be selected. The schema of the returned log entry matches the selected columns.

Parameters:

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

logEntryID - ID of the desired log entry

columnNames - the columns to be selected, i.e. that will be contained in the returned log entry; when no column is specified, all will be selected

Returns:

the desired log entry containing the selected columns or null if the entry does not exist

Throws:

DataSourceException - if an unrecoverable error occurs while accessing the data source

read

LogEntrySet read(SessionToken session,
                 java.lang.String sqlWhereClause,
                 java.lang.String sqlOrderByClause,
                 int maxEntries,
                 java.lang.String... columnNames)
          throws DataSourceException

Reads all log entries that match the specified WHERE clause. Only the specified columns are selected and contained in the returned log entry set. If no columns are specified, all will be selected. The schema of the returned log entry set matches the selected columns.

This method only returns the specified number of entries; all excess entries are silently dropped.

Parameters:

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

sqlWhereClause - the SQL WHERE clause (without the WHERE keyword) that determines which log entries should be read; may be null to read them all

sqlOrderByClause - the SQL ORDER BY clause (without the ORDER BY keywords) to determine the order of the log entries (but not their nested entries in complex columns); may be null (then the entries are sorted by id ASC, i.e. from old to new)

maxEntries - the maximum number of entries to return; the excess entries are silently dropped; 0 disables this limit

columnNames - the columns to be selected, i.e. that will be contained in the returned log entry set; when no column is specified, all will be selected

Returns:

a log entry set containing the selected columns of all matching log entries

Throws:

DataSourceException - if an unrecoverable error occurs while accessing the data source

read

LogEntrySet read(SessionToken session,
                 java.lang.String sqlWhereClause,
                 java.lang.String sqlOrderByClause,
                 int startEntry,
                 int maxEntries,
                 java.lang.String... columnNames)
          throws DataSourceException

Reads all log entries that match the specified WHERE clause. Only the specified columns are selected and contained in the returned log entry set. If no columns are specified, all will be selected. The schema of the returned log entry set matches the selected columns.

This method only returns the specified number of entries, starting at the specified entry (where 1 is the first entry of the unlimited result)); all excess entries are silently dropped.

Parameters:

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

sqlWhereClause - the SQL WHERE clause (without the WHERE keyword) that determines which log entries should be read; may be null to read them all

sqlOrderByClause - the SQL ORDER BY clause (without the ORDER BY keywords) to determine the order of the log entries (but not their nested entries in complex columns); may be null (then the entries are sorted by id ASC, i.e. from old to new)

startEntry - The entry with which the result should start (with 1 being the first entry of the unlimited result). This refers to the result set and not to any data within the result set, that is, with a descending order, a start entry of 1 is the highest element of the order.

maxEntries - the maximum number of entries to return; the excess entries are silently dropped; 0 disables this limit

columnNames - the columns to be selected, i.e. that will be contained in the returned log entry set; when no column is specified, all will be selected

Returns:

a log entry set containing the selected columns of all matching log entries

Throws:

DataSourceException - if an unrecoverable error occurs while accessing the data source

count

long count(SessionToken session,
           java.lang.String sqlWhereClause)
    throws DataSourceException

Counts all log entries that match the specified WHERE clause.

Parameters:

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

sqlWhereClause - the SQL WHERE clause (without the WHERE keyword) that determines which log entries should be counted

Returns:

the number of matching log entries

Throws:

DataSourceException - if an unrecoverable error occurs while accessing the data source

query

java.sql.ResultSet query(SessionToken session,
                         java.lang.String sqlQuery,
                         int maxEntries)
                  throws java.sql.SQLException

Executes a user-defined SQL query on the data source of the associated log manager.

This method is equivalent to LogManager.query(SessionToken, String, int), to which a call is usually redirected. See this method for more information.

Parameters:

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

sqlQuery - the SQL query to be executed

maxEntries - the maximum number of entries to return; the excess entries are silently dropped; 0 disables this limit

Returns:

a disconnected result set (i.e. all data is cached in memory)

Throws:

java.sql.SQLException - if a database access error occurs

See Also:

LogManager.query(SessionToken, String, int)

formatCondition

java.lang.String formatCondition(SessionToken session,
                                 java.lang.String conditionFormat,
                                 java.io.Serializable... values)
                          throws DataSourceException

Formats the given condition format string and values to an SQL condition that can e.g. be used in the WHERE clause of query(SessionToken, String, int) or read(SessionToken, String, String, int, String...). This method is equivalent to LogManager.formatCondition(SessionToken, Log, String, Serializable...), to which a call is usually redirected. See this method for more information.

Parameters:

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

conditionFormat - the condition format string

values - the values to be filled in the condition format string; the number of values must match the condition format string

Returns:

an SQL condition formatted from the given column, comparison operator and value

Throws:

DataSourceException - if an unrecoverable error occurs while accessing the data source