Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Programming WebLogic Web Services > Invoking Web Services from Client Applications and WebLogic Server

Programming WebLogic Web Services

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

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.

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.

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:

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.

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

    3. For details, see Getting Information About a Web Service.

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

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

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

    2. 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:
    4. 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

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:

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:

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

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

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

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:

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.

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

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

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:

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:

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:

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.

 

Skip navigation bar  Back to Top Previous Next