com.oracle.bpel.client
Interface IInstanceHandle

All Superinterfaces:

IInstanceConstants

public interface IInstanceHandle

extends IInstanceConstants

The IInstanceHandle interface allows the user to perform operations on an active instance. An instance in the process domain represents a long-running, multi-step business transaction that may involve orchestration (or conversations) between multiple performers or service components (represented as activities).

Instances, once started by the process domain, may be administered (for example, an instance may be suspended, resumed or aborted) via this interface. In addition, this interface allows developers to access run-time attributes of the instance (for instance, the current title value of the instance, or even a data field value).

Since:

1.0

Field Summary

Fields inherited from interface com.oracle.bpel.client.IInstanceConstants

PRIORITY_NORMAL, STATE_CLOSED_ABORTED, STATE_CLOSED_CANCELLED, STATE_CLOSED_COMPLETED, STATE_CLOSED_FAULTED, STATE_CLOSED_PENDING_CANCEL, STATE_CLOSED_STALE, STATE_INITIATED, STATE_OPEN_FAULTED, STATE_OPEN_RUNNING, STATE_OPEN_SUSPENDED

Method Summary

void	abort() Aborts the instance.
void	cancel() Cancels the instance.
void	delete() Delete the instance from the process domain.
java.lang.String	getAuditDetails(int detailId) Returns the details for a single audit trail entry.
java.lang.String	getAuditTrail() Returns the XML representation of the audit trail of this instance.
java.lang.String	getConversationId() Returns the converationId of this instance.
java.util.Date	getCreationDate() Retrieves the creation date of this instance.
java.lang.String	getCreator() Retrieves the creator of this instance.
java.lang.String	getDebugTrace() Returns an XML dump of the instance.
java.lang.Object	getField(java.lang.String name) Retrieves the value of a data field from within this process instance.
java.lang.String	getIndex(int i) Returns the specified index value for this instance.
java.lang.String	getInstanceTrace() Returns an XML dump of the instance.
java.lang.String	getMetadata() Returns the user specified metadata of this instance.
java.util.Date	getModifyDate() Retrieves the date this instance was last modified on.
java.lang.String	getParentId() Returns the parent identifier of this instance.
int	getPriority() Retrieves the current priority of this instance.
IBPELProcessHandle	getProcess() Returns a handle to the BPEL process that this instance belongs to.
ReferenceId	getReferenceId() Retrieves the reference identifier of this instance.
java.lang.Object	getResult() Retrieves the return value of the instance.
java.lang.String	getRootId() Returns the root identifier of this instance.
java.lang.String	getStage() Retrieves the current stage of this instance.
int	getState() Retrieves the current state of this instance.
java.lang.String	getStatus() Retrieves the current status of this instance.
java.lang.String	getTitle() Retrieves the current title of this instance.
java.lang.String	getTransactionTrail() Returns an XML dump of the transaction status for this instance.
boolean	isCancelled() Returns true if this instance has been cancelled.
boolean	isClosed() Returns true if the state of this instance is either one of: closed.pending.cancel closed.completed closed.faulted closed.cancelled closed.aborted closed.stale
boolean	isComplete() Returns true if this instance is complete.
boolean	isFaulted() Returns true if this instance has completed abnormally (that is, due to a fault/exception).
boolean	isOpen() Returns true if the state of this instance is either one of: open.running open.suspended open.faulted
boolean	isStale() Returns true if this instance has been marked as stale.
IActivityHandle[]	listActivities() Returns the handles for all the activities that belong to this instance.

Method Detail

getReferenceId

public ReferenceId getReferenceId()

Retrieves the reference identifier of this instance. The reference identifier is the key which can uniquely identify the instance within the process domain.

Returns:

the reference identifier of this instance.

getCreationDate

public java.util.Date getCreationDate()
                               throws ServerException

Retrieves the creation date of this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getCreator

public java.lang.String getCreator()
                            throws ServerException

Retrieves the creator of this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getModifyDate

public java.util.Date getModifyDate()
                             throws ServerException

Retrieves the date this instance was last modified on.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getState

public int getState()
             throws ServerException

Retrieves the current state of this instance.

Returns:

the current state of this instance as an int

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isOpen

public boolean isOpen()
               throws ServerException

Returns true if the state of this instance is either one of:

• open.running
• open.suspended
• open.faulted

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isClosed

public boolean isClosed()
                 throws ServerException

Returns true if the state of this instance is either one of:

• closed.pending.cancel
• closed.completed
• closed.faulted
• closed.cancelled
• closed.aborted
• closed.stale

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isComplete

public boolean isComplete()
                   throws ServerException

Returns true if this instance is complete. An instance is complete if it does not contain any active activities.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isFaulted

public boolean isFaulted()
                  throws ServerException

Returns true if this instance has completed abnormally (that is, due to a fault/exception).

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isCancelled

public boolean isCancelled()
                    throws ServerException

Returns true if this instance has been cancelled. Instances that terminate due to a fault condition while executing are considered faulted. Instances that are cancelled have had administrative action taken upon them.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

isStale

public boolean isStale()
                throws ServerException

Returns true if this instance has been marked as stale. When a BPEL process is deployed on top of an existing (that is, deployed) BPEL process with the same process identifier and revision tag, all instances created from the old BPEL process are marked as stale and cannot be acted upon any longer.

Instances belonging to undeployed processes are also marked as stale.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

See Also:

IInstanceConstants

getPriority

public int getPriority()
                throws ServerException

Retrieves the current priority of this instance. The priority for the instance can be set via the setPriority() method from a BPELX java exec tag.

The semantics attached to the priority value are the sole domain and responsibility of the developer.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getTitle

public java.lang.String getTitle()
                          throws ServerException

Retrieves the current title of this instance. The title for the instance can be set via the setTitle() method from a BPELX java exec tag.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getStatus

public java.lang.String getStatus()
                           throws ServerException

Retrieves the current status of this instance. The status for the instance can be set via the setStatus() method from a BPELX java exec tag.

The semantics attached to the status value are the sole domain and responsibility of the developer.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getStage

public java.lang.String getStage()
                          throws ServerException

Retrieves the current stage of this instance. The stage for the instance can be set via the setStage() method from a BPELX java exec tag.

The semantics attached to the stage value are the sole domain and responsibility of the developer.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getConversationId

public java.lang.String getConversationId()
                                   throws ServerException

Returns the converationId of this instance. When an instance is created the user may pass the process domain a user-specified key; this key has no system-specific meaning and is only available as a means for linking a Collaxa process instance with an external system.

The semantics attached to the value of the key are the sole domain and responsibility of the developer.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getParentId

public java.lang.String getParentId()
                             throws ServerException

Returns the parent identifier of this instance. When an instance is calling another instance, a system specified id is passed. This id is identified by the instance being called as the parentId. This id can be used to locate the caller of an instance.

The semantics attached to the status value are the sole domain and responsibility of the user.

Throws:

ServerException

getRootId

public java.lang.String getRootId()
                           throws ServerException

Returns the root identifier of this instance. When an instance is created the user may pass the process domain a user-specified key. This key will then be passed as part of the requests to other processes being called. This key has no system-specific meaning and is only available as a means for identifying a set of related instances.

The semantics attached to the status value are the sole domain and responsibility of the user.

Throws:

ServerException

getMetadata

public java.lang.String getMetadata()
                             throws ServerException

Returns the user specified metadata of this instance. When an instance is created the user may pass the process domain a user-specified metadata string.

The semantics attached to the value of the key are the sole domain and responsibility of the developer.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getIndex

public java.lang.String getIndex(int i)
                          throws ServerException

Returns the specified index value for this instance. Instances may be created with index values; these indexes can be used to search for an instance later via a database query. There are six indexes available for use.

Parameters:

i - the index number, starting from 1.

Throws:

ServerException - if there is a problem fetching the meta data of this instance from the process domain.

getField

public java.lang.Object getField(java.lang.String name)
                          throws ServerException

Retrieves the value of a data field from within this process instance.

Parameters:

name - the name of the data field.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain or if a data member called name has not been declared in the instance.

getResult

public java.lang.Object getResult()
                           throws ServerException

Retrieves the return value of the instance. If the asynchronous instance has not completed yet an exception is thrown.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain or if the instance is not complete yet.

getInstanceTrace

public java.lang.String getInstanceTrace()
                                  throws ServerException

Returns an XML dump of the instance. The XML content returned will contain:

• A dump of all the attributes associated with the instance. This does not include the scope tree of the instance.
• A dump of all the activities associated with the instance.
• A dump of all the entries logged to the audit trail for this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getDebugTrace

public java.lang.String getDebugTrace()
                               throws ServerException

Returns an XML dump of the instance. The XML content returned will contain:

• A dump of all the attributes associated with the instance. This will include the scope tree of the instance (that is, the data values associated with the instance).
• A dump of all the activities associated with the instance.
• A dump of all the entries logged to the audit trail for this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getAuditTrail

public java.lang.String getAuditTrail()
                               throws ServerException

Returns the XML representation of the audit trail of this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getAuditDetails

public java.lang.String getAuditDetails(int detailId)
                                 throws ServerException

Returns the details for a single audit trail entry.

Large audit trail documents stored in the details field of any entry are persisted to a separate table than the rest of the audit trail. By doing this, the overall size of the audit trail is kept small and as a result, faster to load.

The id for a detail entry is found as an attribute on the details tag.

If no details entry can be found with the specified identifier, an empty string will be returned.

Parameters:

detailId - the identifier for the details entry

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

getTransactionTrail

public java.lang.String getTransactionTrail()
                                     throws ServerException

Returns an XML dump of the transaction status for this instance.

Throws:

ServerException - if there is a problem in fetching the meta data of this instance from the process domain.

listActivities

public IActivityHandle[] listActivities()
                                 throws ServerException

Returns the handles for all the activities that belong to this instance.

Throws:

ServerException - if there is a problem in fetching the activities for this instance.

getProcess

public IBPELProcessHandle getProcess()
                              throws ServerException

Returns a handle to the BPEL process that this instance belongs to.

Throws:

ServerException - if there is a problem in fetching the process for this instance.

cancel

public void cancel()
            throws ServerException

Cancels the instance. All active activities that belong to this instance will also be cancelled.

When an activity is cancelled, the performer of the activity is notified of the cancellation and is given an opportunity to rollback or cancel any work that has already been done on behalf of the activity. Since this clean-up procedure can take an indeterminate amount of time, cancelling an instance may not be instaneous and could result in new activities being activated.

Throws:

ServerException - if there is a problem in locating the instance in the process domain or if the requested action is not permitted (the instance this handle is referring to may have been changed in the meantime).

abort

public void abort()
           throws ServerException

Aborts the instance. Aborting an instance differs from cancelling one; the latter informs the performers of any active activities that the activity is being cancelled and allows the performer to clean-up or rollback the any changes made. Aborting an instance will simply mark the activities as having been aborted without the chance for clean-up. This method is included for administrative purposes only.

Throws:

ServerException - if there is a problem in locating the instance in the process domain or if the requested action is not permitted (the instance this handle is referring to may have been changed in the meantime).

delete

public void delete()
            throws ServerException

Delete the instance from the process domain. After this method is invoked all the data associated with this instance in the datastore will be removed. This action cannot be undone.

Throws:

ServerException - if there is a problem in locating the instance in the process domain or if there is a problem deleting the instance from the domain.