Skip Headers
Oracle® Fusion Middleware Programming Advanced Features of JAX-RPC Web Services for Oracle WebLogic Server
11g Release 1 (10.3.6)

Part Number E13735-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Creating Buffered Web Services

This chapter describes how to create buffered WebLogic Java API for XML-based RPC (JAX-RPC) Web services.

This chapter includes the following topics:

Overview of 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 in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server:

Table 5-1 Steps to Create a Buffered Web Service

#
Step Description

1

Configure the WebLogic Server instance that hosts the buffered Web service.

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

2

Create a new JWS file, or update an existing one, that implements the buffered Web service.

Use your favorite IDE or text editor. See Programming Guidelines for the Buffered JWS File.

3

Update your build.xml file to include a call to the jwsc Ant task to compile the JWS file into a buffered Web service.

For example:

<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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server for general information about using the jwsc Ant task.

4

Recompile your JWS file by calling the appropriate target, then redeploy the Web service to the WebLogic Server.

For example:

prompt> ant build-clientService deploy-clientService

For more information about deployment, see See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

5

Create a new JWS file, or update an existing one, that implements the client Web service that invokes the buffered Web service.

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

6

Update the build.xml file that builds the client Web service.

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:

prompt> ant build-clientService deploy-clientService

For more information about deployment, see See "Deploying and Undeploying WebLogic Web Services" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.


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.

You can configure these resources manually or you can use the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Using the Configuration Wizard greatly simplifies the required configuration steps; for details, see "Configuring Your Domain For Web Services Features" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.

A domain that does not contain Web Services resources will still boot and operate correctly for non-Web services scenarios, and any Web Services scenario that does not involve asynchronous request and response. You will, however, see INFO messages in the server log indicating that asynchronous resources have not been configured and that the asynchronous response service for Web services has not been completely deployed.

If you prefer to configure the resources manually, perform the following steps.

Table 5-2 Steps to Configure Host WebLogic Server Instance Manually for the Buffered Web Service

#
Step Description

1

Invoke the Administration Console for the domain that contains the host WebLogic Server instance.

To invoke the Administration Console in your browser, enter the following URL:

http://host:port/console

where

  • host refers to the computer on which the Administration Server is running.

  • port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

See "Invoking the Administration Console" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3

Create a JMS Server.

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

See "Create JMS servers" in Oracle WebLogic Server Administration Console Help.

4

Create JMS module and define queue.

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. Be sure you specify that this JMS queue is local, typically by setting the local JNDI name. See "Create JMS system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Help.

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

Clustering Considerations:

If you are using the Web service buffering feature in a cluster, you must:

  • Create a local JMS queue, rather than a distributed queue, when creating the JMS queue.

  • Explicitly target this JMS queue to each server in the cluster.

4

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve Web Service Performance" in WebLogic Server Performance and Tuning.


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" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

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.

<taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />

<target name="build-clientService">

    <jwsc
        enableAsyncService="true"
        srcdir="src"
        destdir="${clientService-ear-dir}" >

        <jws file="examples/webservices/buffered/BufferedClientImpl.java">
           <clientgen 
             wsdl="http://${wls.hostname}:${wls.port}/buffered/BufferedService?WSDL" 
             packageName="examples.webservices.buffered"/> 

        </jws>

    </jwsc>

  </target>

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

Update the jwsc Ant task that compiles the client Web service to include a <clientgen> child element of the <jws> element so as to generate and compile the JAX-RPC stubs for the deployed BufferedService Web service. The jwsc Ant task automatically packages them in the generated WAR file so that the client Web service can immediately access the stubs. You do this because the BufferedClientImpl JWS file imports and uses one of the generated classes.