Server User Guide > My Role Endpoint and the Process Consumer > Invoking a Process from Java
  

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:
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.
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