Invoking a Process from Java
Process Server provides an API for dispatching a message directly to the engine. This API is available as an Enterprise Java Bean (EJB) on platforms that support EJB or as a plain Java API for deployment platforms without an EJB container.
The following illustration shows an overview of the external and standard implementations of My Role service endpoints.
The Process Server engine’s Enterprise Java Bean (EJB) binding implements the following interface:
public interface org.activebpel.wsio.receive.IAeMessageQueue
{
/**)
* Delivers the message to the BPEL engine's message queue.
*
* @param aData
* @param aContext
* @return IAeWebServiceResponse
* @throws RemoteException
* @throws AeRequestException
*/
queueReceiveData
(org.activebpel.wsio.IAeWebServiceMessageData aData,
org.activebpel.wsio.receive.IAeMessageContext aContext)
throws RemoteException,
org.activebpel.wsio.receive.AeRequestException;
where:
- •IAeMessageQueue is name of the interface. The package is org.activebpel.wsio.receive.
- •IAeWebServiceResponse is the interface for the data or fault that can be returned from the calling service.
- •queueReceiveData is a method that a service endpoint can invoke passing in context and data.
- •IAeWebServiceMessageData contains the data for the inbound message.
- •IAeMessageContext contains the contextual information for the request.
Steps to Invoke a Process using plain Java or EJB API
Step 1: Include required .jar files on your java project classpath
The API is contained in the following .jar files. If using the plain Java API, only ae_wsio.jar is required, if using the EJB implementation, both are required in the classpath.
- •ae_wsio.jar contains the core interfaces used to send messages to the engine.
- •ae_awfwsio.jar contains the required interfaces for interacting with the Process Server engine EJB.
Step 2: Lookup the EJBHome
From Java code, lookup the EJBHome for the AeMessageQueueBean from JNDI context and create an instance of the bean. For example:
InitialContext ctx = new InitialContext();
object home = ctx.lookup("ejb/AeMessageQueueBean");
Home = (AeMessageQueueHome)
portableRemoteObject.narrow(home,AeMessageQueueHome.class);
eMessageQueueRemote msgQueueBean = mHome.create();
Step 3: Create an instance of AeMessageContext.
The AeMessageContext object contains the relevant details about the My Role partner link from the BPEL process. These details make up the context for the inbound messages sent to the engine. and are:
AeMessageContext Parameters | Description |
|---|
setProcessName | Process Qname. The Qname includes the namespace plus the local part of the process name. In a BPEL source file, this is the target namespace. Note: You can specify a service name instead of a process/partnerlink name. For a discussion of service name, see My Role Endpoint and the Process Consumer. |
setPartnerLinkName | Partner link name from the BPEL process |
setServiceName | Optional. As an alternative to setting the process and partner link name, you may specify the My Role (Process Consumer) service name. This name is in the Process Deployment Descriptor Editor on the Partner Links page and is also on the Service Definitions page in the Process Console. This property is mutually exclusive with the process name and only one or the other may be set on the context. |
setOperation | Operation from the portType of the partner link type defined for My Role |
setProcessVersion | Optional. Messages are sent to the current process if a process version is not specified. |
setPrincipal | Optional. This value is used by the engine for performing lookups on deployed partner definitions when using the "Principal" endpoint type. Identifies the principal name value for inbound messages. Processes that include human tasks also use this value to identify the process initiator. |
Example code for creating a new message context:
// Create the message context object for the request
/ containing the routing information for the process
eMessageContext context = new AeMessageContext();
context.setProcessName(new QName(aProcessNamespace,aProcessName));
context.setPartnerLink(aPartnerLink);
context.setOperation(aOperation);
Step 4: Create an instance of AeWebServiceMessageData
The context details are as follows:
AeWebServiceMessageData Parameters | Description |
|---|
Constructor QName | The QName specified in the constructor corresponds to the QName of the WSDL message associated with the input message |
setData | Each message part is defined in this parameter. Message parts must be primitive types like strings, integers, or XML passed as DOM Document object. Complex types get passed as documents. The XML document must conform to the schema definition of the complex type. If a message has correlated properties in it, the engine extracts these properties using the property aliases and routes the message to the correct process instance. |
WSDL Message for the message data object:
<wsdl:message name="creditInformationMessage">
<wsdl:part name="part1" element="tns:LoanProcessRequest" />
<wsdl:part name="part2" element="tns:LoanProcessAddress" />
</wsdl:message>
Example code for creating message data object:
AeWebServiceMessageData data = new AeWebServiceMessageData (new
QName("http://tempuri.org/services/loandefinitions","creditInformationMessage"));
data.setData("part1", domOfLoanProcessRequest);
data.setData("part2", domOfLoanProcessAddress);
Invoke the queueReceiveData method on the bean.
IAeWebServiceResponse response = msgQueueBean.queueReceiveData(data,context);
The context details are as follows:
IAeWebServiceResponse Parameter | Description |
|---|
getMessageData() | Message data returned from the invoke. See the description of AeWebServiceMessageData for details. |
isFaultResponse() | Return true if the response wraps a fault |
getErrorCode() | Accessor for the error code QName |
getErrorString() | Returns an error message associated with the fault or null if there is none |
getErrorDetail() | Returns a stack trace or other detailed information associated with the fault or null if there was none |
getRootCause() | Returns a Throwable that is the root cause of the error code |
getBusinessProcessProperties() | Return a Map of (string) name/value pairs from the business process |
