Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Invoking Web Services from Client Applications and WebLogic Server

The following sections describe how to invoke Web Services, both WebLogic and non-WebLogic, from client applications and from WebLogic Server:

- Overview of Invoking Web Services
- Creating Java Client Applications to Invoke Web Services: Main Steps
- Writing an Asynchronous Client Application
- Using Web Services System Properties
- Using a Proxy Server with the WebLogic Web Services Client
- Invoking Web Services from WebLogic Server
- Writing Advanced Java Client Applications

For information about invoking a WebLogic Web Service using reliable SOAP messaging, see Using Reliable SOAP Messaging.

It is assumed in this chapter that the client applications use HTTP/S as the connection protocol when invoking a WebLogic Web Service. You can, however, configure your Web Service so that client applications can also use JMS as the transport when invoking the Web Service. For details, see Using JMS Transport to Invoke a WebLogic Web Service.

# Overview of Invoking Web Services

Invoking a Web Service refers to the actions that a client application performs to use the Web Service. Client applications that invoke Web Services can be written using any technology: Java, Microsoft SOAP Toolkit, Microsoft .NET, and so on.

Note: This chapter uses the term client application to refer to both a standalone client that uses the WebLogic thin client to invoke a Web Service hosted on both WebLogic and non-WebLogic Servers, and a client that runs inside of an EJB running on WebLogic Server.

The sections that follow describe how to use BEA's implementation of the JAX-RPC specification (Version 1.0) to invoke a Web Service from a Java client application. You can use this implementation to invoke Web Services running on any server, both WebLogic and non-WebLogic. In addition, you can create a standalone client application or one that runs as part of a WebLogic Server.

WebLogic Server provides optional runtime client JAR files that include, for your convenience when developing a standalone client application, the classes you need to invoke a Web Service. You can also use the `clientgen` Ant task to generate a Web Service-specific JAR file that contains the stubs, defined by the JAX-RPC specification, that client applications use to statically invoke a Web Service. These stubs implement JAX-RPC interfaces such as `Stub` and `Service`.

For information about troubleshooting problems when invoking a Web Service, see Troubleshooting.

## JAX-RPC API 1.0

The Java API for XML based RPC (JAX-RPC) is a Sun Microsystems specification that defines the Web Services APIs.

The following table briefly describes the core JAX-RPC interfaces and classes.

Table 7-1 JAX-RPC Interfaces and Classes

javax.xml.rpc Interface or Class | Description
--- | ---
Service | Main client interface.
ServiceFactory | Factory class for creating `Service` instances.
Stub | Base class of the client proxy used to invoke the operations of a Web Service.
Call | Used to dynamically invoke a Web Service.
JAXRPCException | Exception thrown if an error occurs while invoking a Web Service.

WebLogic Server implements the JAX-RPC 1.0 specification.

For detailed information on JAX-RPC, see http://java.sun.com/xml/jaxrpc/index.html.

For a tutorial that describes how to use JAX-RPC to invoke Web Services, see http://java.sun.com/webservices/docs/ea1/tutorial/doc/JAXRPC.html.

## The Runtime Client JAR Files

WebLogic Server provides the following runtime client JAR files for use with standalone client applications (that is, client applications that do not run in a WebLogic Server instance). These JAR files are located in the `WL_HOME``/server/lib` directory, where `WL_HOME` refers to the top-level directory of WebLogic Platform.

- `webserviceclient.jar`: Contains the client runtime implementation of JAX-RPC.
- `webserviceclient+ssl.jar`: Same as `webserviceclient.jar`, plus the runtime implementation of SSL.

Use this runtime client JAR file if you are using SSL to secure your Web Service and you want to use the WebLogic Server-provided implementation of the SSL client classes.

- `webserviceclient+ssl_pj.jar`: Same as the `webserviceclient_ssl.jar`, but for the CDC profile of J2ME.

Use this runtime client JAR file if you are writing a J2ME client that uses SSL.

Client applications that use the `webserviceclient.jar` file (or the SSL and J2ME variants) should not have `webservices.jar` or `weblogic.jar` in their CLASSPATH. All classes needed to run a client application that invokes a Web Service are typically available in `webserviceclient.jar`. If, however, there are some other classes needed by your application that are missing from `webserviceclient.jar`, but are included in `webservices.jar` or `weblogic.jar`, then put these JAR files after `webserviceclient.jar` in your CLASSPATH.

Note: For information about BEA's current licensing of client functionality, see the BEA eLicense Web Site.

## Examples of Clients That Invoke Web Services

WebLogic Server includes the following examples of creating and invoking WebLogic Web Services in the WL_HOME`/samples/server/src/examples/webservices` directory, where `WL_HOME` refers to the main WebLogic Platform directory:

- `basic.statelessSession`: Uses a stateless session EJB back-end component with built-in data types as its parameters and return value.
- `basic.javaclass`: Uses a Java class back-end component with built-in data types as its parameters and return value.
- `complex.statelessSession`: Uses a stateless session EJB back-end component with non-built-in data types as its parameters and return value.
- `handler.log`: Uses both a handler chain and a stateless session EJB.
- `handler.nocomponent`: Uses only a handler chain with no back-end component.
- `client.static`: Shows how to create a static client application that invokes a non-WebLogic Web Service.
- `client.dynamic_wsdl`: Shows how to create a dynamic client application that uses WSDL to invoke a non-WebLogic Web Service.
- `client.dynamic_no_wsdl`: Shows how to create a dynamic client application that does not use WSDL to invoke a non-WebLogic Web Service.

For detailed instructions on how to build and run the examples, open the following Web page in your browser:

>     WL_HOME/samples/server/src/examples/webservices/package-summary.html

# Creating Java Client Applications to Invoke Web Services: Main Steps

To create a Java client application that invokes a Web Service, follow these steps:

1. Generate the Web Service-specific client JAR file by running the `clientgen` Ant task.

Specify the `wsdl` attribute to create a client JAR file for a Web Service that is being hosted by either a WebLogic or a non-WebLogic server, or specify the `ear` attribute for WebLogic Web Services packaged in EAR files.

For details and examples of running the `clientgen` Ant task, see Generating the Client JAR File by Running the clientgen Ant Task. For reference information, see Web Service Ant Tasks and Command-Line Utilities.

2. Get information about the Web Service, such as its name and signature.

For details, see Getting Information About a Web Service.

3. Write the Java client application code that includes the invoke of the Web Service.

See Writing the Java Client Application to Invoke a Web Service for an example of writing a simple client application.

4. Compile and run your Java client application.

If you are creating a standalone client application, ensure that the `webserviceclient.jar` runtime Java client JAR file provided by WebLogic Server is in your CLASSPATH. For details, see The Runtime Client JAR Files.

If your client application is running on WebLogic Server, you do not need this runtime client JAR file.

## Generating the Client JAR File by Running the clientgen Ant Task

The Web Service-specific JAR file contains the stubs, such as implementation of the `Stub` and `Service` interfaces, which are defined by the JAX-RPC specification and are used by client applications to invoke a Web Service (either WebLogic or non-WebLogic). Almost all the code you need is automatically generated for you.

Note: For information about BEA's current licensing of client functionality, see the BEA eLicense Web Site.

To run the `clientgen` Ant task and automatically generate the Web Service-specific client JAR file:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a file called `build.xml` that contains a call to the `clientgen` Ant task. For details, see the example later in this section.
3. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the same directory as the`build.xml` file:

>     prompt> ant

For reference information about the `clientgen` Ant task, see clientgen.

The following example shows a simple `build.xml` file.

Listing 7-1 Sample build.xml File for the clientgen Ant Task

>     <project name="buildWebservice" default="generate-client">
>        <target name="generate-client">
>          <clientgen wsdl="http://example.com/myapp/myservice?WSDL"
>                     packageName="myapp.myservice.client"
>                     clientJar="myapps/myService_client.jar"
>     />

>        </target>
>     </project>

When you run the `clientgen` Ant task using the preceding `build.xml` file, the Ant task creates a client JAR file (called `myapps/myService_client.jar`) that the client application will use to invoke the Web Service described by the `http://example.com/myapp/myservice?WSDL` WSDL. It packages the interface and stub files in the `myapp.myservice.client` package.

## Getting Information About a Web Service

You need to know the name of the Web Service and the signature of its operations before you write your client code. There are a variety of ways to find this information.

If you are invoking a WebLogic Web Service, you can use its Home Page to get the full signature of each operation. For details, see Using the Web Service Home Page to Test Your Web Service.

Another way to get the signature of a Web Service operation is to use the `clientgen` Ant task to generate the Web Service-specific client JAR file, un-JAR the file, and look at the generated `*.java` files. Typically, the file `ServiceName` `Port.java` contains the interface definition of your Web Service, where `ServiceName` refers to the name of the Web Service. For example, look at the `TraderServicePort.java` file for the signature of the `buy` and `sell` operations.

Finally, you can examine the actual WSDL of the Web Service. The name of the Web Service is contained in the `<service>` element, as shown in the following excerpt of the `TraderService` WSDL:

>       <service name="TraderService">
>         <port name="TraderServicePort"
>              binding="tns:TraderServiceSoapBinding">
>       ...
>         </port>
>       </service>

The operations defined for this Web Service are listed under the corresponding `<binding>` element. For example, the following WSDL excerpt shows that the `TraderService` Web Service has two operations, `buy` and `sell` (for clarity, only relevant parts of the WSDL are shown):

>       <binding name="TraderServiceSoapBinding" ...>
>         ...
>         <operation name="sell">
>         ...
>         </operation>
>         <operation name="buy">
>         </operation>
>       </binding>

## Writing the Java Client Application to Invoke a Web Service

The following sections describe how to write Java client applications to invoke a Web Service. The example uses the JAX-RPC API and assumes that you have the necessary BEA-provided JAR files in your CLASSPATH.

### Writing a Simple Client Application

You use a strongly-typed Java interface when you use a static client application to invoke a Web Service. The Web Services-specific JAR file includes the following classes and interfaces:

- Implementation of the JAX-RPC `Service` interface for the Web Service you are invoking.
- An implementation of the `Stub` interface for each SOAP port in the WSDL.
- Serialization class for non-built-in data types and their Java representations.

The following code shows an example of writing a client application that invokes the sample `TraderService` Web Service; in the example, `TraderService` is the stub factory and `TraderServicePort` is the stub itself:

>     package examples.webservices.complex.statelessSession;

>     public class Client {

>       public static void main(String[] args) throws Exception {

>         // Setup the global JAXM message factory
>         System.setProperty("javax.xml.soap.MessageFactory",
>           "weblogic.webservice.core.soap.MessageFactoryImpl");
>         // Setup the global JAX-RPC service factory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>           "weblogic.webservice.core.rpc.ServiceFactoryImpl");

>         // Parse the argument list
>         Client client = new Client();
>         String wsdl = (args.length > 0? args[0] : null);
>         client.example(wsdl);
>       }

>       public void example(String wsdlURI) throws Exception {

>         TraderServicePort trader = null;
>         if (wsdlURI == null) {
>           trader = new TraderService_Impl().getTraderServicePort();
>         } else {
>           trader = new TraderService_Impl(wsdlURI).getTraderServicePort();
>         }
>         String [] stocks = {"BEAS", "MSFT", "AMZN", "HWP" };

>           // execute some buys
>         for (int i=0; i<stocks.length; i++) {
>           int shares = (i+1) * 100;
>           log("Buying "+shares+" shares of "+stocks[i]+".");
>           TradeResult result = trader.buy(stocks[i], shares);
>           log("Result traded "+result.getNumberTraded()
>               +" shares of "+result.getStockSymbol());
>         }
>         // execute some sells
>         for (int i=0; i<stocks.length; i++) {
>           int shares = (i+1) * 100;
>           log("Selling "+shares+" shares of "+stocks[i]+".");
>           TradeResult result = trader.sell(stocks[i], shares);
>           log("Result traded "+result.getNumberTraded()
>               +" shares of "+result.getStockSymbol());

>         }

>       }

>       private static void log(String s) {
>         System.out.println(s);
>       }

>     }

In the preceding example:

- The following code shows how to create a `TraderServicePort` stub:

>         trader = new TraderService_Impl(wsdlURI).getTraderServicePort();

The `TraderService_Impl` stub factory implements the JAX-RPC `Service` interface. The constructor of `TraderService_Impl` creates a stub based on the provided WSDL URI. The `getTraderServicePort()` method is used to return an instance of the `TraderService` stub implementation.

- The following code shows how to invoke the `buy` operation of the `TraderService` Web Service:

>      TradeResult result = trader.buy(stocks[i], shares);

The `trader` Web Service has two operations: `buy()` and `sell()`. Both operations return a non-built-in data type called `TradeResult`.

### Writing a Client That Uses Out or In-Out Parameters

Web Services can use out or in-out parameters as a way of returning multiple values. For more information on out and in-out parameters, see Implementing Multiple Return Values.

When you write a client application that invokes a Web Service that uses out or in-out parameters, the data type of the out or in-out parameter must implement the `javax.xml.rpc.holders.Holder` interface. After the client application invokes the Web Service, the client can query the out or in-out parameters in the `Holder` object and treat them as if they were standard return values.

For example, the Web Service described by the following WSDL has an operation called `echoStructAsSimpleTypes()` that takes one standard input parameter and three out parameters:

>     http://soap.4s4c.com/ilab/soap.asp?WSDL

The following client application shows one way to invoke the `echoStructAsSimpleTypes()` Web Service operation.

>     package websvc;

>     public class Main {

>       public static void main(String[] args) throws Exception {
>         // Setup the global JAX-RPC service factory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>           "weblogic.webservice.core.rpc.ServiceFactoryImpl");

>         InteropLab_Impl test = new InteropLab_Impl();
>         InteropTest2PortType soap = test.getinteropTest2PortType();

>         org.tempuri.x4s4c.x1.x3.wsdl.types.SOAPStruct inputStruct =
>           new org.tempuri.x4s4c.x1.x3.wsdl.types.SOAPStruct();

>         inputStruct.setVarInt(10);
>         inputStruct.setVarFloat(10.1f);
>         inputStruct.setVarString("hi there");

>         javax.xml.rpc.holders.StringHolder outputString =
>           new javax.xml.rpc.holders.StringHolder();
>         javax.xml.rpc.holders.IntHolder outputInteger =
>           new javax.xml.rpc.holders.IntHolder();
>         javax.xml.rpc.holders.FloatHolder outputFloat =
>           new javax.xml.rpc.holders.FloatHolder();

>         soap.echoStructAsSimpleTypes(inputStruct, outputString, outputInteger,
>                                      outputFloat);

>         System.out.println("This example shows how to create a static client
>                             application that invokes a non-WebLogic Web Service.");
>         System.out.println("The webservice used was:
>                          http://soap.4s4c.com/ilab/soap.asp?WSDL");
>         System.out.println("This webservice shows how to invoke an operation that
>                            uses out parameters.  The set parameters are below:");
>         System.out.println("outputString.value: " + outputString.value);
>         System.out.println("outputInteger.value: " + outputInteger.value);
>         System.out.println("outputFloat.value: " + outputFloat.value);
>       }

>     }

# Writing an Asynchronous Client Application

This section describes how to invoke an operation asynchronously. In this context, asynchronously means you invoke an operation and then optionally get the results of the invoke in a later step.

Warning: This section applies only to static client application that use the Web Service-specific client JAR files generated by the `clientgen` Ant task. You cannot use the procedure specified in this section in dynamic proxy and DII-based client applications.

To write an asynchronous client, follow these steps:

1. Generate the Web Service-specific client JAR file by running the `clientgen` Ant task. Be sure to specify the `generateAsyncMethods="True"` attribute, as shown in the following example:

>     <clientgen
>        wsdl="http://www.mssoapinterop.org/asmx/simple.asmx?WSDL"
>        clientJar="echoservice.jar"
>        packageName="examples.async"
>        generateAsyncMethods="true" />

The `clientgen` Ant task generates special asynchronous methods in the JAX-RPC stubs to invoke the operations of the Web Service. See Description of the Generated Asynchronous Web Service Client Stub for more details.

For general details and examples of running the `clientgen` Ant task, see Generating the Client JAR File by Running the clientgen Ant Task. For reference information, see Web Service Ant Tasks and Command-Line Utilities.

2. Write the Java code using the special asynchronous methods. For examples, see Writing the Asynchronous Client Java Code.
3. Compile and run your asynchronous Java client application.

If you are creating a standalone asynchronous client application, ensure that the `webserviceclient.jar` runtime Java client JAR file provided by WebLogic Server is in your CLASSPATH. If your client application is running on WebLogic Server (for example, as part of the reliable SOAP messaging framework), you can omit this step.

For detail about the `webserviceclient.jar` file, as well as the other available runtime client JAR files, see The Runtime Client JAR Files.

For detailed API reference information about writing asynchronous client applications, see the weblogic.webservice.async Javadoc.

## Description of the Generated Asynchronous Web Service Client Stub

When you specify `generateAsyncMethods="True"` when executing the `clientgen` Ant task, the task creates two special methods in the generated JAX-RPC stub to invoke each Web Service operation asynchronously, in addition to the standard methods. The special methods take the following form:

>     FutureResult startMethod (params, AsyncInfo asyncInfo);
>     result endMethod (FutureResult futureResult);

where:

- `Method` is the name of the synchronous method used to invoke the Web Service operation.
- `params` is the list of parameters of the operation.
- `result` is the result of the operation.
- `FutureResult` is a WebLogic object used as a placeholder for the impending result.
- `AsyncInfo` is a WebLogic object used to pass additional information to WebLogic Server.

Note: If the operations of the Web Service are document-oriented (rather than RPC-oriented), the `clientgen` Ant task also generates the following `end()` method, in addition to the methods listed above:

>     result endConvenienceMethod (FutureResult futureResult);

If you use convenience methods when invoking document-oriented Web Service operations, then use this flavor of the `end()` method when invoking the operation asynchronously.

For example, assume the standard generated stub contains the following method to invoke a Web Service operation called `echoString`:

>     String echoString (String str);

The `clientgen` task generates the following additional asynchronous methods in the generated stub:

>     FutureResult startEchoString (String str, AsyncInfo asyncInfo);
>     String endEchoString (FutureResult futureResult);

For detailed API reference information about the `FutureResult` interface and the `AsyncInfo` class, see the weblogic.webservice.async Javadoc.

## Writing the Asynchronous Client Java Code

When you write a Java client application that asynchronously invokes a Web Service operation, you must first import the following classes:

>     import weblogic.webservice.async.FutureResult;
>     import weblogic.webservice.async.AsyncInfo;
>     import weblogic.webservice.async.ResultListener;
>     import weblogic.webservice.async.InvokeCompletedEvent;

There are two steps involved in invoking an asynchronous operation: the first starts the invocation and the second optionally retrieves the results of the completed operation.

Assume that your client application uses the following Java code to get an instance of the `SimpleTest` stub implementation:

>         SimpleTest echoService = new SimpleTest_Impl();
>         SimpleTestSoap echoPort = echoService.getSimpleTestSoap();

Further assume that you want to invoke the `echoString` operation of the Web Service. The following paragraphs show a variety of ways you can invoke this operation asynchronously.

The simplest way is to simply execute the `startEchoString()` client method, do some other task, then execute the `endEchoString()` client method:

>           FutureResult futureResult = echoPort.startEchoString( "94501", null );
>           // do something
>           String result = echoPort.endEchoString( futureResult );

The `end` `Method``()` method, in this case `endEchoString()`, blocks until the result is ready.

You can also use the `FutureResult.isCompleted()` method to test whether the results have returned from the Web Service, as shown in the following excerpt:

>           FutureResult futureResult = echoPort.startEchoString( "94501", null );

>           while( !futureResult.isCompleted() ){
>             // do something ;
>           }

>           String result = echoPort.endEchoString( futureResult );

Alternatively, you can use the `ResultListener` and `InvokeCompletedEvent` classes to set up a listener in your client application that listens for a callback indicating that the results of the operation have returned, as shown in the following excerpt:

>           AsyncInfo asyncInfo = new AsyncInfo();

>           asyncInfo.setResultListener( new ResultListener(){
>             public void onCompletion( InvokeCompletedEvent event ){

>               SimpleTestSoap source = (SimpleTestSoap)event.getSource();

>               try{
>                 String result = source.endEchoString ( event.getFutureResult() );
>                } catch ( RemoteException e ){
>                 e.printStackTrace ( System.out );
>               }
>             }
>           });

>           echoPort.startEchoString( "94501", asyncInfo );

# Using Web Services System Properties

The following two tables list the WebLogic and standard JDK 1.4 system properties you can set in client applications that invoke Web Services. Use the System.setProperty() method to set the properties.

Table 7-2 WebLogic Web Services System Properties

WebLogic Web Services System Property | Description | Data Type
--- | --- | ---
weblogic.webservice.transport.http.full-url | Specifies that the full URL, rather than the relative URL, of the Web Service that the client application is invoking be specified in the `Request-URI` field of HTTP request. Valid values are `True` and `False`. Default value is `False`. | Boolean.
weblogic.webservice.transport.https.proxy.host | If you use a proxy server to make HTTPS (HTTP over SSL) connections, use this system property to specify the host name of the proxy server in your client applications. | String.
weblogic.webservice.transport.https.proxy.port | If you use a proxy server to make HTTPS (HTTP over SSL) connections, use this system property to specify the port of the proxy server in your client applications. | String.
weblogic.webservice.verbose | Enables verbose mode during Web Service invocation The SOAP request and response messages are printed to the standard out of the client. Valid values are `True` and `False`. Default value is `False`. For details, see Viewing SOAP Messages. | Boolean
weblogic.webservice.client.ssl.strictcertchecking | Enables or disables strict certificate validation when using the WebLogic-provided implementation of SSL. Set to `True` to enable strict certificate validation, and `False` to disable. Default value is `True`. For an example, see Using the WebLogic Server-Provided SSL Implementation. | Boolean
weblogic.webservice.client.ssl.trustedcertfile | The name of the file (located on the client application computer) that contains the certificates of CA (certificate authority). The CAs are trusted to issue WebLogic Server certificates. The file can also contain certificates that you trust directly. | String
weblogic.webservice.client.ssl.adapterclass | Fully qualified name of an adapter class you have implemented to use a third-party SSL implementation. For an example, see Using a Third-Party SSL Implementation. | String.
weblogic.webservice.security.clock.precision | Describes the accuracy of synchronization between the clock of the client application invoking a WebLogic Web Service and WebLogic Server's clock. The client application uses this value to account for a reasonable level of clock skew between two clocks. The value is expressed in milliseconds. This means, for example, that if the clocks are accurate within a one minute of each other, the value of this element is 60000. If the value of this element is greater than the expiration period of the SOAP response, the client application rejects the request because it cannot accurately enforce the expiration. For example, if the clock precision value is 60000 milliseconds, and the client application receives a SOAP response that expires 30000 milliseconds after its creation time, it is possible that the message has lived for longer than 30000 seconds, due to the 60000 millisecond clock precision discrepancy, so the client application has no option but to reject the message. You can relax this strict enforcement by setting the `weblogic.webservice.security.clock.precision.lax` property to `false`. This property must be specified in conjunction with `weblogic.webservice.security.clock.synchronized`. The default value for this property is 60000. | Integer.
weblogic.webservice.security.clock.precision.lax | Specifies whether to enforce the clock precision time period. If this element is set to `true`, the client application does not reject SOAP responses whose time expiration period is smaller than the clock precision time, specified with the `weblogic.webservice.security.clock.precision` property. By default, the client application rejects these SOAP responses because it cannot accurately determine whether the message has expired, due to the discrepancy in clock precision between the client application and WebLogic Server. Valid values for this property are `true` and `false`. The default value is `false`. | Boolean.
weblogic.webservice.security.clock.synchronized | Specifies whether the client application assumes that the clocks of the client application invoking a WebLogic Web Service and WebLogic Server are synchronized when dealing with timestamps in SOAP messages. If the value of this property is `true`, the client application enforces, if it exists, the time expiration of the SOAP response from WebLogic Server. If the value of this element is `false`, the client application rejects all SOAP responses that contain a time expiration. Valid values for this property are `true` and `false`. The default value is `false`. | Boolean.
weblogic.webservice.security.delay.max | Specifies, in milliseconds, the client application's expiration period for a SOAP response from WebLogic Server. The client application adds the value of this property to the creation date in the time stamp of the SOAP response, accounts for clock precision, then compares the result to the current time. If the result is greater than the current time, the client application rejects the response. In addition to its own expiration period for SOAP responses, the client application also honors expirations in the SOAP response message itself, specified by WebLogic Server To specify no expiration, set this property to `-1`. The default value of this property is `-1`. If you set this property to a value, be sure you also specify that the clocks between WebLogic Server and client applications are synchronized by setting the `weblogic.webservice.security.clock.synchronized` property to `true`. | Integer.
weblogic.webservice.security.timestamp.include | Specifies whether the client application includes a timestamp in the SOAP request to a WebLogic Web Service operation. Valid values for this property are `true` and `false`. The default value is `true`. | Boolean
weblogic.webservice.security.timestamp.require | Specifies whether the client application requires that the SOAP response from WebLogic Server include a timestamp. If this element is set to `true`, and a SOAP response does not contain a timestamp, the client application rejects the request. Valid values for this property are `true` and `false`. The default value is `true`. | Boolean.
weblogic.webservice.security.validity | Specifies, in milliseconds, the expiration period that the client application adds to the timestamp header of the SOAP request. To specify no expiration, set this property to `-1`. The default value of this property is `-1`. | Integer.

The following table lists the standard JDK 1.4 system properties you can set in your client applications.

For additional information about these properties, see Sun's Network Properties.

Table 7-3 Standard JDK 1.4 System Properties

Standard JDK 1.4 System Property | Description
--- | ---
http.proxyHost | If you use a proxy server to make HTTP connections, specifies the host name of the proxy server in your client applications.
http.proxyPort | If you use a proxy server to make HTTP connections, specifies the port of the proxy server in your client applications.
http.nonProxyHosts | If you use a proxy server to make HTTP connections, specifies the hosts which should be connected to directly and not through the proxy server.
networkaddress.cache.ttl | Used in `java.security` to specify the caching policy for successful name lookups from the name service. The value is specified as an integer to indicate the number of seconds to cache the successful lookup.
networkaddress.cache.negative.ttl | Used in `java.security` to specify the caching policy for unsuccessful name lookups from the name service. The value is specified as an integer to indicate the number of seconds to cache the failure for unsuccessful lookups.
http.agent | Specifies the `User-Agent` request header sent in HTTP requests.
http.auth.digest.validateServer | Modifies the behavior of the HTTP digest authentication mechanism. When set to True, this system property forces the server to authenticate itself to the client application.
http.auth.digest.validateProxy | Modifies the behavior of the HTTP digest authentication mechanism. When set to True, this system property forces the proxy server to authenticate itself to the client application.
http.auth.digest.cnonceRepeat | Modifies the behavior of the HTTP digest authentication mechanism by specifying how many times a `cnonce` value is reused.
http.keepAlive | Specifies whether keep alive, or persistent, connections are supported.
http.maxConnections | Specifies the number of idle connections that will be simultaneously kept alive, per destination. This system property should be used together with `http.keepAlive`.
https.sharedsocket | Enables socket sharing in an SSL client application that connects to a WebLogic Web Service using the WebLogic SSL implementation. Valid values are `True` and `False`. Default value is `False`. For details, see Using SSL Socket Sharing When Using the WebLogic SSL Implementation.
https.sharedsocket.timeout | Specifies the timeout value, in seconds, for shared sockets. Default value is 15 seconds. For details, see Using SSL Socket Sharing When Using the WebLogic SSL Implementation.

# Invoking Web Services from WebLogic Server

Invoking a Web Service from a component deployed on WebLogic Server, such as from an EJB or a servlet, is essentially the same as invoking a Web Service from a standalone client. You write the same code as shown in the examples in this chapter and you generate a Web Service-specific client JAR file using `clientgen` in the same way. The main differences are:

- You do not need the runtime client JAR files, because all the needed classes are already included in the WebLogic Server runtime.
- You must add the Web Service-specific client JAR file to the appropriate directory of the deployed component.
- If you are invoking a Web Service deployed on WebLogic Server Version 8.1 from a Version 7.0 instance of WebLogic Server, and it is necessary for the Version 7.0 WebLogic Server instance to use a Web Service-specific client JAR file generated from the `clientgen` Ant task included in Version 8.1 of WebLogic Server, then you must use portable stubs. For details, see Creating and Using Portable Stubs.

The following table summarizes the location of the various client JAR files depending on the type of client application from which you are invoking the Web Service.

Table 7-4 Location of Client JAR Files For Various Client Applications

Type of Client Application | Location of Runtime Client JAR Files | Location of Web Service-Specific Client JAR File
--- | --- | ---
Standalone | Client's CLASSPATH. | Client's CLASSPATH
EJB | Not needed, because the runtime client classes are part of the WebLogic Server runtime. | EJB JAR file.
Servlet or Java class | Not needed, because the runtime client classes are part of the WebLogic Server runtime. | `WEB-INF/lib` directory of the WAR file.

## Creating and Using Portable Stubs

If you use the Web Services client JAR files (both the ones distributed with the product and the Web Service-specific one generated by the `clientgen` Ant task) as part of an application that runs in WebLogic Server, you might find that the Java classes in the JAR file collide with the classes of WebLogic Server itself. This happens when the WebLogic Server instance in which the client JAR file is deployed is a different version from that which the client JAR file was generated. To solve this problem, use portable stubs.

Note: Always try to use the `clientgen` Ant task of the WebLogic Server instance that is invoking the Web service to create the Web Service-specific client JAR file rather than that of the WebLogic Server that is hosting the Web Service. If this is not possible, then use portable stubs.

You need to use portable stubs only if your client application is deployed and running on WebLogic Server, not if your client application is standalone.

To enable your client application to use portable stubs:

1. Use the WebLogic Server release-specific client JAR file called `wsclient81.jar` (distributed with WebLogic Server in the `WL_HOME``/server/lib` directory) with your client application rather than the generic `webserviceclient.jar` client JAR file. The `wsclient81.jar` file contains the same class files as the standard client JAR file, but they are renamed `weblogic81.*`. Because these class files are version-specific, they will not collide with any `weblogic.*` WebLogic Server classes.
2. Run the Web-service specific client JAR file you generated with the `clientgen` Ant task, as well as any supporting client JAR files, through the `VersionMaker` utility. This utility makes the following changes to the classes in these client JAR files:

- Renames all `weblogic.*` classes as `weblogic81.*`
- All references to `weblogic.*` classes are changed to reference `weblogic81.*` instead.

Use these new version-specific client JAR files with your client application.

For details on using `VersionMaker`, see Using the VersionMaker Utility to Update Client JAR Files.

## Using the VersionMaker Utility to Update Client JAR Files

Follow these steps to update your client JAR files to use version-specific WebLogic Server classes:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Execute the Java utility `weblogic.webservice.tools.versioning.VersionMaker`, passing it the following parameters:

- `destination_dir`: the destination directory that will contain the new version-specific client JAR files.
- `client_jar_file`: the client JAR file, generated by the `clientgen` Ant task, whose class files are named `weblogic.*` and will be renamed `weblogic81.*`.
- `other_jar_files`: supporting JAR files

For example:

>     java weblogic.webservice.tools.versioning.VersionMaker \
>        new_directory myclient.jar supporting.jar

In the example, the `weblogic.*` classes in the `myclient.jar` and `supporting.jar` client JAR files are renamed `weblogic81.*`, and all references to these classes updated accordingly. The new client JAR files are generated into the directory called `new_directory` under the current directory.

# Using a Proxy Server with the WebLogic Web Services Client

You can use a proxy server to proxy requests from a WebLogic Web Services client application to a server (either WebLogic or non-WebLogic) that is hosting a Web Service. However, be sure to set all the following system properties in your client application:

- `http.proxyHost`
- `http.proxyPort`
- `weblogic.webservice.transport.http.proxy.host`
- `weblogic.webservice.transport.http.proxy.port`

Note: If you are using HTTPS as the transport when invoking the Web Service, replace the `http` in the preceding properties with `https`. For example, use `https.proxyHost` instead of `http.proxyHost`.

For more information on these, and other, WebLogic system properties you can set in your client application, see Using Web Services System Properties.

Additionally, if you have set up your proxy server to use proxy authentication, then you must also set the property `weblogic.net.proxyAuthenticatorClassName` in your client application to the name of the Java class that implements the `weblogic.common.ProxyAuthentication` interface, as shown in the following excerpt from a client application:

>         System.setProperty("weblogic.net.proxyAuthenticatorClassName", "my.ProxyAuthenticator");

In the example, `my.ProxyAuthenticator` is a class in the client application's CLASSPATH that implements the `weblogic.common.ProxyAuthentication` interface.

The `weblogic.common.ProxyAuthentication` interface allows a client application to provide user authentication information required when tunneling WebLogic HTTP and SSL protocols through a proxy server that requires user authentication. For details on implementing this interface, see the `weblogic.common.ProxyAuthentication` Javadocs`.`

# Writing Advanced Java Client Applications

The following sections contain examples of how to write advanced client applications:

- Writing a Dynamic Client That Uses WSDL
- Writing a Dynamic Client That Does Not Use WSDL
- Writing a Dynamic Client That Uses Non-Built-In Data Types
- Writing a J2ME Client

## Writing a Dynamic Client That Uses WSDL

Assume you want to create a dynamic client application that uses built-in data types and WSDL to invoke the Web Service found at the following URL:

http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl

Follow these steps when writing the Java code:

1. Create a service factory using the `ServiceFactory.newInstance()` method.
2. Create a `Service` object from the factory and pass it the WSDL and the name of the Web Service you are going to invoke.
3. Create a `Call` object from the `Service`, passing it the name of the port and the operation you want to execute
4. Use the `Call.invoke()` method to actually invoke the Web Service operation.

Note: If the Web Service you are invoking from your dynamic client application uses non-built-in data types, see Writing a Dynamic Client That Uses Non-Built-In Data Types.

The following Java code shows an example of writing a dynamic client application:

>     import java.net.URL;

>     import javax.xml.rpc.ServiceFactory;
>     import javax.xml.rpc.Service;
>     import javax.xml.rpc.Call;
>     import javax.xml.rpc.ParameterMode;

>     import javax.xml.namespace.QName;

>     public class Main {

>       public static void main(String[] args) throws Exception {

>         // Setup the global SAAJ message factory
>         System.setProperty("javax.xml.soap.MessageFactory",
>           "weblogic.webservice.core.soap.MessageFactoryImpl");
>         // Setup the global JAX-RPC service factory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>           "weblogic.webservice.core.rpc.ServiceFactoryImpl");

>         // create service factory
>         ServiceFactory factory = ServiceFactory.newInstance();

>         // define qnames
>         String targetNamespace =
>           "http://www.themindelectric.com/"
>           + "wsdl/net.xmethods.services.stockquote.StockQuote/";

>         QName serviceName =
>           new QName(targetNamespace,
>                     "net.xmethods.services.stockquote.StockQuoteService");

>         QName portName =
>           new QName(targetNamespace,
>                     "net.xmethods.services.stockquote.StockQuotePort");

>         QName operationName = new QName("urn:xmethods-delayed-quotes",
>                                         "getQuote");

>         URL wsdlLocation =
>           new URL("http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl");

>         // create service
>         Service service = factory.createService(wsdlLocation, serviceName);

>         // create call
>         Call call = service.createCall(portName, operationName);

>         // invoke the remote web service
>         Float result = (Float) call.invoke(new Object[] {
>           "BEAS"
>         });

>         System.out.println("\n");
>         System.out.println("This example shows how to create a dynamic client
>                            application that invokes a non-WebLogic Web Service.");
>         System.out.println("The webservice used was:
>                             http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl");
>         System.out.println("The quote for BEAS is: ");
>         System.out.println(result);
>       }

>     }

Note: When you use the javax.xml.rpc.Call API to create a dynamic client that uses WSDL, you cannot use the following methods in your client application:

- `getParameterTypeByName()`
- `getReturnType()`

Additionally, if you want to execute the `getTargetEndpointAddress()` method, you must have previously executed the `setTargetEndpointAddress()` method, even if the targetEndPointAddress is available in the WSDL.

## Writing a Dynamic Client That Does Not Use WSDL

Dynamic clients that do not use WSDL are similar to those that use WSDL except that when the client does not use WSDL, you have to explicitly set information that would be found in the WSDL, such as the parameters to the operation, the target endpoint address, and so on.

The following example shows how to create a client application that invokes a Web Service without specifying the WSDL in the client application:

>     import javax.xml.rpc.ServiceFactory;
>     import javax.xml.rpc.Service;
>     import javax.xml.rpc.Call;
>     import javax.xml.rpc.ParameterMode;

>     import javax.xml.namespace.QName;

>     public class Main {

>       public static void main(String[] args) throws Exception {
>         // Setup the global JAX-RPC service factory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>           "weblogic.webservice.core.rpc.ServiceFactoryImpl");

>         // create service factory
>         ServiceFactory factory = ServiceFactory.newInstance();

>         // define qnames
>         String targetNamespace =
>           "http://www.themindelectric.com/"
>           + "wsdl/net.xmethods.services.stockquote.StockQuote/";

>         QName serviceName =
>           new QName(targetNamespace,
>                     "net.xmethods.services.stockquote.StockQuoteService");

>         QName portName =
>           new QName(targetNamespace,
>                     "net.xmethods.services.stockquote.StockQuotePort");

>         QName operationName = new QName("urn:xmethods-delayed-quotes",
>                                         "getQuote");

>         // create service
>         Service service = factory.createService(serviceName);

>         // create call
>         Call call = service.createCall();

>         // set port and operation name
>         call.setPortTypeName(portName);
>         call.setOperationName(operationName);
>         // add parameters
>         call.addParameter("symbol",
>                           new QName("http://www.w3.org/2001/XMLSchema", "string"),
>                           ParameterMode.IN);

>         call.setReturnType(new QName( "http://www.w3.org/2001/XMLSchema","float") );

>         // set end point address
>         call.setTargetEndpointAddress("http://www.xmethods.com:9090/soap");

>         // invoke the remote web service
>         Float result = (Float) call.invoke(new Object[] {
>           "BEAS"
>         });

>         System.out.println("\n");
>         System.out.println("This example shows how to create a dynamic client
>                             application that invokes a non-WebLogic Web Service.");
>         System.out.println("The webservice used was:
>      http://www.themindelectric.com/wsdl/net.xmethods.services.stockquote.StockQuote");
>         System.out.println("The quote for BEAS is:");
>         System.out.println(result);
>       }

>     }

Note: In dynamic clients that do not use WSDL, the `getPorts()` method always returns `null`. This behavior is different from dynamic clients that do use WSDL in which the method actually returns the ports.

## Writing a Dynamic Client That Uses Non-Built-In Data Types

When you write a dynamic client to invoke a Web Service that uses non-built-in data types as parameters or return type, you must do the following:

- Code the serialization class that converts the non-built-in data type between its Java and XML Schema representations. To create the serialization class, use the `autotype` Ant task (see autotype) or create one manually (see Writing the Serialization Class.)
- In your client application code, use the JAX-RPC `TypeMappingRegistry` of the `ServiceFactory` to register the serialization classes.

For detailed information about the `TypeMappingRegistry`, see the JAX-RPC 1.0 specification.

Note: Because the `clientgen` Ant task automatically generates all needed serialization classes and creates stubs that correctly use the serialization classes, BEA recommends that you use a static client application when using non-built-in data types.

The following example shows how to use the `TypeMappingRegistry` to register the serialization class called `SOAPStructCode` in your client application; the relevant code is in bold.

>     import javax.xml.soap.SOAPConstants;
>     import javax.xml.rpc.ServiceFactory;
>     import javax.xml.rpc.Service;
>     import javax.xml.rpc.Call;
>     import javax.xml.rpc.ParameterMode;

>     import javax.xml.namespace.QName;

>     import javax.xml.rpc.encoding.TypeMapping;
>     import javax.xml.rpc.encoding.TypeMappingRegistry;

>     import org.soapinterop.xsd.SOAPStructCodec;
>     import org.soapinterop.xsd.SOAPStruct;

>     public class MSInterop{

>       public static void main( String[] args ) throws Exception{

>         //set weblogic ServiceFactory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>             "weblogic.webservice.core.rpc.ServiceFactoryImpl" );

>         //create service factory
>         ServiceFactory factory = ServiceFactory.newInstance();

>         //define qnames
>         String targetNamespace = "http://soapinterop.org/";

>         QName serviceName = new QName( targetNamespace, "SimpleTest" );
>         QName portName = new QName( targetNamespace, "SimpleTestSoap" );

>         QName operationName = new QName( "http://soapinterop.org/",
>             "echoStruct" );

>         //create service
>         Service service = factory.createService( serviceName );

>         TypeMappingRegistry registry = service.getTypeMappingRegistry();

>         TypeMapping mapping = registry.getTypeMapping(
>             SOAPConstants.URI_NS_SOAP_ENCODING );

>         mapping.register( SOAPStruct.class,
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ),
>             new SOAPStructCodec(),
>             new SOAPStructCodec() );

>         //create call
>         Call call = service.createCall();

>         //set port and operation name
>         call.setPortTypeName( portName );
>         call.setOperationName( operationName );

>         call.addParameter( "inputStruct",
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ),
>             ParameterMode.IN);

>         call.setReturnType(
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ) );

>         //set end point address
>         call.setTargetEndpointAddress(
>             "http://www.mssoapinterop.org/asmx/simple.asmx" );

>         SOAPStruct s = new SOAPStruct();
>         s.setVarInt(2);
>         s.setVarString("foo");
>         s.setVarFloat(123123);
>         System.out.println(s.toString());

>         SOAPStruct res = (SOAPStruct) call.invoke(new Object[]{s} );

>         System.out.println( res );
>       }
>     }

## Writing a J2ME Client

You can create a Java 2 Platform, Micro Edition (J2ME) Web Service-specific client JAR file to use with client applications that run on J2ME.

Note: BEA supports the CDC and Foundation profile J2ME environment.

Creating a J2ME client application that invokes a Web Service is similar to creating a non-J2ME client. For example, you use the same runtime client JAR file as non-J2ME client applications (`WL_HOME``/server/lib/webserviceclient.jar`.)

To write a J2ME client application, follow the steps described in Creating Java Client Applications to Invoke Web Services: Main Steps but with the following changes:

- When you run the `clientgen` Ant task to generate the Web Service-specific client JAR file, be sure you specify the `j2me="True"` attribute, as shown in the following example:

>     <clientgen wsdl="http://example.com/myapp/myservice.wsdl"
>                packageName="myapp.myservice.client"
>                clientJar="myapps/myService_clients.jar"
>                j2me="True"
>     />

Note: The J2ME Web Service-specific client JAR file generated by `clientgen` is not compliant with the JAX-RPC specification in the following ways:

- The methods of the generated stubs do not throw `java.rmi.RemoteException`.
- The generated stubs do not extend `java.rmi.Remote`.

- When you write, compile, and run your Java client application, be sure you use the J2ME virtual machine and APIs.

For more information about J2ME, see http://java.sun.com/j2me/.

## Writing a J2ME Client That Uses SSL

WebLogic Server includes support for creating J2ME client applications that use SSL. If you are writing a J2ME client that uses SSL, follow these guidelines in addition to the guidelines specified in Writing a J2ME Client.

- You must use the following additional class and package:

- `java.math.BigInteger` (class)
- `java.util.*` (entire package)

- Ensure that the file `WL_HOME``/server/lib/webserviceclient+ssl_pj.jar` is in your CLASSPATH.

Warning: Do not include the `weblogic.jar` file in your CLASSPATH.

- If your client application uses the WSDL file to invoke a Web Service, you must use a local copy of the WSDL file stored on your client computer; you cannot access the WSDL file using a `URLConnection` object.