Process API

filenet.vw.api
Class VWLog

java.lang.Object
  extended by filenet.vw.api.VWLog
All Implemented Interfaces:
java.io.Serializable

public final class VWLog
extends java.lang.Object

Use this class to query logs, determine the associated session, and access the log definition. The VWSession.fetchEventLog() method instantiates this class. Once you have a VWLog object, you can query logs, based on different query criteria.

Since:
VWWS3.10
See Also:
VWSession, VWLogQuery, VWLogDefinition, Serialized Form

Field Summary
static int QUERY_GET_NO_TRANSLATED_SYSTEM_FIELDS
          Value of 2048. Include this value in the queryFlags parameter of the createQuery() method to return objects without translated system fields.
static int QUERY_MAX_VALUES_INCLUSIVE
          Value of 64. This value is used as a possible value for the queryFlags parameter of the startQuery method.
static int QUERY_MIN_VALUES_INCLUSIVE
          Integer value of 32. This value is used as a possible value for the queryFlags parameter of the startQuery method.
static int QUERY_NO_OPTIONS
          Value of 0. This value is used as a possible value for the queryFlags parameter of the startQuery method.
static int QUERY_RESOLVE_NAMES
          Value of 8192.
 
Method Summary
static java.lang.String _get_FILE_AUTHOR()
          For FileNet internal use only, do not call.
static java.lang.String _get_FILE_DATE()
          For FileNet internal use only, do not call.
static java.lang.String _get_FILE_REVISION()
          For FileNet internal use only, do not call.
 VWLogDefinition fetchLogDefinition()
          Fetches the log definition.
 java.lang.String getAuthoredName()
          Return the authored name
 int getBufferSize()
          Gets the maximum number of elements set by the user to return in a fetch.
 java.lang.String getName()
          Returns the name of this instance, as it is stored in the workflow database.
 VWSession getServiceSession()
          Gets the session that contains the query object.
 void setBufferSize(int theNewSize)
          Sets the maximum number of elements to return in a fetch.
 VWLogQuery startQuery(java.lang.String indexName, java.lang.Object[] minValues, java.lang.Object[] maxValues, int queryFlags, java.lang.String filter, java.lang.Object[] substitutionVars)
          Fetches log items based on conditions specified in the parameters.
 java.lang.String toString()
          Gets the string version of the log name.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

QUERY_NO_OPTIONS

public static final int QUERY_NO_OPTIONS
Value of 0. This value is used as a possible value for the queryFlags parameter of the startQuery method. The value sets all query flag options to false. Returned work objects are unlocked, unbound, and writable.

See Also:
Constant Field Values

QUERY_MIN_VALUES_INCLUSIVE

public static final int QUERY_MIN_VALUES_INCLUSIVE
Integer value of 32. This value is used as a possible value for the queryFlags parameter of the startQuery method. The specified value enables using minimum acceptable values for a range of values. Minimum values are evaluated as greater than or equal to rather than the default greater than evaluation.

See Also:
Constant Field Values

QUERY_MAX_VALUES_INCLUSIVE

public static final int QUERY_MAX_VALUES_INCLUSIVE
Value of 64. This value is used as a possible value for the queryFlags parameter of the startQuery method. The specified value enables using maximum acceptable values for a range of values. Maximum values are evaluated as less than or equal to rather than the default less than evaluation.

See Also:
Constant Field Values

QUERY_RESOLVE_NAMES

public static final int QUERY_RESOLVE_NAMES
Value of 8192. Flag Indicates query is to parse the maxValues, minValues, filter and substitutionVars values for user name and class substitution of strings to IDs.

This supports conversion of user names to ids for Process Engine Web Services to perform queries using user ID fields within an index or filter (used when querying for rosters, queues and logs). Process Engine Web Services is stateless, so the conversion of name to ID within the index and filter values is done on the PE server.

See Also:
VWRoster.QUERY_RESOLVE_NAMES, VWQuery#QUERY_RESOLVE_NAMES, Constant Field Values

QUERY_GET_NO_TRANSLATED_SYSTEM_FIELDS

public static final int QUERY_GET_NO_TRANSLATED_SYSTEM_FIELDS
Value of 2048. Include this value in the queryFlags parameter of the createQuery() method to return objects without translated system fields.

Use for performance enhancement when methods on a retrieved object are not needed and only the returned data itself is needed.

System fields and translated system fields are used in the helper methods for each object. Note that VWWorkObject objects have system fields that are not present in VWStepElement objects. A VWStepElement object contains only parameter data if this flag is used. However, a VWWorkObject object will contain system fields even if this flag is used.

A method that requires translation returns a default value (null, 0, or false) for this flag. This is because related helper methods require the system fields and translated system fields to function properly.

See Also:
Constant Field Values
Method Detail

_get_FILE_DATE

public static java.lang.String _get_FILE_DATE()
For FileNet internal use only, do not call.

Returns:
the date

_get_FILE_AUTHOR

public static java.lang.String _get_FILE_AUTHOR()
For FileNet internal use only, do not call.

Returns:
the author

_get_FILE_REVISION

public static java.lang.String _get_FILE_REVISION()
For FileNet internal use only, do not call.

Returns:
the file revision

startQuery

public VWLogQuery startQuery(java.lang.String indexName,
                             java.lang.Object[] minValues,
                             java.lang.Object[] maxValues,
                             int queryFlags,
                             java.lang.String filter,
                             java.lang.Object[] substitutionVars)
                      throws VWException
Fetches log items based on conditions specified in the parameters. If a translation source exists, the authored name of the log is translated. The authored names must be specified for the query parameters.

The query bases log item retrieval on a filter condition and a range you specify in an index key with Composer. Use a logical AND to include minimum and maximum (minValue and maxValue) index key values, query options (queryFlags), and filters with substitution variables (substitutionVars). Returned log query items match all fetch criteria specified in the parameters.

Parameters:
indexName - The authored name of the database index key for the log element items, or a system search field name. Use either the name assigned to the index at the Configuration Console or a system search field name.

Note: An index assigned through the Configuration Console can be a user-defined or system-defined search field, or it can be both.

System indexes include:

      F_LogTime = F_TimeStamp + F_SeqNumber
      F_LogWobTag = F_WorkObjectTag + F_TimeStamp + F_SeqNumber
 

The standard system search fields are:

  • F_WobNum: work item number of type byte[].
    For MS SQL, use the syntax: 0x.
    For DB2, use the syntax: x''.
    For Oracle, use the syntax: ''
  • F_SortRule: predefined as F_Locked (type integer)
  • F_FiFo: defined to an internal value. Do not modify.
minValues - An array of minimum values used to compare index key fields.

The array elements type must match the type of the fields in the index key. If the number of minValues array elements is smaller than the number of index key fields, the system assumes the fields at the end of the index key have no value. The array elements must be of a Java type that corresponds to a Process Engine type (integer, float, boolean, or string). Strings must be the authored strings.

For example:

     myIndex = integerA + stringB + booleanC;
     Object[] minValues = {new Integer(1000), "aardvark", new Boolean(true)};
 
maxValues - An array of maximum values used to compare the index key fields.

The array elements type must match the type of the fields in the index key. If the number of maxValues array elements is smaller than the number of index key fields, the system assumes the fields at the end of the index key have no value. The array elements must be of a Java type that corresponds to a Process Engine type (integer, float, boolean, or string). Strings must be the authored strings.

queryFlags - Integer value flags that specify the query options.

Setting this parameter refines the query for the log records specified by the index. Use the | and + operators to combine the the flags. See the query properties for this instance and the QUERY_* properties on VWQuery for descriptions of the possible query flags.

filter - A SQL WHERE clause used as a filter, and having placeholder variables that are replaced by values in the substitutionVars parameter.

Use this parameter with the parameter settings for minValues, maxValues, and queryFlags to refine the search. The SQL WHERE clause should contain a search field name on the left side of a boolean operator and a placeholder variable on the right side of the operator.

The field names are processed as SQL column names. For this reason, it is important that you do no use SQL function names as field names.

For example:

   integerA < :A AND stringB =:B 

specifies that an object satisfies the filter if it meets the following conditions:

  1. The integer search field, integerA, must be less than the value of the placeholder variable A.
  2. The string search field, stringB, must be equal to the value of the next placeholder variable B.

Use the following guidelines when creating the filter:

  • In a SQL WHERE clause, a colon (:) precedes each placeholder variable on the right side of the statement.
  • The search field can be a variable, a system field, or a user-defined field (the authored string).
  • When the filter parameter is processed, each placeholder variable is replaced (in corresponding order) with a value specified in the substitutionVars parameter.

substitutionVars - An array of objects containing the values to substitute for the placeholder variables specified in the SQL WHERE clause for the filter parameter.

A VWWorkObjectNumber object can be used here in place of F_WobNum and F_WorkFlowNumber. Queries to DB2 databases must use VWWorkObjectNumber instead of F_WobNum or F_WorkFlowNumber.

If there is no placeholder variable in the filter parameter, the values for the substitutionVars parameter will be ignored (and can be null). The array elements in this parameter are substituted, in corresponding order, for the placeholder variables in the filter parameter.

Note: When using special SQL characters (such as, %), these characters need to be contained within the substitution string, and the entire substitution string must be quoted.

For example, if the filter parameter contains three placeholder variables specified as ":A", there must be three corresponding substitution variables.

For example:

   {new Integer(1000),"Smith"} 

This substitutionVars parameter would have a corresponding filter parameter of the following:

   integerA < 1000 AND stringB = "Smith" 

Note: Time columns in the database can be exposed as either 32-bit (can only support dates earlier than 2038) or 64-bit (can support dates beyond 2038). If a user has a filter on a 32-bit time field, the value bound to the bind variable in the query using that filter must be a value that can fit in 32-bits, otherwise the query will not return the expected result. For example:

    "my32bitColumn < :a"

will not work correctly if bound to the date value "11/11/2099"; however, binding it to the value "11/11/2037" will return the expected result.

As a further example, assume the log being queried contains a row with two exposed fields, atime64 (64-bit) and atime32 (32-bit), and both fields have the date/time value "11/11/2008 12:12:12".

Using the filter:

    String filter = "atime64 < :a AND atime32 < :b"; 

the following substitution variables will return the fetched row after applying the filter and substitutionVars in the query:

    Object[] subsVars = {sdf.parse("2040-01-01 12:00:00"), sdf.parse("2020-01-01 12:00:00")}; // works 

However, the following query will not be able to fetch the row, because it binds a value that will not fit in a 32-bit column:

    Object[] subsVars = {sdf.parse("2040-01-01 12:00:00"), sdf.parse("2040-01-01 12:00:00")}; // does not work. 
Returns:
A VWLogQuery instance from which the query fetches items.
Throws:
VWException - The method throws an exception if it cannot complete the process of fetching log items.

getServiceSession

public VWSession getServiceSession()
Gets the session that contains the query object.

Returns:
A VWSession object. The returned VWSession object is the object that instantiated the VWLog object.

toString

public java.lang.String toString()
Gets the string version of the log name.

Overrides:
toString in class java.lang.Object
Returns:
The localized log name.

getBufferSize

public int getBufferSize()
Gets the maximum number of elements set by the user to return in a fetch. The default value is 50.

Returns:
An integer value indicating the maximum number of elements to return in a fetch.
Since:
VWWS3.10

setBufferSize

public void setBufferSize(int theNewSize)
                   throws VWException
Sets the maximum number of elements to return in a fetch. The default number is 50.

Parameters:
theNewSize - An integer value that specifies the number of elements to return in a fetch. The value must be greater than 0 (zero).
Throws:
VWException - The method throws an exception if buffer size is less than or equal to 0 (zero).

fetchLogDefinition

public VWLogDefinition fetchLogDefinition()
                                   throws VWException
Fetches the log definition.

Returns:
A VWLogDefinition object.
Throws:
VWException - The method throws an exception if it cannot complete the process of fetching the log definition.

getName

public java.lang.String getName()
Returns the name of this instance, as it is stored in the workflow database. If a translation source exists, the authored name is translated.

Note: The translation is done only at runtime, so will not appear in design-time applications (such as the Process Designer or Configuration Console).

Returns:
A String containing the translated name, if a translation source exists; otherwise the authored name is returned.

getAuthoredName

public java.lang.String getAuthoredName()
Return the authored name

Returns:
the authored name
Since:
P8 4.0

Process API

© Copyright IBM Corporation 2002, 2008. All rights reserved.