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: Example Java Client 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: Example Java Client With Two-Way SSL) 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: Example Java Client is an example of a Java client that invokes a business process using a JPD Proxy. It invokes a business process named PoRequest.jpd. This example includes basic username-password authentication. A second example (Listing: Example Java Client With Two-Way SSL) describes how to add two-way SSL to the Java client.

Listing : Example 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 JPD on the server.

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

Listing : JpdProxy.create()

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

In the preceding code listing:

Note: In most cases, the public-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. To learn about generating JPD Proxies for versioned business processes, see About Versioned Business Processes.

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: JpdProxy.create(), and is used in the example code in Listing: Example Java Client.

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:

Note: The ProxyDispatcher EJB is a WebLogic Integration system stateless session bean that handles incoming requests from JPD Proxies. Its scope is the WebLogic Server domain. ProxyDispatcher is targeted to all managed servers in a cluster. Administrators can set authentication and authorization policies on this EJB using the WebLogic Server Administration Console. BEA recommends using the Java Authentication and Authorization Service (JAAS) rather than JNDI to associate a User with a security context. To learn more, see the following WebLogic Server documentation:

WebLogic JNDI at http://e-docs.bea.com/wls/docs81/jndi/jndi.html

Using JAAS Authentication in Java Clients at http://e-docs.bea.com/wls/docs81/security/fat_client.html

The JpdProxy implementation does not explicitly authenticate to the server. Instead, it relies on JNDI authentication when it looks up the ProxyDispatcherHome with the JNDI context returned by the ContextHandler.

Use the following method when you need a ContextHandler:

Listing : JpdProxy.create()

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: Example Java Client, 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:

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, which is available at the following URL:

http://e-docs.bea.com/wli/docs81/javadoc/com/bea/wli/bpm/proxy/JpdProxySession.html

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: Example Java Client.

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.

Listing : Example Java Client With Two-Way SSL

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: Example Java Client With Two-Way SSL shows a Java client that uses a JPD Proxy to invoke a business process named MyProcess.jpd.

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: Example Java Client With Two-Way SSL. 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:

Note: If the custom keystore is protected by a password, include the following: -Dweblogic.security.CustomTrustKeystorePassPhrase=password.

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 following WebLogic Server documentation:

Configuring Keystores and SSL at http://e-docs.bea.com/wls/docs81/ConsoleHelp/security_7x.html

Using SSL Authentication in Java Clients at http://e-docs.bea.com/wls/docs81/security/SSL_client.html

Related Topics

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

Using SSL Authentication in Java Clients at http://e-docs.bea.com/wls/docs81/security/SSL_client.html

Weblogic JNDI Environment Class at http://e-docs.bea.com/wls/docs81/javadocs/weblogic/jndi/Environment.html

weblogic.Admin Command-Line Reference at http://e-docs.bea.com/wls/docs81/admin_ref/cli.html

Starting Your Business Process

Interacting With Clients

How Do I: Call Business Processes?

Previous Document Next Document