Provides the application programming interface (API) for managing process-related objects in the ProcessChoreographer Business Flow Manager. You can create application programs that use the API to manage runtime information related to processes. You can:
The API contains a stateless session bean BusinessFlowManager for local and remote access. The BusinessFlowManagerService interface describes the functions that can be called locally and remotely. It exposes the functions that can be called by an application program. The application program can be any Java program, including another EJB.
The application program accesses the BusinessFlowManager session bean through the bean's home and remote or local interfaces. A reference must be added to your application deployment descriptor. For example, for client applications such as a J2EE client application add the reference to the application-client.xml, for a Web application to the web.xml, and for an EJB application to the ejb-jar.xml.
Add the reference to the remote interface as in the following example:
<ejb-ref> <ejb-ref-name>ejb/BusinessFlowManagerHome</ejb-ref-name> <ejb-ref-type>Session<ejb-ref-type> <home>com.ibm.bpe.api.BusinessFlowManagerHome</home> <remote>com.ibm.bpe.api.BusinessFlowManager</remote> </ejb-ref>
Add the reference to the local interface as in the following example:
<ejb-local-ref> <ejb-ref-name>ejb/LocalBusinessFlowManagerHome</ejb-ref-name> <ejb-ref-type>Session<ejb-ref-type> <local-home>com.ibm.bpe.api.LocalBusinessFlowManagerHome</local-home> <local>com.ibm.bpe.api.LocalBusinessFlowManager</local> </ejb-local-ref>
If you use WebSphere Integration Developer to add the EJB reference to the deployment descriptor, the binding for the EJB reference is automatically created when the application is deployed.
If you use the remote interface of the BusinessFlowManager bean, complete the following actions:
The BusinessFlowManager home interface is then made available to the client through JNDI by the container where the BusinessFlowManager session bean is deployed. To access the remote interface:
// Obtain the default initial JNDI context Context initialContext= new InitialContext(); // Lookup the remote home interface of the BusinessFlowManager bean Object result= initialContext.lookup("java:comp/env/ejb/BusinessFlowManagerHome"); // Convert the lookup result to the proper type BusinessFlowManagerHome processHome= (BusinessFlowManagerHome)javax.rmi.PortableRemoteObject.narrow(result,BusinessFlowManagerHome.class);To access the local interface:
// Obtain the default initial JNDI context Context initialContext= new InitialContext(); // Lookup the local home interface of the BusinessFlowManager bean LocalBusinessFlowManagerHome processHome= (LocalBusinessFlowManagerHome)initialContext.lookup("java:comp/env/ejb/LocalBusinessFlowManagerHome");
The home interface contains a create method that returns the BusinessFlowManager session bean's remote or local interface. For example, access the remote interface of the session bean:
BusinessFlowManager process= processHome.create();For example, access the local interface of the session bean:
LocalBusinessFlowManager process= processHome.create();
When the BusinessFlowManager session bean is accessed, the application program can call any of the business functions exposed by the API. For example:
process.initiate("MyProcessModel",input);
If the method called does not complete successfully, an exception is thrown that denotes the cause of the error. You can handle this exception specifically to provide guidance to the caller.
However, it is common practice to handle only a subset of the exceptions specifically and to provide general guidance for the other potential exceptions. All specific exceptions inherit from a generic ProcessException. It is a best practice to catch the generic exception with a final catch(ProcessException) statement. This statement helps to ensure the upward compatibility of your application program because it takes account of all of the other exceptions that can occur, now and in future releases.
When a method is called, null can be specified as a parameter value to indicate that a value is not passed. For example, the order-by clause of a query call can be null to indicate that the result of the query is not to be sorted.
Always qualify your null values to prevent potential upgrade problems to a newer level of WebSphere Process Server, for example, specify (String)null or (Integer)null instead of just null.
Also note that access to the BusinessFlowManager session bean does not guarantee that all functions can be executed; the caller must also be authorized for these actions.
When an instance of the BusinessFlowManager session bean is created, the container associates a context with the instance of the session bean. The context contains the caller's principal ID, a group membership list, and indicates whether the caller has one of the Business Flow Manager J2EE roles, that is, whether the caller belongs to the group of BPE system administrators or monitors. The context is used by both the container and the process engine to check the caller's authorization for each call even when global security is not set. If global security is not set, the caller's principal ID has the value 'UNAUTHENTICATED'.
In other words, if global security is set, you need to login before the API can be accessed.
Calls from applications are run as transactions. A transaction is either established and ended explicitly by the application program, or established by the container when the application progam calls the process engine and ended by the container when the application program receives the result (the deployment descriptor specifies TX_REQUIRED). For example, the application program can establish and end a transaction as follows:
// Obtain user transaction interface UserTransaction transaction= (UserTransaction)intialContext.lookup("jta/usertransaction"); // Begin a transaction transaction.begin(); // Process calls ... // On successful return, commit the transaction transaction.commit();Design your own transactions to prevent database deadlocks when multiple transaction instances are run concurrently. For example, avoid running statements similar to the following in parallel:
UserTransaction transaction= (UserTransaction)intialContext.lookup("jta/usertransaction"); transaction.begin(); process.getActivityInstance(aiid); // read-locks the activity process.claim(aiid); // write-locks the activity to update the state transaction.commit();
The following table shows how WebSphere Process Server terms map to WebSphere Integration
Developer terms.
WebSphere Process Server | WebSphere Integration Developer |
---|---|
participating task | to-do task |
staff activity | human task activity |