Working with Process Interfaces

This chapter provides the following sections describing the usage of Infinity Process Platform API concerning process interfaces:

Interface ProcessInterface

The interface ProcessInterface holds an ordered list of formal parameters (instances of FormalParameter interface) as defined in the model. This list may be empty, but never null, if the process interface does not define formal parameters.

public interface ProcessInterface extends Serializable
{
   QName getDeclaringProcessDefinitionId();

   List<FormalParameter> getFormalParameters();
}

The process definition may hold references to the interface it implements and the interface it declares.

There are three different valid states concerning declared and implemented process interfaces:

Retrieving the Implemented Process Interface

To get the process interface implemented by a process definition, use the method

ProcessInterface getImplementedProcessInterface();

of the ProcessDefinition class.

The method returns a ProcessInterface object or null, if the process does not implement an interface.

Retrieving the Declared Process Interface

To get the process interface declared by a process definition, use the method

ProcessInterface getDeclaredProcessInterface();

of the ProcessDefinition class.

The method returns a ProcessInterface object or null, if the process does not declare an interface.

Formal Parameter Types

Note that the formal parameter's data type will not be be exposed as a first class element, but can be retrieved from the formal parameter's attributes map as the following examples illustrate.

For structured types:

Formal Parameter fp = ...
String typeDeclarationId = (String) fp.getAttribute(StructuredDataConstants.TYPE_DECLARATION_ATT);

For primitive types:

Formal Parameter fp = ...
org.eclipse.stardust.engine.core.pojo.Type type = (org.eclipse.stardust.engine.core.pojo.Type) fp.getAttribute(PredefinedConstants.TYPE_ATT);

Retrieving Process Instance Results

After a process instance has been completed, the output data of this process instance, provided as a key set of formal parameter IDs and corresponding data values, can be retrieved via the following method of the WorkflowService:

Map<String, Serializable> getProcessResults(long processInstanceOID)
         throws ObjectNotFoundException, AccessForbiddenException;

In case the given process instance OID points to a process instance whose process definition does neither implement nor declare an interface, an empty map will be returned.

If the process instance has not been completed yet or the process instance the given OID points to isn't a root process instance, an AccessForbiddenException is thrown.

Selecting the Primary Implementation for Process Interfaces

The AdministrationService provides a method setPrimaryImplementation to specify which implementation alternative should be considered as the Primary Implementation of a given process interface.

DeploymentInfo setPrimaryImplementation(long interfaceModelOid, String processId, String implementationModelId,
         LinkingOptions options) throws DeploymentException;

This method specifies which implementation alternative (identified by implementationModelId) will be considered as the Primary Implementation of the Process Interface identified by processId (in scope of the deployment identified by interfaceModelOid).

If the implementation model is defining one or more than one implementation for the same interface, the implementationModelId must be specified as a fully qualified ID of the implementation process for the, i.e. "{" + model_id + "}" + process_definition_id . However, if a model contains only one process interface implementation then specifying model ID is also appropriate.

The linking options contain the following:

public class LinkingOptions implements Serializable
{
   /**
    * The deployment comment.
    */
   public String getComment();

   public void setComment(String comment);
}

It is not possible to select a primary implementation, if no valid version of the target model (determined by implementationModelId) that implements the interface defined by the parameters interfaceModelOid and processId is available. This could happen in one of the following cases:

In these cases, calling the setPrimaryImplementation() fails with a DeploymentException.

The required permission to execute this method is deployProcessModel.

Note that changing the primary implementation becomes effective for new process instance hierarchies started. Instances already running will continue to use the primary implementations that were effective at the start time of the root process instance.

Please refer to the section AdministrationService of the chapter Infinity Process Platform Services for information on this service and the according Javadoc of the AdministrationService for detailed information on its methods and their parameter usage.

Getting Implementation Details

The interface ImplementationDescription provides information about a specific implementation of a Process Interface, like the local ID of the implemented process interface, local ID of the implementing process definition or a check, if the implementation is a primary implementation. The following methods are provided:

Deleting Referenced Model

The following consistency check is performed with the deleteModel() method. An exception will be thrown in case of:

Furthermore, deletion will not be allowed if there are running process instances that are using this model (be it via model element references or as a primary implementation). But note that you can delete a model set as primary implementation if there is a previous implementation available. To determine that, the tree of model references valid for that running instance and not only the current set of model references has to be considered. After deleting the model, the internal records of existing implementations for process interfaces need to be updated.