Process Class Relationships

filenet.vw.api
Class VWRosterQuery

java.lang.Object
  |
  +--filenet.vw.api.VWQuery
        |
        +--filenet.vw.api.VWRosterQuery

public final class VWRosterQuery
extends filenet.vw.api.VWQuery

Use this class to query roster elements or work objects.

A given instance of this class returns a single type of item. A query completes when the next() method returns null values.

VWRosterQuery contains methods next() and hasNext() which function similarly to the next() and hasNext() methods in the Iterator interface in Java 2.

See Also:
VWRoster.startQuery(String, Object[], Object[], int, String, Object[]), VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int)

Field Summary
static int QUERY_GET_TRANSLATED_SYSTEM_FIELDS
          Deprecated. Not replaced. This is the default.
static int QUERY_LOCK_OBJECTS
          Value of 16. Flag used to specify that items returned from a query should become locked.
static int QUERY_MAX_VALUES_INCLUSIVE
          Value of 64. Flag used to specify that maximum values passed in a query are inclusive, i.e.
static int QUERY_MIN_VALUES_INCLUSIVE
          Value of 32. Flag used to specify that minimum values passed in a query are inclusive, i.e.
static int QUERY_READ_BOUND
          Value of 2. Flag used to specify that items returned from a query should include those that are already bound to a user or machine.
static int QUERY_READ_LOCKED
          Value of 1. Flag used to specify that items returned from a query should include those that are already locked.
static int QUERY_READ_UNWRITABLE
          Value of 4. Flag used to specify that items returned from a query should include those that are Read-only.
 
Method Summary
 int fetchCount()
          Returns the number of records that can be retrieved for the current VWRosterQuery object.
 VWRosterElement[] fetchRosterElements(int bufferSize)
          Fetches a specified number of roster elements.
 VWWorkObject[] fetchWorkObjects(int bufferSize)
          Deprecated. Replaced by next()
 int getElementType()
          Gets the fetch type for the VWRosterQuery object.
 VWRoster getRoster()
          Gets a roster that was retrieved by the query initiated by either the VWRoster.createQuery() or VWRoster#startQuery(String, Object[], Object[], int, String, Object[]) methods.
 boolean hasNext()
          Indicates whether another element can be fetched from this VWRosterQuery instance.
 boolean isDone()
          Deprecated. Replaced by next().
 java.lang.Object next()
          Retrieves the subsequent element for this VWRosterQuery instance. Invoke this method repeatedly to retrieve a series of objects that can be cast to the fetch type of this VWRosterQuery object, as specified by the VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call that created this VWRosterQuery instance.
 void resetFetch()
          Resets the last element fetched for this RosterQuery object.
 java.lang.String toString()
          Gets the name of the roster retrieved in a query.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

QUERY_READ_LOCKED

public static final int QUERY_READ_LOCKED
Value of 1. Flag used to specify that items returned from a query should include those that are already locked.
See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_READ_BOUND

public static final int QUERY_READ_BOUND
Value of 2. Flag used to specify that items returned from a query should include those that are already bound to a user or machine.
See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_READ_UNWRITABLE

public static final int QUERY_READ_UNWRITABLE
Value of 4. Flag used to specify that items returned from a query should include those that are Read-only.
See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_LOCK_OBJECTS

public static final int QUERY_LOCK_OBJECTS
Value of 16. Flag used to specify that items returned from a query should become locked. See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_MIN_VALUES_INCLUSIVE

public static final int QUERY_MIN_VALUES_INCLUSIVE
Value of 32. Flag used to specify that minimum values passed in a query are inclusive, i.e. the comparison should be "greater than or equal to" rather than "greater than" (which is the default).
See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_MAX_VALUES_INCLUSIVE

public static final int QUERY_MAX_VALUES_INCLUSIVE
Value of 64. Flag used to specify that maximum values passed in a query are inclusive, i.e. the comparison should be "less than or equal to" rather than "less than" (which is the default).
See the queryFlags parameter of VWRoster.startQuery(..), VWQueue.createQuery(..), and VWQueue.startQuery(..)(deprecated)

QUERY_GET_TRANSLATED_SYSTEM_FIELDS

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

Value of 512. Flag to specify that the query items returned from the query should include translated system field values.
Method Detail

fetchRosterElements

public VWRosterElement[] fetchRosterElements(int bufferSize)
                                      throws VWException
Fetches a specified number of roster elements. Call the method repeatedly to retrieve the needed number of roster elements for the query. If the number of requested elements (specified in the bufferSize parameter) is greater than the number of elements returned in the query, the remaining elements are returned in a single fetch.

An instance of this class can only return a single item type. Therefore, an error occurs if the next() method has previously been called.

Parameters:
bufferSize - A positive integer value specifying the maximum number of elements to return in a fetch operation. The final number of returned elements will be the lesser of this value, the Process Server's size limit, and the total number of roster elements remaining to be fetched.
Returns:
An array of VWRosterElement objects that represents the fetched items. If no more elements can be fetched, the method returns null.
Throws:
VWException - Various causes. A possible cause may be the creation of the current VWRosterQuery object by the VWRoster.createQuery method. Use next() with VWRosterQuery objects that were created with VWRoster.createQuery method.

fetchWorkObjects

public VWWorkObject[] fetchWorkObjects(int bufferSize)
                                throws VWException
Deprecated. Replaced by next()

Fetches a specified number of work objects. Call this method repeatedly to retrieve the needed number of work objects for the query. If the number of requested elements (specified in the bufferSize parameter) is greater than the number of elements returned in the query, all remaining elements are returned in a single fetch.

An instance of this class can return only one type of item. Therefore, an error occurs if the next or fetchRosterElements method has previously been called.

Parameters:
bufferSize - An integer value specifying the maximum number of elements to return in a fetch operation. Specify a value greater than 0 (zero). The server imposes a maximum limit; therefore, the number of returned elements might be smaller than the number specified in this parameter - if the number of work objects is large enough.
Returns:
An array of VWWorkObject objects that represent the fetched items. If no more elements can be fetched, the method returns null.
Throws:
VWException - Thrown if it cannot fetch a specified number of work objects.

getRoster

public VWRoster getRoster()
Gets a roster that was retrieved by the query initiated by either the VWRoster.createQuery() or VWRoster#startQuery(String, Object[], Object[], int, String, Object[]) methods.
Returns:
A VWRoster object that represents the query result for either the VWRoster.createQuery() or VWRoster#startQuery(String, Object[], Object[], int, String, Object[]) methods.
See Also:
VWRoster

isDone

public boolean isDone()
               throws VWException
Deprecated. Replaced by next().

Determines whether the query is complete.
Returns:
true if all available elements have been fetched, indicating the query has completed; false, otherwise.
Throws:
VWException - The method throws an exception if the current VWRosterQuery instance was created with a call to VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int). For VWRosterQuery instances created with VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int), use the hasNext() method to determine the query's completion status.

toString

public java.lang.String toString()
Gets the name of the roster retrieved in a query.
Overrides:
toString in class java.lang.Object
Returns:
The name of the roster retrieved as a result of a query.

getElementType

public int getElementType()
Gets the fetch type for the VWRosterQuery object.
Returns:
An integer value associated with the element type to be retrieved.

Valid fetch type values are as follows:

  • 1: work object (VWFetchType.FETCH_TYPE_WORKOBJECT)
  • 4: Roster element (VWFetchType.FETCH_TYPE_ROSTER_ELEMENT)
  • -1: None (VWFetchType.FETCH_TYPE_NONE); this value is returned only if the deprecated method VWRoster.startQuery was used to create this object.

See Also:
VWFetchType.FETCH_TYPE_WORKOBJECT, VWFetchType.FETCH_TYPE_ROSTER_ELEMENT

next

public java.lang.Object next()
                      throws VWException
Retrieves the subsequent element for this VWRosterQuery instance. Invoke this method repeatedly to retrieve a series of objects that can be cast to the fetch type of this VWRosterQuery object, as specified by the VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call that created this VWRosterQuery instance. Returns null when no more objects can be returned.

To use this method, create a VWRosterQuery object with a VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call, which specifies a range of objects to be fetched, a SQL filter expression, and the type of object to be fetched. The resulting query object will use a default buffer size of 50 retrieved items.

After a set of items in the current retrieval buffer is exhausted, additional items will be retrieved from the Process server and buffered. The effective buffer block size is the lesser of the number specified with a preceding VWRoster.setBufferSize(int) call and the number imposed by the Process server limit.

You can modify retrieval performance by changing the retrieval buffer size. To change the current retrieval buffer size, set it with a VWRoster.setBufferSize(int) call from the same instance of the VWRoster class that created the current VWRosterQuery object. In other words, after you reset the buffer size, you must create a new VWRosterQuery object (which will contain this next() method) with VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int). In the new instance of VWRosterQuery, the next() method will use the new buffer size.
Note
This method requires a buffer size greater than 1 to operate properly.

Returns:
An object that represents an item of the fetch type specified in the VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) method that created the current VWRosterQuery object, or null (indicating there are no more objects in the series).
Note
The returned object should be cast to the fetch type specified by the creating VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call.
Throws:
VWException - Various causes. A possible cause may be using the deprecated VWRoster.startQuery(String, Object[], Object[], int, String, Object[]) method to create the current VWRosterQuery instance, instead of a VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call.
See Also:
hasNext()

resetFetch

public void resetFetch()
Resets the last element fetched for this RosterQuery object. Previously fetched elements will be included in the new fetch results.
Since:
VWWS3.10

hasNext

public boolean hasNext()
                throws VWException
Indicates whether another element can be fetched from this VWRosterQuery instance.
Note
This method requires a buffer size greater than 1 to operate properly. The default buffersize is 50.
Returns:
true if there are more elements that can be fetched.
Throws:
VWException - Various causes. A possible cause may be using the deprecated VWRoster.startQuery(String, Object[], Object[], int, String, Object[]) method to create the current VWRosterQuery instance, instead of a VWRoster.createQuery(String, Object[], Object[], int, String, Object[], int) call.
See Also:
next()

fetchCount

public int fetchCount()
               throws VWException
Returns the number of records that can be retrieved for the current VWRosterQuery object.
Returns:
The number of records that could be retrieved in the roster for the current VWRosterQuery object.
Note
The record set may change before the query returns, so the result should be treated as approximate.
Throws:
VWException - Various causes. A possible cause may be an unsupported fetch type.
Since:
VWWS3.10


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