This section uses example code to describe how to use a JPD Proxy from a Java client. It includes the following topics:
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:
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.
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) { ... } } }
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.
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:
public static final Object create(Class publicContract, String serviceUri, JpdProxy.ContextHandler ch) throws JpdProxyException
In the preceding code listing:
Listing: Example Java Client shows the getContext() method used in the Java client.
To learn more about the context handler interface, see Interface JpdProxy.ContextHandler 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/JpdProxy.ContextHandler.html
To learn more about creating an initial context, see Class Environment in the WebLogic Integration Javadoc, which is available at the following URL:
http://e-docs.bea.com/wls/docs81/javadocs/weblogic/jndi/Environment.html
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
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
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).
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:
This client accesses the business process via proxy classes found in MyProcess.jar, in the default package: weblogic.wli.jpdproxy.
To pass the digital certificates to JNDI, an array of InputStreams opened on files containing DER-encoded1 digital certificates is created. The first element in the array is a private key file; it is followed by the Java client's digital certificate file, or files2. (The digital certificate file contains the public key for the Java client.)
Note:
1If you have PEM-encoded data, you can wrap your InputStreams in PEMInputStream classes before passing them in. To do so, add the following lines of code after you create instances of the PEM-encoded key and certificates in your file:
// wrap input streams if key/cert are in pem files
key = new PEMInputStream(key);
cert = new PEMInputStream(cert);
The weblogic.security.PEMInputStream class (at http://e-docs.bea.com/wls/docs81/javadocs/weblogic/security/PEMInputStream.html) reads digital certificates stored in PEM files.
2The private key is the first input stream in the array; subsequent input streams in the array can be a single certificate (as in our example) or a chain of X.509 certificates.
You must create a new Environment object for each call to the getInitialContext() method. Once you specify a User object and security credentials, both the user and their associated credentials remain set in the Environment object.
Note: In addition to the t3 and t3s protocols, WebLogic Server clients can use the RMI over IIOP protocol. To learn about using RMI over IIOP, see Programming WebLogic RMI over IIOP in the WebLogic Server documentation at http://e-docs.bea.com/wls/docs81/rmi_iiop/index.html.
When the JNDI getInitialContext() method is called, the Java client and WebLogic Server execute mutual authentication. An exception is thrown if the digital certificates cannot be validated or if the Java client's digital certificate cannot be authenticated in the default (active) security realm. The authenticated user object is stored on the Java client's server thread and is used for checking the permissions governing the Java client's access to any protected WebLogic resources.
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: SSL Client License Requirement—Any stand-alone Java client that uses WebLogic SSL classes (weblogic.security.SSL) to invoke an Enterprise Java Bean (EJB) must use the BEA license file. When you run your client application, you must set the -Dbea.home and the -Djava.protocol.handler.pkgs system properties on the 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:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password
-Dweblogic.security.TrustKeyStore=DemoTrust
This argument is required if the server instance to which you want to connect is using the demonstration identity and certificates. If the Java Standard Trust keystore is protected by a password, include the following command-line argument:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password
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
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
How Do I: Call Business Processes?
![]() |
![]() |