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:

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.

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

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, 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 endMethod() 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.

System Property

Description

Data Type

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. Boolean.
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. Integer.
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 False.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 ServerTo 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.

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.
sun.net.client.defaultConnectTimeout Specifies the time-out (in milliseconds) for the protocol handler used by java.net.URLConnection while establishing the connection to the host.
sun.net.client.defaultReadTimeout Specifies the time-out (in milliseconds) for the protocol handler used by java.net.URLConnection while reading from input stream when a connection is established to a resource.

 

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

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.

 

Writing Advanced Java Client Applications

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

 

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,  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,  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 that 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,  use a local copy of the WSDL file stored on your client computer; you cannot access the WSDL file using a URLConnection object.









 

  
    Skip navigation bar
    Back to Top
  
  
    
   Previous
  
  
    
   Next