Process Class Relationships

filenet.vw.api
Class VWRoster

java.lang.Object
  |
  +--filenet.vw.api.VWPersistentCollection
        |
        +--filenet.vw.api.VWRoster

public final class VWRoster
extends filenet.vw.api.VWPersistentCollection

Use this class to access the contents of a roster or manage running workflows. Create an instance of this class with VWSession.getRoster(). Create a query object for an instance of this class with VWRoster.createQuery.

See Also:
VWNewWorkObject, VWSession

Field Summary
static int QUERY_GET_NO_SYSTEM_FIELDS
          Value of 1024. Include this value in the queryFlags parameter of the createQuery() method to return objects without system fields.
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 fields.
static int QUERY_GET_SYSTEM_FIELDS
          Deprecated. Not replaced. This is the default.
static int QUERY_GET_TRANSLATED_SYSTEM_FIELDS
          Deprecated. Not replaced. This is the default.
static int QUERY_MAX_VALUES_INCLUSIVE
          Value of 64. Pass this value in the queryFlags parameter of the createQuery method to specify the inclusion of maximum search values.
static int QUERY_MIN_VALUES_INCLUSIVE
          Value of 32. Pass this value in the queryFlags parameter of the createQuery method to specify the inclusion of minimum search values.
static int QUERY_NO_OPTIONS
          Value of 0. Pass this value in the queryFlags parameter of the createQuery method to specify no search option.
static int QUERY_READ_UNWRITABLE
          Value of 4. Pass this value in the queryFlags parameter of the createQuery method to specify the return of Read-only work items.
 
Method Summary
 VWRosterQuery createQuery(java.lang.String indexName, java.lang.Object[] minValues, java.lang.Object[] maxValues, int queryFlags, java.lang.String filter, java.lang.Object[] substitutionVars, int fetchType)
          Performs a filtered fetch of roster items. The filters specify search conditions flexibly and include setting a range for the search index.
 VWNewWorkObject createWorkObject()
          Deprecated. Replaced by VWSession.createNewWorkObject(String)
 int fetchCount()
          Gets an integer that indicates the number of work items in the roster.
 VWRosterDefinition fetchRosterDefinition()
          Fetches the definition for this roster.
 VWRosterStats fetchStatistics(java.util.Date startTime, java.util.Date endTime, int timeUnits)
          Fetches statistical information for the roster, given a start and stop time.
 int getBufferSize()
          Gets an integer value indicating the maximum number of elements to return in a fetch. The default number is 50.
 int getCount()
          Deprecated. Replaced by fetchCount()
 VWInjectSessionInfo getInjectSessionInfo(java.lang.String sessionName, boolean nextName)
          Deprecated. Replaced by VWSession.createLiveWorkObject(String[], Object[], String, int) and VWCreateLiveWOResult.
 VWSession getServiceSession()
          Identifies the session that originated the search object.
 void setBufferSize(int newSize)
          Sets the integer value for the maximum number of elements to return in a fetch. The default value is 50.
 VWRosterQuery startQuery(java.lang.String indexName, java.lang.Object[] minValues, java.lang.Object[] maxValues, int queryFlags, java.lang.String filter, java.lang.Object[] substitutionVars)
          Deprecated. Replaced by createQuery(String, Object[], Object[], int, String, Object[], int)
 java.lang.String toString()
          Gets the roster 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. Pass this value in the queryFlags parameter of the createQuery method to specify no search option.

After passing this value, the returned work items are unlocked, unbound, and writable. If you use this flag in conjunction with another flag, the value of the other flag becomes the value input to the parameter [for example, 0(this value) + n(another flag value) = n(the other flag value)].


QUERY_READ_UNWRITABLE

public static final int QUERY_READ_UNWRITABLE
Value of 4. Pass this value in the queryFlags parameter of the createQuery method to specify the return of Read-only work items.

Setting this flag causes the application to read unwritable work items; not setting it causes the return of only writable work items.


QUERY_MIN_VALUES_INCLUSIVE

public static final int QUERY_MIN_VALUES_INCLUSIVE
Value of 32. Pass this value in the queryFlags parameter of the createQuery method to specify the inclusion of minimum search values. Minimum search values can be applied as "greater than" by default, or they can be applied as "greater than or equal to" by using this flag value.

QUERY_MAX_VALUES_INCLUSIVE

public static final int QUERY_MAX_VALUES_INCLUSIVE
Value of 64. Pass this value in the queryFlags parameter of the createQuery method to specify the inclusion of maximum search values. Maximum search values can be applied as "less than" by default, or they can be applied as "less than or equal to" by using this flag value.

QUERY_GET_SYSTEM_FIELDS

public static final int QUERY_GET_SYSTEM_FIELDS
Deprecated. Not replaced. This is the default.

Value of 256. Pass this value in the queryFlags parameter of the createQuery method to specify the return of system field names and values.

Use the system fields for additional queries on objects. A method that requires translation returns a default value (null, 0, or false). Helper methods require the QUERY_GET_TRANSLATED_SYSTEM_FIELDS to function properly.


QUERY_GET_TRANSLATED_SYSTEM_FIELDS

public static final int QUERY_GET_TRANSLATED_SYSTEM_FIELDS
Deprecated. Not replaced. This is the default.

Value of 512. Pass this value in the queryFlags parameter of the createQuery method to specify the return of system field names and translated system field values. Use these fields in the helper methods for each element.

QUERY_GET_NO_SYSTEM_FIELDS

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

System fields and translated system fields are used in the helper methods for each element. System fields and translated system field data will not be returned on the objects queried. 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 fields to function properly.


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 fields. Use for performance enhancement when methods on retrieved object are not needed and only the returned data itself is needed.

Translated system fields are used in the helper methods for each element. System fields and translated system field data will not be returned on the objects queried. 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 fields to function properly.

Method Detail

createWorkObject

public VWNewWorkObject createWorkObject()
                                 throws VWException
Deprecated. Replaced by VWSession.createNewWorkObject(String)

Creates a work item with specified field values and saves it to a workflow roster. This method assumes that the workflow roster name and the work class name are identical.
Throws:
VWException - Thrown if the method cannot create the specified work item and save it to a workflow roster.

getCount

public int getCount()
             throws VWException
Deprecated. Replaced by fetchCount()

Gets an integer value that indicates the size of the roster.
Returns:
An integer value indicating the number of work items in the roster.
Throws:
VWException - Thrown if the roster size cannot be determined.

fetchCount

public int fetchCount()
               throws VWException
Gets an integer that indicates the number of work items in the roster.
Returns:
An integer value indicating the number of work items in the roster.
Throws:
VWException - Thrown if the roster size cannot be determined.
Since:
VWWS3.10

startQuery

public VWRosterQuery 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
Deprecated. Replaced by createQuery(String, Object[], Object[], int, String, Object[], int)

Fetches roster items.

Specifying search conditions in this method causes the retrieval of roster items based on a filter condition and a range in a search index. Use the following to limit your search:

A roster item must match all fetch criteria specified in the parameters to return.

Parameters:
indexName - The name of the database search index for the roster. Specify either the name assigned to the index at the Configuration Console (this may be a user-defined search field, a system search field, or both) or a system search field name.

The standard system search fields for rosters are listed below:

  • F_WobNum: work item number of type byte[]. For an MS SQL server, pass the hex version of the field value; for example, if F_WobNum were C4BCB36717A2D3119E0F00C04F8C7570, pass 0xC4BCB36717A2D3119E0F00C04F8C7570.
  • F_WobTag: Predefined as F_Tag(of type string)

minValues - An array of objects containing the minimum values with which to compare the index fields.

The type of the array elements must correspond to the field types in the search index. If the number of minValues array elements is smaller than the number of search fields, the application assumes the fields at the end of the search index have no value. The array element must be of a Java type that corresponds to a Process type (integer, float, boolean, or string). For example, java.lang.Integer corresponds to integer.

For example, the index named 'myIndex' is an integer, followed by a string, followed by a boolean, followed by a float, followed by a time-type value:

     myIndex = integerA + stringB + booleanC + floatD + timeE
     

Set sample minimum values, against which to compare the index, as follows:

     Object[] minValues = {new Integer(1000), "aardvark",
    new Boolean(true), new Float(0012345678.369), new Time([date&time value])}
maxValues - An array of maximum values with which to compare the index fields.

The type of the array elements must correspond to the field types in the search index. If the number of maxValues array elements is smaller than the number of search fields, the application assumes that the fields at the end of the search index have no value. The array element must be of a Java type that corresponds to a Process type (integer, float, boolean, or string). For example, java.lang.Integer corresponds to integer.

queryFlags - An integer value that specifies the search options Setting this parameter refines the search for the work items specified by the search index. Use | and + operators to combine the options. See the Field Detail section for description of these query flags:

  • 0: No query (QUERY_NO_OPTIONS)
  • 4: Read-only (QUERY_READ_UNWRITABLE)
  • 32: Include minValues value (QUERY_MIN_VALUE_INCLUSIVE)
  • 64: Include maxValues value (QUERY_MAX_VALUE_INCLUSIVE)

filter - A string containing a SQL statement used to specify filter conditions (used with values input to the substitutionVars parameter).

Use this parameter with the parameter settings for minValues, maxValues, and queryFlags to refine the your search. Input a SQL where-clause that contains a search field name on the left side of a boolean operator and a substitution placeholder on the right side of the operator.

For example: if filter input is similar to the following SQL statements:

    integerA < :A AND stringB =:A

This filter will make the object pass the filter only if it meets two conditions:

  • The integer, integerA, must be less than the value of the placeholder, A.
  • The string, stringB, must be equal to the value of the placeholder, A.

In the SQL statement, a colon (:) precedes each placeholder on the right side of the statement.

A search field must be a variable or a roster field, for example: F_Tag=:name. Using this filter requires that you substitute the placeholder to the right of each colon with a value you pass to the corresponding substitutionVars parameter.

substitutionVars - An array of objects that contain the values to substitute for the variable names to the right of the colons in the SQL statement you passed to the filter parameter.

A substitution variable must begin with colon. If there is no variable in the filter parameter, the values for this parameter can be null. The array elements in this parameter substitute for the corresponding array elements in the filter parameter array. The filter parameter array elements act as place holders and must be substituted. For example, if three names are :A, a user needs three distinct substitution variables.

For example, if you pass the following:

    {new Integer(1000),"Smith"}

to the substitutionVars parameter to accompany the example for filter input, the object has to meet the following conditions to return:

    integerA < 1000 AND stringB = "Smith"

Returns:
A VWRosterQuery object for the queue being from which items are fetched.
Throws:
VWException - Thrown if the method cannot fetch roster items.

createQuery

public VWRosterQuery createQuery(java.lang.String indexName,
                                 java.lang.Object[] minValues,
                                 java.lang.Object[] maxValues,
                                 int queryFlags,
                                 java.lang.String filter,
                                 java.lang.Object[] substitutionVars,
                                 int fetchType)
                          throws VWException
Performs a filtered fetch of roster items. The filters specify search conditions flexibly and include setting a range for the search index.

This method employs the following kinds of condition descriptors to define the filters:

For this method to successfully return a given roster item, the roster item must pass all the fetch criteria specified by the input parameters.

Parameters:
indexName - The name of the database search index for the queue. Enter 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- or system- defined search field, or it can be both.

The standard system search fields for queues are listed below:

  • F_WobNum: work item number of type byte[]. For MS SQL pass the hexadecimal version of the field value; for example, if F_WobNum were C4BCB36717A2D3119E0F00C04F8C7570, pass 0xC4BCB36717A2D3119E0F00C04F8C7570.
  • F_WobTag: Predefined as F_Tag (type string)

minValues - An array of objects containing the minimum values with which to compare the index fields.

Array element data types must match the corresponding data types in the search index. If the number of minValues array elements is smaller than the number of search fields, the unmatched search fields are ignored. The array element types must be Java data types that correspond to Process Operation Parameter types.

Example the index named 'myIndex' is an integer, followed by a string, followed by a boolean, followed by a float, followed by a time-type value:

     myIndex = integerA + stringB + booleanC + floatD + timeE
     

Set minimum values for comparison to the index as shown in the following sample code snippet:

     Object[] minValues = {new Integer(1000), "aardvark",
    new Boolean(true), new Float(0012345678.369), new Time( [date/time value] )}
maxValues - An array of objects containing the maximum values with which to compare the index fields.

Array element data types must match the corresponding data types in the search index. If the number of maxValues array elements is smaller than the number of search fields, the unmatched search fields are ignored. The array element types must be Java data types that correspond to Process Operation Parameter types.

queryFlags - An integer value that specifies the search options

Setting this parameter refines the search for the work items specified by the search index. Use | and + operators to combine these options, which are described below:

  • 0: No query (QUERY_NO_OPTIONS)
  • 4: Read-only (QUERY_READ_UNWRITABLE)
  • 32: Include minValues value (QUERY_MIN_VALUE_INCLUSIVE)
  • 64: Include maxValues value (QUERY_MAX_VALUE_INCLUSIVE)

filter - A SQL WHERE clause that specifies a filter condition that is defined with values input to 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 substitution placeholder on the right side of the operator.

Example:
Consider the following SQL WHERE clause:

    integerA < :A AND stringB =:B

This filter specifies that the object passes the filter if it meets two conditions:

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

The following usage tips summarize the use of this parameter:

  • In a SQL statement, a colon (:) precedes each placeholder variable on the right side of the statement.
  • The search field is a variable or a system- or user-defined field.
  • The operation of the filter causes substitution of the placeholder named to the right of each colon with a value you specify in corresponding order. There ordered values are in the substitutionVars parameter.

substitutionVars - An array of objects that contain the values to substitute for the variable names to the right of the colons in the SQL statement you passed to the filter parameter.

In accordance with SQL expression rules, a substitution variable begins with a colon, and the name itself immediately follows the colon. If there is no such substitution variable in the filter parameter, the values for the substitutionVars parameter will be ignored and can be null. The array elements in this parameter substitute for the corresponding substitution variable elements in the filter parameter array.

The filter parameter array elements contain ordered values that are substituted in order into the corresponding SQL substitution variables, which act as ordered placeholders. For example, if three names are :A (the same), a user needs three distinct substitution variables, and the values are assigned according to the ordered correspondences between the values of the substitutionVars parameter and the occurence of SQL substitution variables in the filter parameter expression.

Example:
Suppose a substitutionVars parameter is specifed the follows:

    {new Integer(1000),"Smith"}

If this substitutionVars parameter accompanies the above example for the filter parameter input, the object has to meet the following conditions to pass the filter:

    integerA < 1000 AND stringB = "Smith"

The line above is the result of the ordered substitution of substitutionVars values into the SQL filter expression found in the filter parameter.

fetchType - An integer value associated with the element type to be retrieved using the object returned by VWRosterQuery. Valid element type values must be one of the following:

  • 1: Work object (FETCH_TYPE_WORKOBJECT)
  • 4: Roster element (FETCH_TYPE_ROSTER_ELEMENT)

Returns:
A VWRosterQuery instance from which items are fetched by iteration with the VWRosterQuery.next() method in a manner similar to use of to the next() method of the Iterator interface in Java 2.
Throws:
VWException -  
Since:
VWWS3.10
See Also:
VWFetchType

getServiceSession

public VWSession getServiceSession()
Identifies the session that originated the search object.
Overrides:
getServiceSession in class filenet.vw.api.VWPersistentCollection
Returns:
The VWSession object that created this VWRoster object.

getInjectSessionInfo

public VWInjectSessionInfo getInjectSessionInfo(java.lang.String sessionName,
                                                boolean nextName)
                                         throws VWException
Deprecated. Replaced by VWSession.createLiveWorkObject(String[], Object[], String, int) and VWCreateLiveWOResult.

Gets information about an inject session.
Parameters:
sessionName - The user-assigned name of the inject session, which was passed in the sessionName parameter of the VWNewWorkObject.saveMany() method.

nextName - true to retrieve information about the next session after the session defined in the sessionName parameter; false to get information for this session only.

Keep the following guidelines in mind:

  • If the sessionName parameter value is set to null and the value of this parameter is set to true, information about the first session returns.
  • If the sessionName parameter value is set to an invalid session name and the value of this parameter is set to true, information about this session returns since the name of this session is logically greater than the name of the bad session.

Returns:
A VWINjectSessionInfo object that contains inject session information. If the method cannot find the appropriate session, the method returns null.
Throws:
VWException - Thrown if the method cannot get information about an inject session.
See Also:
VWCreateLiveWOResult, VWNewWorkObject, VWSession.createLiveWorkObject(String[], Object[], String, int)

fetchStatistics

public VWRosterStats fetchStatistics(java.util.Date startTime,
                                     java.util.Date endTime,
                                     int timeUnits)
                              throws VWException
Fetches statistical information for the roster, given a start and stop time.
Parameters:
startTime - A date value indicating the time to start gathering statistics.
endTime - A date value indicating the time to stop gathering statistics.
timeUnits - An integer value indicating the unit of time for gathering statistics. Valid integer values for associated with the time units are as follows:

  • 1: Minute
  • 2: Hour
  • 3: Day
  • 4: Week
  • 5: Month
  • 6: Year

Returns:
A VWRosterStats object containing roster statistics information.
Throws:
VWException - Thrown if the method cannot fetch statistical information for the roster.
Since:
VWWS3.10
See Also:
VWTimeUnitType.MINUTES, VWTimeUnitType.HOURS, VWTimeUnitType.DAYS, VWTimeUnitType.WEEKS, VWTimeUnitType.MONTHS, VWTimeUnitType.YEARS

toString

public java.lang.String toString()
Gets the roster name.
Overrides:
toString in class java.lang.Object
Returns:
The localized roster name.

getBufferSize

public int getBufferSize()
Gets an integer value indicating the maximum number of elements to return in a fetch. The default number is 50.
Returns:
An integer value indicating the maximum number of elements to return in a fetch operation.
Since:
VWWS3.10

setBufferSize

public void setBufferSize(int newSize)
                   throws VWException
Sets the integer value for the maximum number of elements to return in a fetch. The default value is 50.
Parameters:
newSize - An integer value specifying the maximum number of elements to return in a fetch. The value must be greater than 0.
Throws:
VWException - Thrown if the buffer size specified in the newSize parameter is less than or equal to 0.
Since:
VWWS3.10

fetchRosterDefinition

public VWRosterDefinition fetchRosterDefinition()
                                         throws VWException
Fetches the definition for this roster. The roster definition contains search fields, search indexes, security information, and the server location of the roster.
Returns:
A VWRosterDefinition object that contains information about the roster.
Throws:
VWException - Thrown if the method cannot fetch the definition for this roster.
Since:
VWWS3.10


Copyright © 2002, 2003 FileNet Corporation. All rights reserved.