Skip navigation.

eDocs Home > BEA WebLogic Server 9.0 Documentation > Programming Web Services for WebLogic Server > Advanced JWS Programming: Implementing Asynchronous Features

Programming Web Services for WebLogic Server

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

Advanced JWS Programming: Implementing Asynchronous Features

The following sections provide information about implementing asynchronous features using JWS files. The first four sections describe how to implement these features separately. Typically, however, programmers use these features together; see Using the Asynchronous Features Together for more information.

 

Using Web Service Reliable Messaging

Web Service reliable messaging is a framework whereby an application running in one application server can reliably invoke a Web Service running on another appication server, assuming that both servers implement the WS-ReliableMessaging specification. Reliable is defined as the ability to guarantee message delivery between the two Web Services.

Note: Web Services reliable messaging works between any two application servers that implement the WS-ReliableMessaging specification. In this document, however, it is assumed that the two application servers are WebLogic Server instances.

WebLogic Web Services 9.0 conform to the WS-ReliableMessaging specification (February 2005), which describes how two Web Services running on different application servers can communicate reliably in the presence of failures in software components, systems, or networks. In particular, the specification describes an interoperable protocol in which a message sent from a source endpoint (or client Web Service) to a destination endpoint (or Web Service whose operations can be invoked reliably) is guaranteed either to be delivered, according to one or more delivery assurances, or to raise an error.

A reliable WebLogic Web Service provides the following delivery assurances:

See the WS-ReliableMessaging specification for detailed documentation about the architecture of Web Service reliable messaging. Using Web Service Reliable Messaging: Main Steps describes how to create the reliable and client Web Services and how to configure the two WebLogic Server instances to which the Web Services are deployed.

Note: Web Services reliable messaging is not supported with the JMS transport feature.

Use of WS-Policy Files for Web Service Reliable Messaging Configuration

WebLogic Web Services use WS-Policy files to enable a destination endpoint to describe and advertise its Web Service reliable messaging capabilities and requirements. The WS-Policy specification provides a general purpose model and syntax to describe and communicate the policies of a Web service.

These WS-Policy files are XML files that describe features such as the version of the supported WS-ReliableMessaging specification, the source endpoint's retransmission interval, the destination endpoint's acknowledgment interval, and so on.

You specify the names of the WS-Policy files that are attached to your Web Service using the @Policy JWS annotation in your JWS file. Use the @Policies annotation to group together multiple @Policy annotations. For reliable messaging, you specify these annotations only at the class level.

WebLogic Server includes two simple WS-Policy files that you can specify in your JWS file if you do not want to create your own WS-Policy files:

You cannot change these pre-packaged files, so if their values do not suit your needs, you must create your own WS-Policy file.

See Creating the Web Service Reliable Messaging WS-Policy File for details about creating your own WS-Policy file if you do not want to one included with WebLogic Server. See Web Service Reliable Messaging Policy Assertion Reference, for reference information about the reliable messaging policy assertions.

DefaultReliability.xml WS-Policy File

<?xml version="1.0"?>
<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy"
  >
  <wsrm:RMAssertion >
    <wsrm:InactivityTimeout
        Milliseconds="600000" />
    <wsrm:AcknowledgementInterval
        Milliseconds="200" />
    <wsrm:BaseRetransmissionInterval
        Milliseconds="3000" />
    <wsrm:ExponentialBackoff />
    <beapolicy:Expires Expires="P1D"/>
  </wsrm:RMAssertion>
</wsp:Policy>

LongRunningReliability.xml WS-Policy File

<?xml version="1.0"?>
<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy"
  >
  <wsrm:RMAssertion >
    <wsrm:InactivityTimeout
        Milliseconds="86400000" />
    <wsrm:AcknowledgementInterval
        Milliseconds="200" />
    <wsrm:BaseRetransmissionInterval
        Milliseconds="3000" />
    <wsrm:ExponentialBackoff />
    <beapolicy:Expires Expires="P1M"/>
  </wsrm:RMAssertion>
</wsp:Policy>

Using Web Service Reliable Messaging: Main Steps

Configuring reliable messaging for a WebLogic Web Service requires standard JMS tasks such as creating JMS servers and Store and Forward (SAF) agents, as well as Web Service-specific tasks, such as adding additional JWS annotations to your JWS file. Optionally, you create WS-Policy files that describe the reliable messaging capabilities of the reliable Web Service if you do not use the pre-packaged ones.

If you are using the WebLogic client APIs to invoke a reliable Web Service, the client application must run on WebLogic Server. Thus, configuration tasks must be performed on both the source WebLogic Server instance on which the Web Service that includes client code to invoke the reliable Web Service reliably is deployed, as well as the destination WebLogic Server instance on which the reliable Web Service itself is deployed.

The following procedure describes how to create a reliable Web Service, as well as a client Web Service that in turn invokes an operation of the reliable Web Service reliably. The procedure shows how to create the JWS files that implement the two Web Services from scratch; if you want to update existing JWS files, use this procedure as a guide. The procedure also shows how to configure the source and destination WebLogic Server instances.

It is assumed that you have created a WebLogic Server instance where you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated reliable Web Service. It is further assumed that you have a similar setup for another WebLogic Server instance that hosts the client Web Service that invokes the Web Service reliably. For more information, see:

  1. Configure the destination WebLogic Server instance for Web Service reliable messaging.

    2. This is the WebLogic Server instance to which the reliable Web Service is deployed.

    See Configuring the Destination WebLogic Server Instance.

  2. Configure the source WebLogic Server instance for Web Service reliable messaging.

    3. This is the WebLogic Server instance to which the client Web Service that invokes the reliable Web Service is deployed.

    See Configuring the Source WebLogic Server Instance.

  3. Using your favorite XML or plain text editor, optionally create a WS-Policy file that describes the reliable messaging capabilities of the Web Service running on the destination WebLogic Server. This step is not required if you plan to use one of the two WS-Policy files that are included in WebLogic Server; see Use of WS-Policy Files for Web Service Reliable Messaging Configuration for more information.

    4. See Creating the Web Service Reliable Messaging WS-Policy File for details about creating your own WS-Policy file.

  4. Create a new JWS file, or update an existing one, which implements the reliable Web Service that will run on the destination WebLogic Server.

    5. See Programming Guidelines for the Reliable JWS File.

  5. Update your build.xml file to include a call to the jwsc Ant task which will compile the reliable JWS file into a Web Service.

    6. See Running the jwsc WebLogic Web Services Ant Task for general information about using the jwsc task.

  6. Compile your destination JWS file by calling the appropriate target and deploy to the destination WebLogic Server. For example:
    7. prompt> ant build-mainService deploy-mainService
  7. Create a new JWS file, or update an existing one, that implements the client Web Service that invokes the reliable Web Service. This service will be deployed to the source WebLogic Server.

    8. See Programming Guidelines for the JWS File That Invokes a Reliable Web Service.

  8. Update the build.xml file that builds the client Web Service.

    9. See Updating the build.xml File for a Client of a Reliable Web Service.

  9. Compile your client JWS file by calling the appropriate target and deploy to the source WebLogic Server. For example:
    10. prompt> ant build-clientService deploy-clientService

Configuring the Destination WebLogic Server Instance

Configuring the WebLogic Server instance on which the reliable Web Service is deployed involves configuring JMS and store and forward (SAF) resources. The following high-level procedure lists the tasks and then points to the Administration Console Online Help for details on performing the tasks.

  1. Invoke the Administration Console for the domain that contains the destination WebLogic Server in your browser.

    2. See Invoking the Administration Console for instructions on the URL that invokes the Administration Console.

  2. Optionally create a persistent store (either file or JDBC) that will be used by the destination WebLogic Server to store internal Web Service reliable messaging information. You can use an existing one, or the default store that always exists, if you do not want to create a new one.

    3. See Create file stores.

  3. Create a JMS Server. If a JMS server already exists, you can use it if you do not want to create a new one.

    4. See Create JMS servers.

  4. Create a JMS module, and then define a JMS queue in the module. If a JMS module already exists, you can use it if you do not want to create a new one. Target the JMS queue to the JMS server you created in the preceding step.

    5. Take note of the JNDI name you define for the JMS queue because you will later use it when you program the JWS file that implements your reliable Web Service.

    See Create JMS modules and Create queues.

  5. Create a store and forward (SAF) agent. You can use an existing one if you do not want to create a new one.

    6. When you create the SAF agent:

    See Create Store and Forward agents.

Cluster Considerations

If you are using the Web Service reliable messaging feature in a cluster, you must:

Configuring the Source WebLogic Server Instance

Configuring the WebLogic Server instance on which the client Web Service is deployed involves configuring JMS and store and forward (SAF) resources. The following high-level procedure lists the tasks and then points to the Administration Console online help for details on performing the tasks.

  1. Invoke the Administration Console for the domain that contains the source WebLogic Server in your browser.

    2. See Invoking the Administration Console for instructions on the URL that invokes the Administration Console.

  2. Create a persistent store (file or JDBC) that will be used by the source WebLogic Server to store internal Web Service reliable messaging information. You can use an existing one if you do not want to create a new one.

    3. See Create file stores.

  3. Create a JMS Server. You can use an existing one if you do not want to create a new one.

    4. See Create JMS servers.

  4. Create a store and forward (SAF) agent. You can use an existing one if you do not want to create a new one.

    5. Be sure when you create the SAF agent that you set the Agent Type field to Both to enable both sending and receiving agents.

    See Create Store and Forward agents.

Creating the Web Service Reliable Messaging WS-Policy File

A WS-Policy file is an XML file that contains policy assertions that comply with the WS-Policy specification. In this case, the WS-Policy file contains Web Service reliable messaging policy assertions.

You can use one of the two default reliable messaging WS-Policy files included in WebLogic Server; these files are adequate for most use cases. However, because these files cannot be changed, if they do not suit your needs, you must create your own. See Use of WS-Policy Files for Web Service Reliable Messaging Configuration for a description of the included WS-Policy files. The remainder of this section describes how to create your own WS-Policy file.

The root element of the WS-Policy file is <Policy> and it should include the following namespace declarations for using Web Service reliable messaging policy assertions:

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy">

You wrap all Web Service reliable messaging policy assertions inside of a <wsrm:RMAssertion> element. The assertions that use the wsrm: namespace are standard ones defined by the WS-ReliableMessaging specification. The assertions that use the beapolicy: namespace are WebLogic-specific. See Web Service Reliable Messaging Policy Assertion Reference, for details.

All Web Service reliable messaging assertions are optional, so only set those whose default values are not adequate. You can specify the following assertions:

The following example shows a simple Web Service reliable messaging WS-Policy file:

<?xml version="1.0"?>
<wsp:Policy wsp:Name="ReliableHelloWorldPolicy"
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:beapolicy="http://www.bea.com/wsrm/policy">
 <wsrm:RMAssertion>
   <wsrm:InactivityTimeout
      Milliseconds="600000" />
   <wsrm:AcknowledgementInterval
      Milliseconds="2000" />
   <wsrm:BaseRetransmissionInterval
      Milliseconds="500" />
   <wsrm:ExponentialBackoff />
 </wsrm:RMAssertion>
</wsp:Policy>

Programming Guidelines for the Reliable JWS File

This section describes how to create the JWS file that implements the reliable Web Service.

The following JWS annotations are used in the JWS file that implements a reliable Web Service:

The following example shows a simple JWS file that implements a reliable Web Service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.reliable;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.BufferQueue;
import weblogic.jws.Policy;
/**
 * Simple reliable Web Service.
 */
@WebService(name="ReliableHelloWorldPortType",
              serviceName="ReliableHelloWorldService")
@WLHttpTransport(contextPath="ReliableHelloWorld",
      serviceUri="ReliableHelloWorld",
      portName="ReliableHelloWorldServicePort")
@Policy(uri="ReliableHelloWorldPolicy.xml",
          direction=Policy.Direction.both,
          attachToWsdl=true)
@BufferQueue(name="webservices.reliable.queue")
public class ReliableHelloWorldImpl {
  @WebMethod()
  @Oneway()
  @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")
  public void helloWorld(String input) {
    System.out.println(" Hello World " + input);
  }
}

In the example, the ReliableHelloWorldPolicy.xml file is attached to the Web Service at the class level, which means that the policy file is applied to all public operations of the Web Service. The policy file is applied only to the request Web Service message (as required by the reliable messaging feature) and it is attached to the WSDL file.

The JMS queue that WebLogic Server uses internally to enable the Web Service reliable messaging has a JNDI name of webservices.reliable.queue, as specified by the @BufferQueue annotation.

The helloWorld() method has been marked with both the @WebMethod and @Oneway JWS annotations, which means it is a public operation called helloWorld. Because of the @Policy annotation, the operation can be invoked reliably. The Web Services runtime attempts to deliver reliable messages to the service a maximum of 10 times, at 10-second intervals, as described by the @ReliabilityBuffer annotation. The message may require redelivery if, for example, the transation is rolled back or otherwise does not commit.

Using the @Policy Annotation

Use the @Policy annotation in your JWS file to specify that the Web Service has a WS-Policy file attached to it that contains reliable messaging assertions.

See Use of WS-Policy Files for Web Service Reliable Messaging Configuration for descriptions of the two WS-Policy files (DefaultReliability.xml and LongRunningReliability.xml) included in WebLogic Server that you can use instead of writing your own.

You must follow these requirements when using the @Policy annotation for Web Service reliable messaging:

Use the uri attribute to specify the build-time location of the policy file, as follows:

You can also set the attachToWsd attribute of the @Policy annotation to specify whether the policy file should be attached to the WSDL file that describes the public contract of the Web Service. Typically you want to publicly publish the policy so that client applications know the reliable messaging capabilities of the Web Service. For this reason, the default value of this attribute is true.

Using the @Oneway Annotation

If you plan on invoking the reliable Web Service operation synchronously (or in other words, not using the asynchronous request-response feature), then the implementing method is required to be annotated with the @Oneway annotation to specify that the method is one-way. This means that the method cannot return a value, but rather, must explicitly return void.

Conversely, if the method is not annotated with the @Oneway annotation, then you must invoke it using the asynchronous request-response feature. If you are unsure how the operation is going to be invoked, consider creating two flavors of the operation: synchronous and asynchronous.

See Invoking a Web Service Using Asynchronous Request-Response and Using the Asynchronous Features Together.

Using the @BufferQueue Annotation

Use the @BufferQueue annotation to specify the JNDI name of the JMS queue which WebLogic Server uses to store reliable messages internally. The JNDI name is the one you configured when creating a JMS queue in step 4. in Configuring the Destination WebLogic Server Instance.

The @BufferQueue annotation is optional; if you do not specify it in your JWS file then WebLogic Server uses a queue with a JNDI name of weblogic.wsee.DefaultQueue. You must, however, still explicitly create a JMS queue with this JNDI name using the Administration Console.

Using the @ReliabilityBuffer Annotation

Use this annotation to specify the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web Service implementation (default 3) and the amount of time that the server should wait in between retries (default 5 seconds).

Use the retryCount attribute to specify the number of retries and the retryDelay attribute to specify the wait time. The format of the retryDelay attribute is a number and then one of the following strings:

For example, to specify a retry count of 20 and a retry delay of two days, use the following syntax:

@ReliabilityBuffer(retryCount=20, retryDelay="2 days")

Programming Guidelines for the JWS File That Invokes a Reliable Web Service

If you are using the WebLogic client APIs, you must invoke a reliable Web Service from within a Web Service; you cannot invoke a reliable Web Service from a stand-alone client application.

The following example shows a simple JWS file for a Web Service that invokes a reliable operation from the service described in Programming Guidelines for the Reliable JWS File; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.reliable;
import java.rmi.RemoteException;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import examples.webservices.reliable.ReliableHelloWorldPortType;
@WebService(name="ReliableClientPortType",
            serviceName="ReliableClientService")
@WLHttpTransport(contextPath="ReliableClient",
                 serviceUri="ReliableClient",
                 portName="ReliableClientServicePort")
public class ReliableClientImpl 
{
  @ServiceClient(
     wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")
  private ReliableHelloWorldPortType port;
  @WebMethod
  public void callHelloWorld(String input, String serviceUrl)
     throws RemoteException {
    port.helloWorld(input);
    System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );
  }
}

Follow these guidelines when programming the JWS file that invokes a reliable Web Service; code snippets of the guidelines are shown in bold in the preceding example:

Updating the build.xml File for a Client of a Reliable Web Service

To update a build.xml file to generate the JWS file that invokes the operation of a reliable Web Service, add taskdefs and a build-reliable-client targets that look something like the following; see the description after the example for details:

  <path id="ws.client.class.path">
    <pathelement path="${tempjar-dir}"/>
    <pathelement path="${java.class.path}"/>
  </path>
<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <target name="build-reliable-client">
    <clientgen
      wsdl="http://${wls.destination.host}:${wls.destination.port}/ReliableHelloWorld/ReliableHelloWorld?WSDL"
      destDir="${tempjar-dir}"
      packageName="examples.webservices.reliable"/>
    <javac
      source="1.5"
      srcdir="${tempjar-dir}"
      destdir="${tempjar-dir}"
      includes="**/*.java"/>
    <jwsc
        srcdir="src"
        destdir="${client-ear-dir}"
        classpathref="ws.client.class.path">
        <jws
           file="examples/webservices/reliable/ReliableClientImpl.java"/>
    </jwsc>
    <copy todir="${client-ear-dir}/app-inf/classes">
         <fileset dir="${tempjar-dir}" />
    </copy>
  </target>

Use the taskdef Ant task to define the full classname of the jwsc and clientgen Ant tasks.

Before running the jwsc Ant task, you must first use clientgen to generate and compile the JAX-RPC stubs for the deployed ReliableHelloWorld Web Service. You do this because the ReliableClientImpl JWS file imports and uses one of the generated classes, and the jwsc task fails if the classes do not already exist. When you execute the jwsc Ant task, use the classpathref attribute to add to the CLASSPATH the temporary directory into which clientgen generated its artifacts.

After jwsc has generated all its artifacts into the EAR directory, use the copy Ant task to copy the clientgen-generated artifacts into the APP-INF/classes directory of the EAR so that the ReliableClientService Web Service can find them.

Note: The APP-INF/classes directory is a WebLogic-specific feature for sharing classes in an Enterprise application.

 

Invoking a Web Service Using Asynchronous Request-Response

When you invoke a Web Service synchronously, the invoking client application waits for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the Web Service might be adequate. However, because request processing can be delayed, it is often useful for the client application to continue its work and handle the response later on, or in other words, use the asynchronous request-response feature of WebLogic Web Services.

You invoke a Web Service asynchronously only from a client running in a WebLogic Web Service, never from a stand alone client application. The invoked Web Service does not change in any way, thus you can invoke any deployed Web Service (both WebLogic and non-WebLogic) asynchronously as long as the application server that hosts the Web Service supports the WS-Addressing specification.

When implementing asynchronous request-response in your client, rather than invoking the operation directly, you invoke an asynchronous flavor of the same operation. (This asynchronous flavor of the operation is automatically generated by the clientgen Ant task.) For example, rather than invoking an operation called getQuote directly, you would invoke getQuoteAsync instead. The asynchronous flavor of the operation always returns void, even if the original operation returns a value. You then include methods in your client that handle the asynchronous response or failures when it returns later on. You put any business logic that processes the return value of the Web Service operation invoke or a potential failure in these methods. You use both naming conventions and JWS annotations to specify these methods to the JWS compiler. For example, if the asynchronous operation is called getQuoteAsync, then these methods might be called onGetQuoteAsyncResponse and onGetQuoteAsyncFailure.

Note: For information about using asynchronous request-response with other asynchronous features, such as Web Service reliable messaging or buffering, see Using the Asynchronous Features Together. This section describes how to use the asynchronous request-response feature on its own.

Note: The asynchronous request-response feature works only with HTTP; you cannot use it with the HTTPS or JMS transport.

Using Asynchronous Request-Response: Main Steps

The following procedure describes how to create a client Web Service that asynchronously invokes an operation in a different Web Service. The procedure shows how to create the JWS file that implements the client Web Service from scratch; if you want to update an existing JWS file, use this procedure as a guide.

For clarity, it is assumed in the procedure that:

It is further assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated service. See Common Web Services Use Cases and Examples, Iterative Development of WebLogic Web Services, and Programming the JWS File.

  1. Using your favorite IDE or text editor, create a new JWS file, or update an existing one, that implements the StockQuoteClientService Web Service.

    2. See Writing the Asynchronous JWS File.

  2. Update your build.xml file to run the clientgen Ant task against the StockQuoteService Web Service and to compile the JWS file that implements the StockQuoteClientService. The clientgen Ant task automatically generates the asynchronous flavor of the Web Service operations you are invoking.

    3. See Updating the build.xml File When Using Asynchronous Request-Response.

  3. Run the Ant target to build the StockQuoteClientService:
    4. prompt> ant build-clientService
  4. Deploy the StockQuoteClientService Web Service as usual.

    5. See Deploying and Undeploying WebLogic Web Services.

When you invoke the StockQuoteClientService Web Service, which in turn invokes the StockQuoteService Web Service, the second invoke will be asynchronous rather than synchronous.

Writing the Asynchronous JWS File

The following example shows a simple JWS file that implements a Web Service called StockQuoteClient that has a single method, asyncOperation, that in turn asynchronously invokes the getQuote method of the StockQuote service. The Java code in bold is described Coding Guidelines for Invoking a Web Service Asynchronously. See Example of a Synchronous Invoke to see how the asynchronous invoke differs from a synchronous invoke of the same operation.

package examples.webservices.async_req_res;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;
import javax.jws.WebService;
import javax.jws.WebMethod;
import examples.webservices.async_req_res.StockQuotePortType;
import java.rmi.RemoteException;
@WebService(name="StockQuoteClientPortType",
            serviceName="StockQuoteClientService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="asyncClient",
                 serviceUri="StockQuoteClient",
                 portName="StockQuoteClientServicePort")
/**
 *  Client Web Service that invokes the StockQuote Service asynchronously.
 */
public class StockQuoteClientImpl {
  @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
                 serviceName="StockQuoteService", portName="StockQuote")
  private StockQuotePortType port;
  @WebMethod
  public void asyncOperation (String symbol) throws RemoteException {
    AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
    apc.setProperty("symbol", symbol);
    try {
      port.getQuoteAsync(apc, symbol );
      System.out.println("in getQuote method of StockQuoteClient WS");
     } catch (RemoteException re) {
        System.out.println("RemoteException thrown");
        throw new RuntimeException(re);
    }
  }
  @AsyncResponse(target="port", operation="getQuote")
  public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
    System.out.println("-------------------");
    System.out.println("Got quote " + quote );
    System.out.println("-------------------");
  }
  @AsyncFailure(target="port", operation="getQuote")
  public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
  }
}

Coding Guidelines for Invoking a Web Service Asynchronously

The following guidelines for invoking an operation asynchronously correspond to the Java code shown in bold in the example described in Writing the Asynchronous JWS File. These guidelines are in addition to the standard ones for creating JWS files. See Example of a Synchronous Invoke to see how the asynchronous invoke differs from a synchronous invoke of the same operation.

To invoke an operation asynchronously in your JWS file:

Note: You are not required to use the @AsyncResponse and @AsyncFailure annotations, although it is a good practice because it clears up any ambiguity and makes your JWS file clean and understandable. However, in the rare use case where you want one of the onXXX methods to handle the asynchronous response or failure from two (or more) stubs that are invoking operations from two different Web Services that have the same name, then you should explicitly NOT use these annotations. Be sure that the name of the onXXX methods follow the correct naming conventions exactly, as described above.

Example of a Synchronous Invoke

The following example shows a JWS file that invokes the getQuote operation of the StockQuote Web Service synchronously. The example is shown only so you can compare it with the corresponding asynchronous invoke shown in Writing the Asynchronous JWS File.

package examples.webservices.async_req_res;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import javax.jws.WebService;
import javax.jws.WebMethod;
import java.rmi.RemoteException;
@WebService(name="SyncClientPortType",
            serviceName="SyncClientService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="syncClient",
                 serviceUri="SyncClient",
                 portName="SyncClientPort")
/**
 *  Normal ole service-to-service client that invokes StockQuote service
 *  synchronously.
 */
public class SyncClientImpl {
  @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
                 serviceName="StockQuoteService", portName="StockQuote")
  private StockQuotePortType port;
  @WebMethod
  public void nonAsyncOperation(String symbol) throws RemoteException {
    int quote = port.getQuote(symbol);
    System.out.println("-------------------");
    System.out.println("Got quote " + quote );
    System.out.println("-------------------");
  }
}

Updating the build.xml File When Using Asynchronous Request-Response

To update a build.xml file to generate the JWS file that invokes a Web Service operation asynchronously, add taskdefs and a build-clientService target that looks something like the following; see the description after the example for details:

<path id="ws.clientService.class.path">
    <pathelement path="${tempjar-dir}"/>
    <pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <target name="build-clientService">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/async/StockQuote?WSDL"
      destDir="${tempjar-dir}"
      packageName="examples.webservices.async_req_res"/>
    <javac
      source="1.5"
      srcdir="${tempjar-dir}" 
      destdir="${tempjar-dir}"
      includes="**/*.java"/>
    <jwsc
        srcdir="src"
        destdir="${clientService-ear-dir}"
        classpathref="ws.clientService.class.path">
        <jws 
         file="examples/webservices/async_req_res/StockQuoteClientImpl.java" />
    </jwsc>
    <copy todir="${clientService-ear-dir}/app-inf/classes">
         <fileset dir="${tempjar-dir}" />
    </copy>
  </target>

Use the taskdef Ant task to define the full classname of the jwsc and clientgen Ant tasks.

Before running the jwsc Ant task, you must first use clientgen to generate and compile the JAX-RPC stubs for the deployed StockQuote Web Service; this is because the StockQuoteClientImpl JWS file imports and uses the generated classes, and the jwsc task will fail if the classes does not already exist. By default, the clientgen Ant task generates both synchronous and asynchronous flavors of the Web Service operations in the JAX-RPC stubs. When you execute the jwsc Ant task, use the classpathref attribute to add to the CLASSPATH the temporary directory into which clientgen generated its artifacts.

After jwsc has generated all its artifacts into the EAR directory, use the copy Ant task to copy the clientgen-generated artifacts into the APP-INF/classes directory of the EAR so that the StockQuoteClient Web Service can find them.

Note: The APP-INF/classes directory is a WebLogic-specific feature for sharing classes in an Enterprise application.

 

Creating Conversational Web Services

A Web Service and the client application that invokes it may communicate multiple times to complete a single task. Also, multiple client applications might communicate with the same Web Service at the same time. Conversations provide a straightforward way to keep track of data between calls and to ensure that the Web Service always responds to the correct client.

Conversations meet two challenges inherent in persisting data across multiple communications:

WebLogic Server manages this unique ID and state by creating a conversation context each time a client application initiates a new conversation. The Web Service then uses the context to correlate calls to and from the service and to persist its state-related data.

Conversations between a client application and a Web Service have three distinct phases:

Conversations typically occur between two WebLogic Web Services: one is marked conversational and defines the start, continue, and finish operations and the other Web Service uses the @ServiceClient annotation to specify that it is a client of the conversational Web Service. You can also invoke a conversational Web Service from a stand-alone Java client, although there are restrictions.

As with other WebLogic Web Service features, you use JWS annotations to specify that a Web Service is conversational.

Caution: A conversational Web Service on its own does not guarantee message delivery or that the messages are delivered in order, exactly once. If you require this kind of message delivery guarantee, you must also specify that the Web Service be reliable. See Using Web Service Reliable Messaging and Using the Asynchronous Features Together.

Creating a Conversational Web Service: Main Steps

The following procedure describes how to create a conversational Web Service, as well as a client Web Service and stand-alone Java client application, both of which initiate and conduct a conversation. The procedure shows how to create the JWS files that implement the two Web Services from scratch. If you want to update existing JWS files, you can also use this procedure as a guide.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated conversational Web Service. It is further assumed that you have a similar setup for the WebLogic Server instance that hosts the client Web Service that initiates the conversation. For more information, see Common Web Services Use Cases and Examples, Iterative Development of WebLogic Web Services, and Programming the JWS File..

  1. Using your favorite IDE or text editor, create a new JWS file, or update an existing one, that implements the conversational Web Service.

    2. See Programming Guidelines for the Conversational JWS File.

  2. Update your build.xml file to include a call to the jwsc Ant task to compile the conversational JWS file into a Web Service.

    3. See Running the jwsc WebLogic Web Services Ant Task.

  3. Run the Ant target to build the conversational Web Service. For example:
    4. prompt> ant build-mainService
  4. Deploy the Web Service as usual.

    5. See Deploying and Undeploying WebLogic Web Services.

  5. If the client application is a stand-alone Java client, see Updating a Stand-Alone Java Client to Invoke a Conversational Web Service. If the client application is itself a Web Service, follow these steps:
    1. Using your favorite IDE or text editor, create a new JWS file, or update an existing one, that implements the client Web Service that initiates and conducts the conversation with the conversational Web Service. It is assumed that the client Web Service is deployed to a different WebLogic Server instance from the one that hosts the conversational Web Service.

      2. See Programming Guidelines for the JWS File That Invokes a Conversational Web Service.

    2. Update the build.xml file that builds the client Web Service.

      3. See Updating the build.xml File for a Client of a Conversational Web Service.

    3. Run the Ant target to build the client Web Service:
      4. prompt> ant build-clientService
    4. Deploy the Web Service as usual.

      5. See Deploying and Undeploying WebLogic Web Services.

Programming Guidelines for the Conversational JWS File

The following example shows a simple JWS file that implements a conversational Web Service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conversation;
import java.io.Serializable;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Conversational;
import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext;
import weblogic.wsee.jws.ServiceHandle;
import javax.jws.WebService;
import javax.jws.WebMethod;
@Conversational(maxIdleTime="10 minutes",
                maxAge="1 day",
                runAsStartUser=false,
                singlePrincipal=false )
@WebService(name="ConversationalPortType",
            serviceName="ConversationalService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="conv",
                 serviceUri="ConversationalService",
                 portName="ConversationalServicePort")
/**
 * Conversational Web Service.
 */
public class ConversationalServiceImpl implements Serializable {
  @Context
  private JwsContext ctx;
  public String status = "undefined";
  @WebMethod
  @Conversation (Conversation.Phase.START)
  public String start() {
    ServiceHandle handle = ctx.getService();
    String convID = handle.getConversationID();
    status = "start";
    return "Starting conversation, with ID " + convID + " and status equal to " + status;
  }
  @WebMethod
  @Conversation (Conversation.Phase.CONTINUE)
  public String middle(String message) {
    status = "middle";
    return "Middle of conversation; the message is: " + message + " and status is " + status;
  }
  @WebMethod
  @Conversation (Conversation.Phase.FINISH)
  public String finish(String message ) {
    status = "finish";
    return "End of conversation; the message is: " + message + " and status is " + status;
  }
}

Follow these guidelines when programming the JWS file that implements a conversational Web Service. Code snippets of the guidelines are shown in bold in the preceding example.

Programming Guidelines for the JWS File That Invokes a Conversational Web Service

The following example shows a simple JWS file for a Web Service that invokes the conversational Web Service described in Programming Guidelines for the Conversational JWS File; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conversation;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import javax.jws.WebService;
import javax.jws.WebMethod;
import examples.webservices.conversation.ConversationalPortType;
import java.rmi.RemoteException;
@WebService(name="ConversationalClientPortType",
            serviceName="ConversationalClientService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="convClient",
                 serviceUri="ConversationalClient",
                 portName="ConversationalClientPort")
/**
 *  client that has a conversation with the ConversationalService.
 */
public class ConversationalClientImpl {
  @ServiceClient(
     wsdlLocation="http://localhost:7001/conv/ConversationalService?WSDL",
     serviceName="ConversationalService",
     portName="ConversationalServicePort")
  private ConversationalPortType port;
  @WebMethod
  public void runConversation(String message) {
    try {
      // Invoke start operation
      String result = port.start();
      System.out.println("start method executed.");
      System.out.println("The message is: " + result);
      // Invoke continue operation
      result = port.middle(message );
      System.out.println("middle method executed.");
      System.out.println("The message is: " + result);
      // Invoke finish operation
      result = port.finish(message );
      System.out.println("finish method executed.");
      System.out.println("The message is: " + result);
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }
  }
}

Follow these guidelines when programming the JWS file that invokes a conversational Web Service; code snippets of the guidelines are shown in bold in the preceding example:

Updating the build.xml File for a Client of a Conversational Web Service

You update a build.xml file to generate the JWS file that invokes a conversational Web Service by adding taskdefs and a build-clientService target that looks something like the following example. See the description after the example for details.

<path id="ws.clientService.class.path">
    <pathelement path="${tempjar-dir}"/>
    <pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <target name="build-clientService">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/conv/ConversationalService?WSDL"
      destDir="${tempjar-dir}"
      packageName="examples.webservices.conversation"/>
    <javac
      source="1.5"
      srcdir="${tempjar-dir}" destdir="${tempjar-dir}"
      includes="**/*.java"/>
    <jwsc
        srcdir="src"
        destdir="${clientService-ear-dir}"
        classpathref="ws.clientService.class.path">
        <jws
     file="examples/webservices/conversation/ConversationalClientImpl.java"
        />
    </jwsc>
    <copy todir="${clientService-ear-dir}/APP-INF/classes">
         <fileset dir="${tempjar-dir}" />
    </copy>
  </target>

Use the taskdef Ant task to define the full classname of the jwsc and clientgen Ant tasks.

Before running the jwsc Ant task, you must first use clientgen to generate and compile the JAX-RPC stubs for the deployed ConversationalService Web Service; this is because the ConversationalClientImpl JWS file imports and uses the generated classes, and the jwsc task fails if the classes do not already exist. When you execute the jwsc Ant task, use the classpathref attribute to add to the CLASSPATH the temporary directory into which clientgen generated its artifacts.

After jwsc has generated all its artifacts into the EAR directory, use the copy Ant task to copy the clientgen-generated artifacts into the APP-INF/classes directory of the EAR so that the ConversationalClientService Web Service can find them.

Note: The APP-INF/classes directory is a WebLogic-specific feature for sharing classes in an Enterprise application.

Updating a Stand-Alone Java Client to Invoke a Conversational Web Service

The following example shows a simple stand-alone Java client that invokes the conversational Web Service described in Programming Guidelines for the Conversational JWS File. See the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.conv_standalone.client;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import weblogic.wsee.jaxrpc.WLStub;
/**
 * stand-alone client that invokes and converses with ConversationlService.
 */
public class Main {
  public static void main(String[] args)
      throws ServiceException, RemoteException{
      ConversationalService service = new ConversationalService_Impl(args[0] + "?WSDL");
      ConversationalPortType port = service.getConversationalServicePort();
      // Set property on stub to specify that client is invoking a Web Service
      // that uses advanced features; this property is automatically set if
      // the client runs in a WebLogic Server instance.
      Stub stub = (Stub)port;
      stub._setProperty(WLStub.COMPLEX,  "true");
      // Invoke start operation to begin the conversation
      String result = port.start();
      System.out.println("start method executed.");
      System.out.println("The message is: " + result);
      // Invoke continue operation
      result = port.middle("middle" );
      System.out.println("middle method executed.");
      System.out.println("The message is: " + result);
      // Invoke finish operation
      result = port.finish("finish" );
      System.out.println("finish method executed.");
      System.out.println("The message is: " + result);
  }
}

Follow these guidelines when programming the stand-alone Java client that invokes a conversational Web Service. Code snippets of the guidelines are shown in bold in the preceding example.

 

Creating Buffered Web Services

When a buffered operation is invoked by a client, the method operation goes on a JMS queue and WebLogic Server deals with it asynchronously. As with Web Service reliable messaging, if WebLogic Server goes down while the method invocation is still in the queue, it will be dealt with as soon as WebLogic Server is restarted. When a client invokes the buffered Web Service, the client does not wait for a response from the invoke, and the execution of the client can continue.

Creating a Buffered Web Service: Main Steps

The following procedure describes how to create a buffered Web Service and a client Web Service that invokes an operation of the buffered Web Service. The procedure shows how to create the JWS files that implement the two Web Services from scratch. If you want to update existing JWS files, use this procedure as a guide. The procedure also shows how to configure the WebLogic Server instance that hosts the buffered Web Service.

Note: Unless you are also using the asynchronous request-response feature, you do not need to invoke a buffered Web Service from another Web Service, you can also invoke it from a stand-alone Java application.

It is assumed that you have set up an Ant-based development environment and that you have a working build.xml file to which you can add targets for running the jwsc Ant task and deploying the generated buffered Web Service. It is further assumed that you have a similar setup for the WebLogic Server instance that hosts the client Web Service that invokes the buffered Web Service. For more information, see:

  1. Configure the WebLogic Server instance that hosts the buffered Web Service.

    2. See Configuring the Host WebLogic Server Instance for the Buffered Web Service.

  2. Create a new JWS file, or update an existing one, that will implement the buffered Web Service.

    3. See Programming Guidelines for the Buffered JWS File.

  3. Update the build.xml file to include a call to the jwsc Ant task to compile the JWS file into a buffered Web Service; for example:
    4. <jwsc
        srcdir="src"
        destdir="${service-ear-dir}" >
        <jws
          file="examples/webservices/async_buffered/AsyncBufferedImpl.java" 
        />
    </jwsc>

    See Running the jwsc WebLogic Web Services Ant Task for general information about using the jwsc task.

  4. Recompile your destination JWS file by calling the appropriate target and deploying the Web Service to WebLogic Server. For example:
    5. prompt> ant build-mainService deploy-mainService
  5. Create a new JWS file, or update an existing one, that implements the client Web Service that invokes the buffered Web Service.

    6. See Programming the JWS File That Invokes the Buffered Web Service.

  6. Update the build.xml file that builds the client Web Service.

    7. See Updating the build.xml File for a Client of the Buffered Web Service.

  7. Recompile your client JWS file by calling the appropriate target, then redeploy the Web Service to the client WebLogic Server. For example:
    8. prompt> ant build-clientService deploy-clientService

Configuring the Host WebLogic Server Instance for the Buffered Web Service

Configuring the WebLogic Server instance on which the buffered Web Service is deployed involves configuring JMS resources, such as JMS servers and modules, that are used internally by the Web Services runtime. The following high-level procedure lists the tasks and then points to the Administration Console online help for details on performing the tasks.

  1. Invoke the Administration Console for the domain that contains the WebLogic Server instance that hosts the buffered Web Service in your browser.

    2. See Invoking the Administration Console for instructions on the URL that invokes the Administration Console.

  2. Create a JMS Server. You can use an existing one if you do not want to create a new one.

    3. See Create JMS servers.

  3. Create a JMS module that contains a JMS queue. Target the JMS queue to the JMS server you created in the preceding step.

    4. If you want the buffered Web Service to use the default Web Services queue, set the JNDI name of the JMS queue to weblogic.wsee.DefaultQueue. Otherwise, if you use a different JNDI name, be sure to use the @BufferQueue annotation in the JWS file to specify this JNDI name to the reliable Web Service. See Programming Guidelines for the Buffered JWS File.

    If you are using the buffered Web Service feature in a cluster, you must still create a local queue rather than a distributed queue. In addition, you must explicitly target this queue to each server in the cluster.

    See Create JMS modules and Create queues.

Programming Guidelines for the Buffered JWS File

The following example shows a simple JWS file that implements a buffered Web Service; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package examples.webservices.buffered;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;
@WebService(name="BufferedPortType",
            serviceName="BufferedService",
            targetNamespace="http://example.org")
@WLHttpTransport(contextPath="buffered",
                 serviceUri="BufferedService",
                 portName="BufferedPort")
// Annotation to specify a specific JMS queue rather than the default
@BufferQueue(name="my.jms.queue")
/**
 * Simple buffered Web Service.
 */
public class BufferedImpl {
  @WebMethod()
  @MessageBuffer(retryCount=10, retryDelay="10 seconds")
  @Oneway()
  public void sayHelloNoReturn(String message) {
    System.out.println("sayHelloNoReturn: " + message);
  }
}

Follow these guidelines when programming the JWS file that implements a buffered Web Service. Code snippets of the guidelines are shown in bold in the preceding example.

Programming the JWS File That Invokes the Buffered Web Service

You can invoke a buffered Web Service from both a stand-alone Java application (if not using asynchronous request-response) and from another Web Service. Unlike other WebLogic Web Services asynchronous features, however, you do not use the @ServiceClient JWS annotation in the client Web Service, but rather, you invoke the service as you would any other. For details, see Invoking a Web Service from Another Web Service.

The following sample JWS file shows how to invoke the sayHelloNoReturn operation of the BufferedService Web Service:

package examples.webservices.buffered;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import javax.jws.WebService;
import javax.jws.WebMethod;
import weblogic.jws.WLHttpTransport;
import examples.webservices.buffered.BufferedPortType;
import examples.webservices.buffered.BufferedService_Impl;
import examples.webservices.buffered.BufferedService;
@WebService(name="BufferedClientPortType",
            serviceName="BufferedClientService",
            targetNamespace="http://examples.org")
@WLHttpTransport(contextPath="bufferedClient",
                 serviceUri="BufferedClientService",
                 portName="BufferedClientPort")
public class BufferedClientImpl {
  @WebMethod()
  public String callBufferedService(String input, String serviceUrl)
        throws RemoteException {
    try {
    BufferedService service = new BufferedService_Impl(serviceUrl + "?WSDL");
    BufferedPortType port = service.getBufferedPort();
    // Invoke the sayHelloNoReturn() operation of BufferedService
    port.sayHelloNoReturn(input);
    return "Invoke went okay!";
    } catch (ServiceException se) {
         System.out.println("ServiceExcpetion thrown");
         throw new RuntimeException(se);
      }
  }
}

Updating the build.xml File for a Client of the Buffered Web Service

To update a build.xml file to generate the JWS file that invokes a buffered Web Service operation, add taskdefs and a build-clientService targets that look something like the following example. See the description after the example for details.

<path id="ws.clientService.class.path">
    <pathelement path="${tempjar-dir}"/>
    <pathelement path="${java.class.path}"/>
</path>
<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />
<taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="build-clientService">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/buffered/BufferedService?WSDL"
      destDir="${tempjar-dir}"
      packageName="examples.webservices.buffered"/>
    <javac
      source="1.5"
      srcdir="${tempjar-dir}" 
      destdir="${tempjar-dir}"
      includes="**/*.java"/>
    <jwsc
        srcdir="src"
        destdir="${clientService-ear-dir}"
        classpathref="ws.clientService.class.path">
        <jws 
           file="examples/webservices/buffered/BufferedClientImpl.java"
        />
    </jwsc>
    <copy todir="${clientService-ear-dir}/app-inf/classes">
         <fileset dir="${tempjar-dir}" />
    </copy>
  </target>

Use the taskdef Ant task to define the full classname of the jwsc and clientgen Ant tasks.

Before running the jwsc Ant task, you must first use clientgen to generate and compile the JAX-RPC stubs for the deployed BufferedService Web Service; this is because the BufferedClientImpl JWS file imports and uses one of the generated classes, and the jwsc task will fail if the classes does not already exist. When you execute the jwsc Ant task, use the classpathref attribute to add to the CLASSPATH the temporary directory into which clientgen generated its artifacts.

After jwsc has generated all its artifacts into the EAR directory, use the copy Ant task to copy the clientgen-generated artifacts into the APP-INF/classes directory of the EAR so that the BufferedClientService Web Service can find them.

Note: The APP-INF/classes directory is a WebLogic-specific feature for sharing classes in an Enterprise application.

 

Using the Asynchronous Features Together

The preceding sections describe how to use the WebLogic Web Service asynchronous features (Web Service reliable messaging, conversations, asynchronous request-response, and buffering) on their own. Typically, however, Web Services use the features together; see Example of a JWS File That Implements a Reliable Conversational Web Service and Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service for examples.

When used together, some restrictions described in the individual feature sections do not apply, and sometimes additional restrictions apply.

Example of a JWS File That Implements a Reliable Conversational Web Service

The following sample JWS file implements a Web Service that is both reliable and conversational:

package examples.webservices.async_mega;
import java.io.Serializable;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Conversation;
import weblogic.jws.Policy;
import javax.jws.WebService;
import javax.jws.WebMethod;
@WebService(name="AsyncMegaPortType",
            serviceName="AsyncMegaService",
            targetNamespace="http://examples.org/")
@Policy(uri="AsyncReliableConversationPolicy.xml",
        attachToWsdl=true)
@WLHttpTransport(contextPath="asyncMega",
                 serviceUri="AsyncMegaService",
                 portName="AsyncMegaServicePort")
/**
 * Web Service that is both reliable and conversational.
 */
public class AsyncMegaServiceImpl implements Serializable {
  @WebMethod
  @Conversation (Conversation.Phase.START)
  public String start() {
    return "Starting conversation";
  }
  @WebMethod
  @Conversation (Conversation.Phase.CONTINUE)
  public String middle(String message) {
    return "Middle of conversation; the message is: " + message;
  }
  @WebMethod
  @Conversation (Conversation.Phase.FINISH)
  public String finish(String message ) {
    return "End of conversation; the message is: " + message;
  }
}

Example of Client Web Service That Asynchronously Invokes a Reliable Conversational Web Service

The following JWS file shows how to implement a client Web Service that reliably invokes the various conversational methods of the Web Service described in Example of a JWS File That Implements a Reliable Conversational Web Service; the client JWS file uses the asynchronous request-response feature as well.

package examples.webservices.async_mega;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient;
import weblogic.jws.AsyncResponse;
import weblogic.jws.AsyncFailure;
import javax.jws.WebService;
import javax.jws.WebMethod;
import weblogic.wsee.async.AsyncPreCallContext;
import weblogic.wsee.async.AsyncCallContextFactory;
import weblogic.wsee.async.AsyncPostCallContext;
import examples.webservices.async_mega.AsyncMegaPortType;
import examples.webservices.async_mega.AsyncMegaService;
import examples.webservices.async_mega.AsyncMegaService_Impl;
import java.rmi.RemoteException;
@WebService(name="AsyncMegaClientPortType",
            serviceName="AsyncMegaClientService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="asyncMegaClient",
                 serviceUri="AsyncMegaClient",
                 portName="AsyncMegaClientServicePort")
/**
 * Client Web Service that has a conversation with the AsyncMegaService
 * reliably and asynchronously.
 */
public class AsyncMegaClientImpl {
  @ServiceClient(
     wsdlLocation="http://localhost:7001/asyncMega/AsyncMegaService?WSDL",
     serviceName="AsyncMegaService",
     portName="AsyncMegaServicePort")
  private AsyncMegaPortType port;
  @WebMethod
  public void runAsyncReliableConversation(String message) {
    AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
    apc.setProperty("message", message);
    try {
      port.startAsync(apc);
      System.out.println("start method executed.");
      port.middleAsync(apc, message );
      System.out.println("middle method executed.");
      port.finishAsync(apc, message );
      System.out.println("finish method executed.");
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }
  }
  @AsyncResponse(target="port", operation="start")
  public void onStartAsyncResponse(AsyncPostCallContext apc, String message) {
    System.out.println("-------------------");
    System.out.println("Got message " + message );
    System.out.println("-------------------");
  }
  @AsyncResponse(target="port", operation="middle")
  public void onMiddleAsyncResponse(AsyncPostCallContext apc, String message) {
    System.out.println("-------------------");
    System.out.println("Got message " + message );
    System.out.println("-------------------");
  }
  @AsyncResponse(target="port", operation="finish")
  public void onFinishAsyncResponse(AsyncPostCallContext apc, String message) {
    System.out.println("-------------------");
    System.out.println("Got message " + message );
    System.out.println("-------------------");
  }
  @AsyncFailure(target="port", operation="start")
  public void onStartAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
  }
  @AsyncFailure(target="port", operation="middle")
  public void onMiddleAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
  }
  @AsyncFailure(target="port", operation="finish")
  public void onFinishAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
  }
}

 

Using Reliable Messaging or Asynchronous Request Response With a Proxy Server

Client applications that invoke reliable Web Services or use the asynchronous request-response feature might not invoke the operation directly, but rather, use a proxy server. Reasons for using a proxy include the presence of a firewall or the deployment of the invoked Web Service to a cluster.

In this case, the WebLogic Server instance that hosts the invoked Web Service must be configured with the address and port of the proxy server. If your Web Service is deployed to a cluster, you must configure every server in the cluster.

For each server instance:

  1. Create a network channel for the protocol you use to invoke the Web Service. You must name the network channel weblogic-wsee-proxy-channel-XXX, where XXX refers to the protocol. For example, to create a network channel for HTTPS, call it weblogic-wsee-proxy-channel-https.

    2. See Configure Custom Network Channels for general information about creating a network channel.

  2. Configure the network channel, updating the External Listen Address and External Listen Port fields with the address and port of the proxy server, respectively.

 

Skip navigation bar  Back to Top Previous Next