QueryIterator

The QueryIterator activity is used to retrieve one or more tuples at a time. This activity is usually used in a TIBCO BusinessWorks group.

General

In the General tab, you can specify the activity name and a space connection, and control the number of tuples to be retrieved in each iterator.

The following table describes the fields in the General tab of the QueryIterator activity:

Field Module Property? Description
Name No Specifies the name to be displayed as the label for the activity in the process.
Space Connection Yes Click the icon to select a space connection that defines how the application joins the space.

Tuples are retrieved in the space with the defined distribution role of the selected space connection.

If no matching space connections are found, click Create Shared Resource to create one. See Creating a Metaspace Connection for details.

Control Subsets No Select this check box to control the number of tuples to be retrieved in each iterator.

If this check box is not selected, this activity retrieves one tuple at a time.

Timeout(milliseconds) Yes Specifies the amount of time in milliseconds that you have to wait before the QueryIterator activity returns interator results.
Note: The default value is 60000 milliseconds. If the value is -1 or smaller than -1, it indicates waiting indefinitely.

If the field is blank, the value of the field is -1. If the value is 0, an error message is displayed.

Description

In the Description tab, you can enter a short description for the QueryIterator activity.

Advanced

In the Advanced tab, you can specify the advanced configurations, such as entries retrieval and the number of tuples returned from an iterative query operation.

The following is the Advanced tab of the QueryIterator activity:

Field Module Property? Description
DistributionScope Yes Select a distribution scope to narrow down the set of entries being browsed:
  • ALL: retrieves all the entries in the space. By default, this option is selected.
  • SEEDED: retrieves only the entries actually distributed to the member when this activity is invoked.
BrowserType No Select one browser type from the following options:
  • GET: retrieves and removes one entry each time. By default, this option is selected.
  • TAKE: retrieves and removes one entry each time.
  • LOCK: retrieves and locks one entry each time.
Note: Only the GET option is displayed when you select CURRENT from the TimeScope list.
TimeScope No Select a time scope to narrow down the period of time of interest:
  • SNAPSHOT: the browser starts with all the tuples in the space when the browser is created, instead of being updated with new tuples that are put into the space.
  • CURRENT: client applications create queries that return large result sets by using less resources. By default, this option is selected.
Prefetch Yes Specifies the number of records that are prefetched for each seeder in parallel with the processing of the result tuples.

The default value is 1000. The special value of -1 indicates that the entire result set is pushed to the client at once.

QueryLimit Yes Specifies the number of tuples returned from an iterative query operation.

The default value is -2, which indicates that the value specified in the Query Limit field in the Advanced tab of the Space shared resource is used.

The value of -1 indicates that all the matched tuples are retrieved.

Note: This field is displayed only when you select SNAPSHOT from the TimeScope list.

Input

The following table describes the fields in the Input tab of the QueryIterator activity:

Input Item Data Type Description
Filter String Specifies a filter string.

A filtered query iterator only returns one entry that matches the specified filter at each time.

The way filters work in the plug-in is similar to the way message selectors work in JMS.

A filter can be reset when working in a group. Once it is reset, the filter evaluates tuples based on the new filter string.

Note: Ensure that the filter syntax is correct according to the TIBCO ActiveSpaces documentation. If an invalid filter is given, no results are reported.

See TIBCO ActiveSpaces Developers Guide for detailed information on how to use filters.

QueryLimit Integer Specifies the number of tuples returned from an iterative query operation.

The value is of -2 indicates that the value specified in the Query Limit field in the Advanced tab of the Space shared resource is used.

The value of -1 indicates that all the matched tuples are retrieved.

This field is displayed only when you select SNAPSHOT from the TimeScope list in the Advanced tab.

Count Integer Specifies the number of tuples to be retrieved in each iterator.

This field is displayed only when you select the Control Subsets check box in the General tab.

Output

In the Output tab, you can find the operation results.

The following table describes the fields in the Output tab of the QueryIterator activity:

Output Item Data Type Description
Tuple String Indicates the matched tuple in the associated space.
IsLast Boolean Indicates whether the current tuple is the last tuple.
  • The value of true indicates that the current tuple is the last tuple
  • The value of false indicates that the current tuple is not the last tuple.
The following fields are displayed when you select SNAPSHOT from the TimeScope list in the Advanced tab:
IsPartialResult Boolean Indicates whether the returned tuples are partial.
  • The value of true indicates that the returned tuples are partial.
  • The value of false indicates that the returned tuples are not partial.
TotalCount Long Indicates the number of returned tuples.
RemainingCount Long Indicates the number of remaining tuples.

Fault

In the Fault tab, you can find the error code and error message of the Query Iterator activity. See Error Codes for more detailed explanation of the errors.

The following table describes the errors in the Fault tab of the QueryIterator activity:

Error Schema Element Datatype Description
msg String The TIBCO ActiveMatrix BusinessWorks Plug-in for ActiveSpaces error message.
msgCode String The TIBCO ActiveMatrix BusinessWorks Plug-in for ActiveSpaces error code.
ASStatus String The status code returned by TIBCO ActiveSpaces functions.

See TIBCO ActiveSpaces Java API Reference for more information.