Guide to Building Business Processes

Calling Business Processes

How you call a business process from another application depends on your business requirements, including whether the client is in the same application as the business process it calls, and whether the client is a WebLogic Workshop component, such as a Web service (JWS), business process (JPD), or pageflow (JPF). To learn about invoking business processes, see the following topics:

How Do I: Call Business Processes?

Business Processes can expose their functionality to clients in several ways, including through WSDL files, Process Controls, Service Broker Controls, and Business Process (Process.java) Proxies.

You can only use Process controls and Service Broker controls between WebLogic Workshop components: Web services (JWS), business processes (Process.java), or pageflows (JPF).

The Process control allows a Web service, business process, or pageflow to send requests to, and receive callbacks from, a business process. Process control invocations are Java Remote Method Invocation (RMI) calls. The target business process must be hosted on the same WebLogic Server domain as the caller. The Process control is typically used to call a subprocess from a parent business process. Transaction contexts are propagated from the parent processes to the subprocesses over the Process control calls. In other words, the target business process runs in the same transaction as the caller.

The Service Broker control allows a business process or Web service to invoke and receive callbacks from another service using one of several protocols; the most commonly used protocol is SOAP over HTTP. (To learn about the protocols, see Using Dynamic Binding.) The target service must expose a WSDL interface; it can be a business process, Web service, or remote (non-Workshop) Web service. Because the transport used is HTTP or JMS, the transaction contexts are not propagated over the Service Broker control calls. Typically, the Service Broker control calls are to remote services.

To call business processes from non-Workshop clients, use a JPD Proxy. You can use a JPD Proxy to communicate with a business process from any Java code. When you invoke a business process using a JPD Proxy, the calls are Java RMI calls. Transaction contexts are propagated from the client to the business process over the JPD Proxy calls. In other words, if the client has a transaction context, the target business process runs in the same transaction as the client. JPD Proxies are typically used by non-Workshop J2EE clients or standalone Java clients to invoke business processes.

Depending on the nature of the client and where it is with respect to the target business processes, clients call the business processes in different ways. The following sections describe the scenarios:

Workshop Client Invokes a Business Process in a Different Domain

If the client is a Workshop client (a Web service, a business process, or a pageflow) and the target business process is in a different domain than the client, use a Service Broker control. In this case, create a Service Broker control from the target business process and call the business process using that control. To learn how to create and use Service Broker controls, see Service Broker Control.

You can also use a JPD Proxy in this case. To learn how, see How Do I: Use a JPD Proxy to a Call Business Process?

Workshop Client Invokes a Business Process in the Same Workshop Application

If the client is a Workshop client (a Web service, a business process, or a pageflow) and the target business process is in the same WebLogic Workshop application, we recommend that you use a Process control. That is, create a Process control from the target business process and call the business process using that control. To learn how to create and use Process controls, see Process Control.

You can also use a Service Broker control in this case. To learn how, see Service Broker Control.

Workshop Client Invokes a Business Process in a Different Workshop Application, in the Same Domain

A Non-Workshop Java Client (EJB, servlet or JSP) Invokes a Business Process

If the client is a standalone Java program, a non-workshop J2EE client (EJB, servlet, or JSP), use a JPD Proxy to call the target business process. To learn how, see How Do I: Use a JPD Proxy to a Call Business Process?

Because JPD Proxy calls are RMI calls, the client and the target business process must be in the same organization.

How Do I: Use a JPD Proxy to a Call Business Process?

You can use a JPD Proxy to call any business process (synchronous and asynchronous, stateful, and stateless) from any Java client, including standalone Java applications, EJBs, JSPs and Servlets. Using a Java proxy for a business process requires different steps depending on whether the client application that uses the proxy is in the same JVM as the target business process.

This topic includes the following sections:

What is a JPD Proxy?

A JPD Proxy is an RMI client to a business process (JPD). An interface that matches a business process’ client requests is associated with each business process. This interface is called the JPD public contract. Each method on the JPD public contract has the same signature as the corresponding client request. A JPD Proxy is a JAR that contains the compiled class file for the JPD contract. You can use the class file to access the JPD as though it were a local Java class. JPD Proxy calls are over Java RMI. JPD Proxy calls propagate the transaction context from the clients to the business processes.

You can download the JPD Proxy JAR file from the JPD Proxy link on the WebLogic Workshop Test Browser Overview page (see How Do I: Get a JPD Proxy for a Business Process?).

The JpdProxy class is a factory class for proxies to a WebLogic Integration business process type. Clients call one of the create() methods on the class to get a proxy instance. The create() methods take the JPD contract class (java.lang.Class) as input.

An example JPD contract interface for a business process named RequestQuote.java is shown in the following listing.

package weblogic.wli.jpdproxy;

import org.example.request.QuoteRequestDocument;

public interface RequestQuote {
    public void quoteRequest(org.example.request.QuoteRequestDocument requestXML);
    public static final String SERVICE_URI =
    "/myApplication/requestquote/RequestQuote.jpd";
}

Note the following characteristics in the preceding example contract interface:

How Do I: Get a JPD Proxy for a Business Process?

About Versioned Business Processes

If the target business process is versioned, you can run the active version of the process to invoke the Test Browser (in this case, the Test Browser is opened on the virtual URI) or you can run any other version of the process (in which case the Test Browser is opened on a specific physical URI). To learn about creating versions of business processes, see Versioning Business Processes.

If you subsequently download a JPD Proxy from the Test Browser, its JPD contract interface matches the virtual JPD or the physical JPD, accordingly. When you create a Java client, you pass the JPD contract and a service URI to the proxy factory method. In most cases the JPD contract interfaces for all versions of a business process are identical, but a specific version of a business process can extend the public interface of the original process. In this case, you must ensure that the service URI and JPD contract interface passed to the proxy factory method are consistent.

How Do I: Use a JPD Proxy From a Java Client?

This section uses example code to describe how to use a JPD Proxy from a Java client. It includes the following topics:

To Use a JPD Proxy From a Java Client

This topic describes how to use a JPD Proxy from a Java client. The code listing in Listing 29-2 is an example of a Java client that invokes a business process using a JPD Proxy. This example includes basic username-password authentication. A second example ( Listing 29-5) describes how to add two-way SSL to the Java client.

You obtain the JPD Proxy JAR for the business process by first running the purchase order business process in WebLogic Workshop to invoke the Test Browser. Then select the JPD Proxy link on the Overview page of the Test Browser.

The following sections reference the code example in Example Java Client to describe how a JPD Proxy Client is used from a Java client:

Example Java Client

The code listing in Listing 29-2 is an example of a Java client that invokes a business process using a JPD Proxy. It invokes a business process named PoRequest.java. This example includes basic username-password authentication. A second example ( Listing 29-5) describes how to add two-way SSL to the Java client.

package your.package;

// Proxy classes are located in the com.bea.wli.bpm.proxy package.
import com.bea.wli.bpm.proxy.JpdProxy;
import com.bea.wli.bpm.proxy.JpdProxySession;

import weblogic.wli.jpdproxy.PoProcess;

/** 
* Import any packages required for your application. For example, if the business
* process uses XML Beans, you must import the appropriate packages.
*/
import requisitionpo.www.purchase.PurchaseDocument;
import requisitionpo.www.purchaserequestreq.PurchaseRequestReqDocument

import javax.naming.Context;
import javax.naming.NamingException;
import javax.naming.InitialContext;
import weblogic.jndi.Environment;
import java.io.*;

public class startPoProcess
{
    public static void main(String[] args)
    {
        try
        {
            PoProcess p = (PoProcess)
                JpdProxy.create(
                   PoProcess.class,
                   PoProcess.SERVICE_URI,

                    new JpdProxy.ContextHandler()
                    {
                        public Context getContext() throws NamingException
                        {
                            Environment env = new Environment();
                            env.setProviderUrl("t3://localhost:7001");
                            env.setSecurityPrincipal("weblogic");
                            env.setSecurityCredentials("weblogic");
                            return env.getInitialContext();
                        }
                   });
            PoDocument document = PoDocument.Factory.newInstance();
            Po po = document.addNewPo();
            po.setSku("abc"); 

            PoReferenceDocument ref = p.processPO(document); 
            p.done();
        }
        catch (Exception e) { ... }
    }
}

To Import the Proxy Classes

Note that the following packages are imported in our example Java client:

import com.bea.wli.bpm.proxy.JpdProxy;
import com.bea.wli.bpm.proxy.JpdProxySession;

Proxy classes are located in the com.bea.wli.bpm.proxy package. Clients can typecast proxies returned by JpdProxy.create() to JpdProxySession to set and get the conversation ID that is used when a business process is invoked. To learn about setting and getting conversation IDs, see About Conversation Management.

To Use the Proxy Factory (JpdProxy.create()) Method

The proxy factory method (JpdProxy.create()) provides two signatures: one to use when the client is running in the same WebLogic Server domain as the target business process (JPD), the other to use when the client is running in a different domain than the target business process:

Method Detail for the create() Method—Use When the Client is Running in the Same WebLogic Server Domain as the Target JPD

The JpdProxy.create() method creates a client proxy for a business process (JPD). JpdProxy.create() accepts the public-contract interface that describes the methods of the JPD as input. The result of this call can be typecast to the public contract class. A service URI uniquely identifies the business process (JPD) on the server.

Use the following method when the client is running on the same WLS domain as the target JPD.

public static final Object create(Class publicContract, String serviceUri)
                           throws JpdProxyException

In the preceding code listing:

Method Detail for the create() Method—Use When the Client is Running in a Different Domain Than the Target JPD

This method signature is shown in Listing 29-4, and is used in the example code in Listing 29-2.

The JpdProxy.create() method creates a client proxy for a business process (JPD). JpdProxy.create() accepts, as input, the public contract interface that describes the methods of the business process. The result of this call can be typecast to the public-contract class. A service URI uniquely identifies the business process on the server. For the case in which your client is running in a different domain than the target JPD, the JpdProxy.ContextHandler is invoked by the proxy to obtain the JNDI context used to login to the server and lookup server-side resources.

If you use the version of JpdProxy.create() that does not take a ContextHandler, the client’s JNDI context is used to look up the ProxyDispatcher EJB.

You need a ContextHandler in the following scenarios:

Use the following method when you need a ContextHandler:

public static final Object create(Class publicContract, String serviceUri,
JpdProxy.ContextHandler ch) throws JpdProxyException

In the preceding code listing:

To Call the Methods on the Target Business Process

To determine which client request methods are available for you to use via the JPD Proxy, review the source code for the business process. To do so, ensure that the business process (JPD) is open in the WebLogic Workshop graphical design environment, identify the Client Request calls in the Design view, then open the Source view, where you can view the method names and signatures. To learn more about the Client Request and Client Response methods in business processes, see Designing Start Nodes.

JPD Proxies cannot receive callbacks from business processes. See Limitation Using JPD Proxies for Business Processes That Include Client Callbacks.

About Strongly-Typed XML or MFL Arguments in Business Processes

Business processes can accept (as input) and return typed XML (XML Beans) and typed binary data (MFL). The JPD contract interface generated from such business process references these types. (For an example of an XML type referenced in a JPD contract, see the code listing in What is a JPD Proxy?)

Note that in our example Java client, in Listing 29-2, the following packages are imported to support the XML Bean types used in the PoProcess business process:

import requisitionpo.www.purchase.PurchaseDocument;
import requisitionpo.www.purchaserequestreq.PurchaseRequestReqDocument

About Conversation Management

You can use the JpdProxySession interface to set and get the conversation ID used when a business process is invoked. To use the JpdProxySession interface, clients can simply typecast proxies returned by JpdProxy.create() to JpdProxySession.

The dynamic proxy returned by JpdProxy.create() implements the JpdProxySession interface. The methods on the JpdProxySession interface include:

String getConversationID()

void reset()

void setConversationID(String conversationID)

The conversation ID is initialized to null. If the conversation ID is null when a method on a business process is invoked through the JPD Proxy, a unique conversation ID is generated. This unique ID is maintained in the run-time state on the client side. In other words, the value is maintained for subsequent invocations, until the client specifies a new conversation ID or resets it to null.

The same JPD Proxy instance can be used to call methods on different instances of a business process. However, clients should take care to avoid making a call with the wrong conversation ID. Specifically, when a client application is finished invoking an instance of a business process through its JPD Proxy and wants to start a new conversation, it must either explicitly set the conversation ID for the second conversation or call JpdProxySession.reset(), which causes the JPD Proxy to reset the conversation ID to null.

To learn more about the JpdProxySession interface, see Interface JpdProxySession in the WebLogic Integration Javadoc.

To Run the Java Client

The following command line describes the options that you must set when you run the example Java client (startPoProcess) shown in Listing 29-2.

java -Dbea.home=C:\bea startPoProcess

where -Dbea.home=C:\bea specifies the location of the BEA license file (license.bea).

Limitation Using JPD Proxies for Business Processes That Include Client Callbacks

JPD Proxies cannot receive callbacks from business processes. Business processes that include client callbacks send those callbacks to the client that started the business process. If a client uses a JPD Proxy to start a business process that includes client callbacks, the business process fails at run time when it tries to send the callback to the client that started it (the JPD Proxy).

To Use a JPD Proxy From a Java Client With Two-Way SSL

The example described in this section shows you how to add two-way SSL to a Java client. This section also describes the command-line options required to run the Java client so that the two-way SSL handshake can take place between the Java client and the SSL server. This section includes the following topics:

Example Java Client With Two-Way SSL

The following example demonstrates how to add two-way SSL to a Java client. The example code is explained in the text that follows the listing.

import weblogic.wli.jpdproxy.MyProcess;
import javax.naming.Context;
import javax.naming.NamingException;
import weblogic.jndi.Environment;
import com.bea.wli.bpm.proxy.JpdProxy;
import java.io.*;
import javax.naming.InitialContext;

public class startMyProcess
{
    public static void main(String[] args)
    {
        try {

            InputStream key = new FileInputStream("C:\\certcmds\\qa\\pki\\keys\\newParent.key");
            InputStream cert = new FileInputStream("C:\\keystore\\newParentx509.cer");

            final InputStream FStream[] = {key,cert};
            MyProcess tm = (MyProcess)
            JpdProxy.create(MyProcess.class,MyProcess.SERVICE_URI, 
                new JpdProxy.ContextHandler()
            {

                public Context getContext() throws NamingException
                {
                    Environment env = new Environment();
                    //Use t3s –  secure port for ssl
                    env.setProviderUrl("t3s://localhost:7002");
                    //Client Certificate and Private Key for that certificate.
                    env.setSSLClientCertificate(FStream);
                    env.setSSLClientKeyPassword("testing123");
                    return env.getInitialContext();
                }
            });
            String str = tm.requestQuote();
            System.out.println("Return String = " + str);
            }
            catch (Exception ex)
            {
                    	//Got an exception
                    System.out.println("Got Exception: " + ex);
                    ex.printStackTrace();
            }
    }
}

This example builds on the information provided in the previous section ( To Use a JPD Proxy From a Java Client) by demonstrating how to add two-way SSL to the Java client. The example code in Listing 29-5 shows a Java client that uses a JPD Proxy to invoke a business process named MyProcess.java.

The following items describe the lines of code used to set up the two-way SSL between the client and WebLogic Server:

To Run the Java Client

The following command line describes the options that you must set when you run the example Java client (startMyProcess) shown in Listing 29-5. Setting these options ensures that the two-way SSL handshake can take place between the Java client and WebLogic Server.

java -Dbea.home=C:\bea 
-Djava.protocol.handler.pkgs=com.certicom.net.ssl 
-Dweblogic.security.SSL.ignoreHostnameVerification=true
-Dweblogic.security.TrustKeyStore=CustomTrust
-Dweblogic.security.CustomTrustKeyStoreFileName=c:\keystore\trustCA.jks
-Dweblogic.security.CustomTrustKeyStoreType=jks
startMyProcess

The command-line options you use depend on the type of trust set up on WebLogic Server. In this example, WebLogic Server was set up with a Custom Trust. (Other options include the WebLogic Server Demo Trust and Java Standard Trust.)

In the preceding command line:

Our example trusts the CA certificates in a custom keystore. The command-line options you use depend on the type of trust set up on WebLogic Server. For instance:

To learn more about using SSL authentication in Java clients, see the WebLogic Server documentation:

Related Topics

Weblogic JNDI Environment Class

weblogic.Admin Command-Line Reference

How Do I: Use a JPD Proxy From a JSP?

To Create a JSP file that Calls a Business Process Using the JPD Proxy

How Do I: Use a JPD Proxy From an EJB?

You can use a JPD Proxy to invoke a business process from an EJB in the same way as you use a JPD Proxy from any Java file. To learn how, see How Do I: Use a JPD Proxy From a Java Client?

To learn about developing EJBs, see Programming WebLogic Enterprise JavaBeans.