Configuring Web Services Reliable SOAP Messaging

} }

Files Prepare Run Troubleshooting Related Topics

About the Example

This example shows how to use the reliable SOAP messaging feature by creating two WebLogic Web Services:

One whose operations can be invoked using reliable SOAP messaging (destination Web Service).
Another that invokes an operation of the first Web Service reliably (source Web Service). Note, only web services can invoke reliable services, not stand-alone Java clients.

This example shows the bare minimum of code needed to invoke a web method reliably. It covers only one-way messages, and only briefly introduces the concept of handling reliable delivery failures. For a more robust example that includes two-way messaging, more robust error reporting/handling, and WS-Security, see the examples.webservices.wsrm.security sample.

Overview of Reliable SOAP Messaging

Reliable SOAP messaging is a framework whereby an application running in one Oracle WebLogic Server instance can reliably invoke a Web Service running on another Oracle WebLogic Server instance. Reliable is defined as the ability to guarantee message delivery between the two Web Services.

WebLogic Web Services 10.3 conform to the WS-ReliableMessaging 1.1 specification (February 2007), which describes how two Web Services running on different Oracle WebLogic Server instances 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 Web Service (or client Web Service) to a destination Web Service (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.

WebLogic Web Services use WS-Policy files to enable a destination Web service to describe and advertise its reliable SOAP messaging capabilities and requirements. WS-Policy files are XML files that describe features such as the version of the WS-ReliableMessaging specification that is supported, the source Web service's retransmission interval, the destination Web Service's acknowledgment interval, and so on.

WebLogic reliable SOAP messaging works only between two Web Services. This means that you can invoke a WebLogic Web Service reliably only from another Web Service, and not from a standalone client application. This example shows how to create both types (source and destination) of Web Services

Overview of the Example

As described in the Web Service example Creating a Web Service Using JWS Metadata Annotations (listed under the Oracle WebLogic Server Examples > Examples > API> Web Services node in the Samples Viewer), this example also uses JWS annotations to specify the shape and behavior of the Web Services. See the documentation for the simple Web Service example for a full explanation of the basic JWS annotations (@WebService, @WebMethod, @SoapBinding, and @WLHttpTransport). This example describes additional JWS annotations to enable reliable SOAP messaging in the destination Web Service and to reliably invoke an operation from the source Web Service.

NOTE: Typically you deploy the source Web Service (that reliably invokes an operation) to a Oracle WebLogic Server instance that is different from the one to which you deploy the reliable destination Web Service. However, because the out-of-the-box Oracle WebLogic Server configuration includes just a single Examples server, this example is set up by default to automatically deploy both Web Services to this same server. Later instructions show how to set up a real-world example by specifying a different destination Oracle WebLogic Server instance to host the reliable destination Web Service.

The destination ReliableHelloWorld Web Service has one operation that can be invoked reliably: helloWorld. The JWS file that implements this Web Service uses the following JWS annotations in addition to the basic ones:

@Policy to specify the name of the WS-Policy file that contains the reliable SOAP messaging assertions, whether the file should be applied to the inbound (request) or outbound (response) SOAP messages, and whether the file should be attached to the WSDL file. You can specify this annotation at both the class- and method- level.
@Oneway to specify that the reliable operations are one-way and do not return any values. The methods that implement these operations must explicitly return void. All methods on a reliable service definition must be either one-way (marked with @Oneway annotation), and accessed simply from the client service by invoking <stub member variable>.<web method name>) or be accessed from the client service via the async request-response feature.

The source ReliableClient Web Service has one operation for invoking the helloWorld operation of the ReliableHelloWorld Web Service reliably: callHelloWorld. The JWS file that implements the ReliableClient Web Service uses the following JWS annotation in addition to the basic ones:

@ServiceClient to specify the service name and port name of the reliable Web Service being invoked. You specify this method at the field-level; the data type of the field must be the JAX-RPC port type of the reliable Web Service being invoked. The PortType class for the reliable Web Service is generated by the clientgen Ant task and imported into the ReliableClient Web Service. The field with the given port type is often called the 'Stub' used for invoking the destination service. Note all port type classes are generated such that they implement the javax.xml.rpc.Stub interface (hence the reason they are sometimes called stubs)

To generate the two Web Services from their respective JWS files, use the jwsc WebLogic Web Service Ant task, as shown in the build.xml file; the build.reliable.service target generates the reliable Web Service and the build.reliable.client target creates the source Web Service. The jwsc Ant task compiles the JWS files, and generates the additional files needed to implement a standard Java EE Web Service: the Web Service deployment descriptors, the WSDL file, data-binding components, and so on. The Ant task automatically generates all the components into an Enterprise Application directory structure, which you can then deploy to Oracle WebLogic Server. This example uses the wldeploy WebLogic Ant task to deploy the Web Service.

The build.reliable.client target also shows how first execute the clientgen Ant task to generate the JAX-RPC stubs for the destination ReliableHelloWorldService Web Service, compile the generated Java source files, and then use the classpath attribute of jwsc to specify the directory that contains these classes so that the ReliableClientimpl.java class can find them. Remember that this JWS file imports and uses the JAX-RPC stubs for the ReliableHelloWorldService.

The Client.java class is a standalone Java application that invokes the callHelloWorld operation of the source Web Service. It uses the JAX-RPC Stubs generated by the clientgen WebLogic Web Service Ant task, based on the WSDL of the ReliableClient Web Service. The client target of the build.xml file shows how to run clientgen and compile all the generated Java files, as well as the Client.java application.

Files Used in the Example

Directory Location:

MW_HOME/wlserver_10.3/samples/server/examples/src/examples/webservices/reliable/

(where MW_HOME is the directory containing your Oracle WebLogic Server installation)

File Click source files to view code.	Description
ReliableClientImpl.java	JWS file that implements the source Web Service that reliably invokes the sayHello operation of the ReliableHelloWorldService Web Service. This JWS file uses the @ServiceClient annotation to specify the Web Service it invokes reliably.
ReliableHelloWorldImpl.java	JWS file that implements the reliable destination Web Service. This JWS file uses the @Policy annotation to specify a WS-Policy file that contains reliable SOAP messaging assertions.
Client.java	Standalone Java client application that invokes the source WebLogic Web Service, that in turn reliably invokes an operation of the ReliableHelloWorldService Web Service.
build.xml	Ant build file that contains targets for building and running the example.

Prepare the Example

Prerequisites

Before working with this example:

Install Oracle WebLogic Server, including the examples.
Start the Examples server.
Set up your environment.

Configure the Destination Oracle WebLogic Server Instance (Optional)

The out-of-the-box default configuration for this example deploys both the source and destination Web Services to the Examples server. You can use this default configuration to see how the example works, but it does not reflect a real-life example of using reliable SOAP messaging in which the source Web Service is deployed to a Oracle WebLogic Server different from the one that hosts the destination Web Service. This section describes how to set up the real-life example.

You can use the Configuration Wizard to create a new domain to host the destination reliable service. It is not strictly required that a new domain is created in order to host a reliable service separate from the client service that invokes it. You could create a new managed server within an existing domain (e.g. the Examples domain) and configure that server with the resources required by reliable messaging (as described in the online documentation). However this example assumes the creation of a new domain (or extending of an existing domain) because it is simpler than defining and configuring a new managed server.

Follow these steps if you want to deploy the reliable destination Web Service to a different Oracle WebLogic Server:

If the Oracle WebLogic Server domain to which you want to deploy the reliable Web Service does not exist, use the Configuration Wizard to create it. Create a domain for hosting Oracle WebLogic Server only, and accept all defaults (other than domain name, administrator user name/password, of course).
Extend the domain you picked (or just created) using the Configuration Wizard, and applying the wls_webservice.jar template. This template will create the necessary resources for hosting a reliable web service.
Edit the build.xml file and update the following property definitions so that the reliable Web Service is later deployed to the destination Oracle WebLogic Server:

<property name="wls.service.server" value="destinationServerName" />
<property name="wls.service.hostname" value="destinationHost" />
<property name="wls.service.port" value="destinationPort" />
<property name="wls.service.username" value="destinationUser" />
<property name="wls.service.password" value="destinationPassword" />

Substitute the italicized terms in the preceding properties with the actual values for your destination Oracle WebLogic Server. The default out-of-the-box build.xml sets these properties to the Examples server.

Build and Deploy the Example

Change to the SAMPLES_HOME\server\examples\src\examples\webservices\reliable directory, where SAMPLES_HOME refers to the main Oracle WebLogic Server examples directory, such as c:\Oracle\Middleware\wlserver_10.3\samples.
Execute the following command:

prompt> ant build

This command compiles and stages the example. In particular it compiles both the source and destination Web Services. It also compiles the standalone Client application that invokes the source Web Service, which in turn invokes the reliable destination Web Service. This is the application you the user invokes to see how the reliable SOAP messaging works.
Execute the following command:

prompt> ant deploy

This command deploys, by default, both the source and destination Web Services to the wl_server domain of your Oracle WebLogic Server installation. If you have configured a different destination Oracle WebLogic Server and updated the build.xml file accordingly, then the reliable Web Service is deployed to this destination server.

Run the Example

To run the example, follow these steps:

Complete the steps in the "Prepare the Example" section.
In your development shell, run the Client Java application by using the following command from the main example directory (SAMPLES_HOME\server\examples\src\examples\webservices\reliable):

prompt> ant run

This command runs the standalone Client application that invokes the source Web Service, which in turn invokes the reliable destination Web Service.
After building and running the example, you can view the WSDL of the ReliableHelloWorldService Web Service by browsing to the following URL in your Web browser:
http://host:port/ReliableHelloWorld/ReliableHelloWorld?WSDL
Where:
- host refers to the machine on which the destination Oracle WebLogic Server is running.
- port refers to port on which the destination Oracle WebLogic Server is listening
To verify that the reliability aspect of the example is indeed working, stop the destination Oracle WebLogic Server, and then rerun the Client application. When you restart the destination Oracle WebLogic Server and the reliable Web Service is deployed, you should see that the operation is invoked also automatically invoked.

Check the Output

If your example runs successfully, you will get the following message in the command shell from which you ran the Client application:

Buildfile: build.xml

run:
     [java] Beginning webservices.reliable.Client...
     [java]  Everything worked!
     [java] End webservices.reliable.Client...

BUILD SUCCESSFUL
       Total time: 6 seconds

You will get the following message in the command window from which you started the destination Oracle WebLogic Server (that hosts the reliable destination Web Service):


Calling ReliableHelloWorldService.helloWorld
Invoked the ReliableHelloWorld.helloWorld operation reliably.
Hello World Hi there!

Troubleshooting

General Troubleshooting Tips for Examples