![]() ![]() ![]() ![]() ![]() ![]() |
The following sections describe how to create a buffered Web Service:
WARNING: | This feature can be implemented only for a JAX-RPC 1.1-based Web Service; you cannot implement it for a JAX-WS 2.0 Web Service. |
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.
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:
See Configuring the Host WebLogic Server Instance for the Buffered Web Service.
See Programming Guidelines for the Buffered JWS File.
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 for general information about using the jwsc
task.
prompt> ant build-mainService deploy-mainService
See Programming the JWS File That Invokes the Buffered Web Service.
build.xml
file that builds the client Web Service.See Updating the build.xml File for a Client of the Buffered Web Service.
prompt> ant build-clientService deploy-clientService
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 either configure these resources yourself, 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.
If, however, you prefer to configure the resources yourself, use the following high-level procedure which lists the tasks and then points to the Administration Console Online Help for details on performing the tasks.
See Invoking the Administration Console for instructions on the URL that invokes the Administration Console.
See Create JMS servers.
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.
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.
import javax.jws.Oneway;
import weblogic.jws.MessageBuffer;
import weblogic.jws.BufferQueue;
See the following bullets for guidelines on which JWS annotations are required.
@BufferQueue
JWS annotation to specify the JNDI name of the JMS queue used internally by WebLogic Server when it processes a buffered invoke; for example:
@BufferQueue(name="my.jms.queue")
If you do not specify this JWS annotation, then WebLogic Server uses the default Web Services JMS queue (weblogic.wsee.DefaultQueue
).
You must create both the default JMS queue and any queues specified with this annotation before you can successfully invoke a buffered operation. See Configuring the Host WebLogic Server Instance for the Buffered Web Service for details.
@MessageBuffer
JWS annotation to specify the operations of the Web Service that are buffered. The annotation has two optional attributes: retryCount
: The number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web Service implementation (default 3).retryDelay
: The amount of time that the server should wait in between retries (default 5 minutes).@MessageBuffer(retryCount=10, retryDelay="10 seconds")
You can use this annotation at the class-level to specify that all operations are buffered, or at the method-level to choose which operations are buffered.
@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
. For example:@Oneway()
public void sayHelloNoReturn(String message) {
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.
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);
}
}
}
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.
![]() ![]() ![]() |