Comparison of the programming interfaces for retrieving process and task data

IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Developing client applications for BPEL processes and tasks > Queries on BPEL process and task data
Comparison of the programming interfaces for retrieving process and task data

Business Process Choreographer provides a query table API and a query API for retrieving process and task data. Each of these interfaces has different characteristics.
The query interface that you choose depends on several factors, including the functionality that your client application must provide, whether you have an existing end-user client infrastructure, and performance considerations. To help you decide which interface to use, the following table compares the characteristics of the query table and the query programming interfaces.

Characteristic query table API query API
Availability The query table API is available for the Business Flow Manager EJB, web services, and the REST programming interfaces. The query API is available for EJB, web services, JMS, and REST programming interfaces.
Methods for content retrieval The API provides the following methods:

queryEntities
queryEntityCount
queryRows
queryRowCount

The API provides the following methods:

query
queryAll
queryProcessTemplates
queryTaskTemplates

Methods for meta data retrieval The API provides the following methods:

getQueryTableMetaData
findQueryTableMetaData

The API provides the following methods:

QueryResultSet.getColumnType

Query table name Specifies the query table on which the query table API is run. Only one query table can be queried at any one time.

For example, queryEntities("CUST.TASKS", ...).
The SELECT clause specifies the columns and predefined database views on which the query runs. This specification is similar to an SQL select clause.

For example, query("TASK.TKIID, TASK.STATE, WORK_ITEM.REASON", ...).
SELECT clause and selected attributes Use the filter options of the query table API to specify the attributes that the query is to return. Because the query is run against one query table, the attributes are uniquely identifiable by their names. Use the SELECT clause to specify attributes. The syntax of the attribute name is: view_name. attribute_name.
For example, to search for task states, specify TASK.STATE in your query.
WHERE clause and filters Use the queryCondition property on the query table API to further filter the result of queries. Query tables provide pre-filtered content if primary query table filters, authorization filters, or query table filters have been specified on the query table definition. Use the WHERE clause to filter the result of the query.
WHERE clause and selection criteria The WHERE clause of the query API is not needed in this form on the query table API. Use the queryCondition property on the query table API for additional filtering.
Selection criteria in the query table definition select a particular property of the attached query table. This is achieved in addition to the filtering by the WHERE clause on the query API.
Selection criteria are not available for the query API. However, selection criteria are similar to the part of the WHERE clause that defines, for example, the name or locale of QUERY_PROPERTY, or TASK_CPROP, or TASK_DESC.

For example, a WHERE clause of QUERY_PROPERTY.NAME='xyz' is the same as specifying NAME='xyz' as a selection criterion on the query table definition for the QUERY_PROPERTY attached query table.
Work items and authorization Use the WORK_ITEM query table to access work items. You can customize the use of work items on the query table definition when the query table is developed and on the query table API, using the AuthorizationOptions object or the AdminAuthorizationOptions object.

For example, to exclude everybody work items when querying the TASK query table, specify a queryCondition property WI.EVERYBODY=0 or specify setUseEverbody(Boolean.FALSE) on the AuthorizationOptions property.
Use the WORK_ITEM view to access work items. All four types of work items are considered for the query result: everybody, individual, groups, and inherited work items. To filter the work items for a specific type of work item, customize the WHERE clause.

For example, to exclude the everybody work items, specify WORK_ITEM.EVERYBODY=0, in the WHERE clause.
Parameters You can use parameters in filters and selection criteria for composite query tables. Parameters are not available for the query API unless stored queries are used.
Stored queries and query tables The difference between a stored query and a query table is that stored queries are defined for one particular query, while a query table is defined for a particular set of queries.
For example, the query table definition does not allow the specification of an order-by clause because this information is typically available only when the query is run.
You can use stored queries to run query that contains a predefined set of options.
Materialized views Materialized views are not available for the query table API. Materialized views use database technologies to provide performance improvements for queries.
Custom tables Supplemental query tables offer the same functionality as custom tables. Custom tables are used to include data in queries that is external to the Business Process Choreographer database schema.
queryAll and authorization options The queryAll functionality is provided by the AdminAuthorizationOptions object, which can be passed to the query table API instead of the AuthorizationOptions object. The caller must be in the BPESystemAdministrator, TaskSystemAdministrator, BPESystemMonitor, or TaskSystemMonitor. The queryAll method which can be used by users that have the BPESystemAdministrator Java EE role to return all of the objects in the query result without being restricted by work items for a particular user or group.
Internationalization For attributes of query tables and for the query table, localized display names and descriptions are available when query tables are used. Names of the columns of the selected views, as they appear in the database or as they are specified in the select clause, are returned.

Queries on BPEL process and task data

Characteristic	query table API	query API
Availability	The query table API is available for the Business Flow Manager EJB, web services, and the REST programming interfaces.	The query API is available for EJB, web services, JMS, and REST programming interfaces.
Methods for content retrieval	The API provides the following methods: queryEntities queryEntityCount queryRows queryRowCount	The API provides the following methods: query queryAll queryProcessTemplates queryTaskTemplates
Methods for meta data retrieval	The API provides the following methods: getQueryTableMetaData findQueryTableMetaData	The API provides the following methods: QueryResultSet.getColumnType
Query table name	Specifies the query table on which the query table API is run. Only one query table can be queried at any one time. For example, queryEntities("CUST.TASKS", ...).	The SELECT clause specifies the columns and predefined database views on which the query runs. This specification is similar to an SQL select clause. For example, query("TASK.TKIID, TASK.STATE, WORK_ITEM.REASON", ...).
SELECT clause and selected attributes	Use the filter options of the query table API to specify the attributes that the query is to return. Because the query is run against one query table, the attributes are uniquely identifiable by their names.	Use the SELECT clause to specify attributes. The syntax of the attribute name is: view_name. attribute_name. For example, to search for task states, specify TASK.STATE in your query.
WHERE clause and filters	Use the queryCondition property on the query table API to further filter the result of queries. Query tables provide pre-filtered content if primary query table filters, authorization filters, or query table filters have been specified on the query table definition.	Use the WHERE clause to filter the result of the query.
WHERE clause and selection criteria	The WHERE clause of the query API is not needed in this form on the query table API. Use the queryCondition property on the query table API for additional filtering. Selection criteria in the query table definition select a particular property of the attached query table. This is achieved in addition to the filtering by the WHERE clause on the query API.	Selection criteria are not available for the query API. However, selection criteria are similar to the part of the WHERE clause that defines, for example, the name or locale of QUERY_PROPERTY, or TASK_CPROP, or TASK_DESC. For example, a WHERE clause of QUERY_PROPERTY.NAME='xyz' is the same as specifying NAME='xyz' as a selection criterion on the query table definition for the QUERY_PROPERTY attached query table.
Work items and authorization	Use the WORK_ITEM query table to access work items. You can customize the use of work items on the query table definition when the query table is developed and on the query table API, using the AuthorizationOptions object or the AdminAuthorizationOptions object. For example, to exclude everybody work items when querying the TASK query table, specify a queryCondition property WI.EVERYBODY=0 or specify setUseEverbody(Boolean.FALSE) on the AuthorizationOptions property.	Use the WORK_ITEM view to access work items. All four types of work items are considered for the query result: everybody, individual, groups, and inherited work items. To filter the work items for a specific type of work item, customize the WHERE clause. For example, to exclude the everybody work items, specify WORK_ITEM.EVERYBODY=0, in the WHERE clause.
Parameters	You can use parameters in filters and selection criteria for composite query tables.	Parameters are not available for the query API unless stored queries are used.
Stored queries and query tables	The difference between a stored query and a query table is that stored queries are defined for one particular query, while a query table is defined for a particular set of queries. For example, the query table definition does not allow the specification of an order-by clause because this information is typically available only when the query is run.	You can use stored queries to run query that contains a predefined set of options.
Materialized views	Materialized views are not available for the query table API.	Materialized views use database technologies to provide performance improvements for queries.
Custom tables	Supplemental query tables offer the same functionality as custom tables.	Custom tables are used to include data in queries that is external to the Business Process Choreographer database schema.
queryAll and authorization options	The queryAll functionality is provided by the AdminAuthorizationOptions object, which can be passed to the query table API instead of the AuthorizationOptions object. The caller must be in the BPESystemAdministrator, TaskSystemAdministrator, BPESystemMonitor, or TaskSystemMonitor.	The queryAll method which can be used by users that have the BPESystemAdministrator Java EE role to return all of the objects in the query result without being restricted by work items for a particular user or group.
Internationalization	For attributes of query tables and for the query table, localized display names and descriptions are available when query tables are used.	Names of the columns of the selected views, as they appear in the database or as they are specified in the select clause, are returned.