org.apache.ode.bpel.pmapi

Interface InstanceManagement

All Known Subinterfaces:

BpelManagementFacade

public interface InstanceManagement

Interface to managing process instances.

Method Summary

Modifier and Type	Method and Description
java.util.Collection<java.lang.Long>	delete(java.lang.String filter) Delete the process instances matching the given filter.
InstanceInfoDocument	fault(java.lang.Long iid, javax.xml.namespace.QName faultname, org.w3c.dom.Element faultData) Causes the process instance to complete unsuccessfully by throwing the specified fault in the global scope.
java.util.List<java.lang.String>	getEventTimeline(java.lang.String instanceFilter, java.lang.String eventFilter) Retrieve a timeline of BPEL events.
InstanceInfoDocument	getInstanceInfo(java.lang.Long iid) Get an instance by id.
ScopeInfoDocument	getScopeInfo(java.lang.String siid) Get info about a scope instance by id, not including activity info.
ScopeInfoDocument	getScopeInfoWithActivity(java.lang.String siid, boolean activityInfo) Get info about a scope instance by id, optionally including activity info.
VariableInfoDocument	getVariableInfo(java.lang.String scopeId, java.lang.String varName) Get info about a variable.
InstanceInfoListDocument	listAllInstances() Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstancesSummary(filter, order, limit)
InstanceInfoListDocument	listAllInstancesWithLimit(int limit) Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstancesSummary(filter, order, limit)
EventInfoListDocument	listEvents(java.lang.String instanceFilter, java.lang.String eventFilter, int maxCount) Retrieve BPEL events.
InstanceInfoListDocument	listInstances(java.lang.String filter, java.lang.String order, int limit) Retrieve and returns information about all, or some process instances.
InstanceInfoListDocument	listInstancesSummary(java.lang.String filter, java.lang.String order, int limit) List instances and only return summary information about the instance, combined with all correlation properties.
InstanceInfoListDocument	queryInstances(java.lang.String query) Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstances(filter, order, limit)
InstanceInfoDocument	recoverActivity(java.lang.Long iid, java.lang.Long aid, java.lang.String action) Performs an activity recovery action.
InstanceInfoDocument	resume(java.lang.Long iid) Resume the (previously suspended) instance.
InstanceInfoDocument	suspend(java.lang.Long iid) Changes the process state from active to suspended.
InstanceInfoDocument	terminate(java.lang.Long iid) Causes the process instance to terminate immediately, without a chance to perform any fault handling or compensation.

Method Detail

listInstances

InstanceInfoListDocument listInstances(java.lang.String filter,
                                       java.lang.String order,
                                       int limit)

Retrieve and returns information about all, or some process instances. The request identifies the process instances using a filter that can select instances with a given name, status, property values, etc. Without a filter, the operation returns all process instances up to a specified limit<.code>. The request also indicates which key fields to use for ordering the results.

The filter element can be used to narrow down the list of process definitions by applying selection criteria. There are six filters that can be applied:

• name -- Only process instances with this local name.

• namespace -- Only process instances with this namespace URI.

• status -- Only process instances with these status code(s).

• started -- Only process instances started relative to this date/time.

• last-active -- Only process instances last active relative to this date/time.

• $property -- Only process instances with a correlation property equal to the specified value.

The name and namespace filters can do full or partial name matching. Partial matching occurs if either filter ends with an asterisk (*). These filters are not case sensitive, for example name=my* will match MyProcess and my-process. If unspecified, the default filter is name=* namespace=*.

The status filter can be used to filter all process definitions based on six status codes:

• active -- All currently active process instances (excludes instances in any other state).

• suspended -- All process instances that have not completed, but are currently suspended.

• error -- All process instances that have not completed, but are currently indicate an error condition.

• completed -- All successfully completed process instances (excludes instances in any other state).

• terminated -- All process instances that were terminated.

• faulted -- All process instances that encountered a fault (in the global scope).

The started filter can be used to filter all process instances started on or after a particular date or date/time instant. The value of this filter is either an ISO-8601 date or ISO-8601 date/time. For example, to find all process instances started on or after September 1, 2005, use started>=20050901. Similarly, the last-active filter can be used to filter all process instances based on their last active time. The last active time records when the process last completed performing work, and either completed or is now waiting to receive a message, a timeout or some other event.

Each process instance has one or more properties that are set its instantiation, that can be used to distinguish it from other process instances. In this version of the specification, we only support properties instantiated as part of correlation sets defined in the global scope of the process. For example, if a process instantiates a correlation set that uses the property order-id, it is possible to filter that process instance based on the value of that property.

The property name is identified by the prefix $. If the property name is an NCName, the filter will match all properties with that local name. If the property name is {namespace}local, the filter will match all properties with the specified namespace URI and local name. For example, to retrieve a list of all active process instances with a property order-id that has the value 456, use status=active $order-id=456.

By default the response returns process instances in no particular order. The order element can be used to order the results by specifying a space-separated list of keys. Each key can be prefixed with a plus sign '+' to specify ascending order, or a '-' minus sign to specify descending order. Without a sign the default behavior is to return process instances in ascending order. The currently supported odering keys are:

• pid

-- Order based on the process identifier.

• name

-- Order based on the local name of the process instance.

• namespace

-- Order based on the namespace URI of the process instance.

• version

-- Order based on the version number.

• status

-- Order based on the status of the process instance.

• started

-- Order based on the process instance start date/time.

• last-active

-- Order based on the process instance last active date/time.

Parameters:

filter - filter string

order - order keys

limit - maximum number of instances to return

Returns:

list of matching instances

listInstancesSummary

InstanceInfoListDocument listInstancesSummary(java.lang.String filter,
                                              java.lang.String order,
                                              int limit)

List instances and only return summary information about the instance, combined with all correlation properties.

Parameters:

filter - See listInstances' filter argument

order - See listInstances' order argument

limit - maximum number of instances to return

Returns:

list of matching instances

queryInstances

InstanceInfoListDocument queryInstances(java.lang.String query)

Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstances(filter, order, limit)

listAllInstances

InstanceInfoListDocument listAllInstances()

Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstancesSummary(filter, order, limit)

List all instances in the default (database) order.

Returns:

list of matching instances

See Also:

listInstances(String, String, int)

listAllInstancesWithLimit

InstanceInfoListDocument listAllInstancesWithLimit(int limit)

Deprecated. As of Ode 1.3, this method is deprecated in favor of listInstancesSummary(filter, order, limit)

List up to limit instances in the default (database) order.

Parameters:

limit - maximum number of instances to return

Returns:

list of matching instances

See Also:

listInstances(String, String, int)

getInstanceInfo

InstanceInfoDocument getInstanceInfo(java.lang.Long iid)
                              throws InstanceNotFoundException

Get an instance by id.

Parameters:

iid -

Returns:

information about a specific instance

Throws:

InstanceNotFoundException - TODO

getScopeInfo

ScopeInfoDocument getScopeInfo(java.lang.String siid)

Get info about a scope instance by id, not including activity info.

Parameters:

siid - scope instance identifier

Returns:

information about a specific scope instance

See Also:

getScopeInfoWithActivity(String, boolean)

getScopeInfoWithActivity

ScopeInfoDocument getScopeInfoWithActivity(java.lang.String siid,
                                           boolean activityInfo)

Get info about a scope instance by id, optionally including activity info.

Parameters:

siid - scope instance identifier

activityInfo - if true, include activity info

Returns:

information about a specific scope instance

getVariableInfo

VariableInfoDocument getVariableInfo(java.lang.String scopeId,
                                     java.lang.String varName)

Get info about a variable.

Parameters:

scopeId - scope identifier

varName - variable name

Returns:

information about variable (basically the value)

listEvents

EventInfoListDocument listEvents(java.lang.String instanceFilter,
                                 java.lang.String eventFilter,
                                 int maxCount)

Retrieve BPEL events. One may specify an "instance filter" and an "event filter" to limit the number of events returned. The instance filter takes the exact same syntax as for the listInstances(String, String, int) method. The "event filter" employs a similar syntax; the following properties may be filtered:

1. type - the event type
2. tstamp - the event timestamp

Parameters:

instanceFilter - instance filter (if set,return only events for matching instances)

eventFilter - event filter (event type and data range)

Returns:

list of events

getEventTimeline

java.util.List<java.lang.String> getEventTimeline(java.lang.String instanceFilter,
                                                  java.lang.String eventFilter)

Retrieve a timeline of BPEL events.

Parameters:

instanceFilter - instance filter (if set,return only events for matching instances)

eventFilter - event filter (event type and data range)

Returns:

list of stringified dates (in ISO format)

suspend

InstanceInfoDocument suspend(java.lang.Long iid)

Changes the process state from active to suspended. this affects process instances that are in the active or error states.

Parameters:

iid - instance id

Returns:

post-change instance information

resume

InstanceInfoDocument resume(java.lang.Long iid)

Resume the (previously suspended) instance. This operation only affects process instances that are in the suspended state.

Parameters:

iid - instance id

Returns:

post-change instance information

terminate

InstanceInfoDocument terminate(java.lang.Long iid)

Causes the process instance to terminate immediately, without a chance to perform any fault handling or compensation. The process transitions to the terminated state. It only affects process instances that are in the active, suspended or error states.

Parameters:

iid - instance id

Returns:

post-change instance information

fault

InstanceInfoDocument fault(java.lang.Long iid,
                           javax.xml.namespace.QName faultname,
                           org.w3c.dom.Element faultData)

Causes the process instance to complete unsuccessfully by throwing the specified fault in the global scope. The process is able to perform recovery using a fault handler in the global scope, through termination handlers in nested scopes and by invoking installed compensation handlers. The process will transition to the faulted state.

Parameters:

iid - instance id

faultname - name of the fault

faultData - fault data

Returns:

post-change instance information

delete

java.util.Collection<java.lang.Long> delete(java.lang.String filter)

Delete the process instances matching the given filter.

Parameters:

filter - instance filter (see listInstances(String, String, int) ).

Returns:

collection of instances identfiers, corresponding to deleted instances

recoverActivity

InstanceInfoDocument recoverActivity(java.lang.Long iid,
                                     java.lang.Long aid,
                                     java.lang.String action)

Performs an activity recovery action.

Parameters:

iid - instance id (process)

aiid - instance id (activity)

action - recovery action (e.g. retry, fault)

Returns:

post-change instance information