8 Using Web Services Reliable Messaging

This chapter describes web services reliable messaging for WebLogic Java API for XML-based RPC (JAX-RPC) web services.

This chapter includes the following sections:

Note:

Web service reliable messaging requires the use of asynchronous request-response feature of WebLogic web services. Before proceeding, you should familiarize yourself with the concepts described in Chapter 7, "Invoking a Web Service Using Asynchronous Request-Response."

Overview of Web Service Reliable Messaging

Web service reliable messaging is a framework that enables an application running on one application server to reliably invoke a web service running on another application 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 in the presence of software component, system, or network failures.

Note:

Web services reliable messaging works between any two application servers that implement the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf. In this document, however, it is assumed that the two application servers are WebLogic Server instances.

Web services reliable messaging is not supported with the JMS transport feature.

WebLogic web services conform to the WS-ReliableMessaging specification (June 2007) at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf, which describes how two web services running on different application servers can communicate reliably. 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.

Table 8-1 Delivery Assurances for Reliable Messaging

Delivery Assurance Description

At Most Once

Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all.

At Least Once

Every message is delivered at least once. It is possible that some messages are delivered more than once.

Exactly Once

Every message is delivered exactly once, without duplication.

In Order

Messages are delivered in the order that they were sent. This delivery assurance can be combined with one of the preceding three assurances.


Note:

Web services reliable messaging requires the use of asynchronous messages. Clients cannot invoke a reliable service synchronously. When invoking a reliable stub method, you must use the async signature—for example, xyzAsync() instead of xyz(). For clients that create SOAP messages directly, the request message is created with non-anonymous ReplyTo address.

You cannot set ReplyTo to the anonymous URI. Any attempt to invoke an operation on a JAX-RPC-based reliable service (either by invoking the sync stub signature or sending a request with anonymous ReplyTo) will result in a runtime exception.

This document 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. See the WS-ReliableMessaging specification for detailed documentation about the architecture of web service reliable messaging (see http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf).

Using WS-Policy to Specify Reliable Messaging Policy Assertions

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 files are XML files that describe features such as the version of the supported WS-ReliableMessaging specification and quality of service requirements. The WS-Policy specification (http://www.w3.org/TR/ws-policy/) provides a general purpose model and syntax to describe and communicate the policies of a web service.

WebLogic Server includes pre-packaged WS-Policy files that contain typical reliable messaging assertions, as described in Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging." If the pre-packaged WS-Policy files 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. See "Web Service Reliable Messaging Policy Assertion Reference" in the WebLogic Web Services Reference for Oracle WebLogic Server for reference information about the reliable messaging policy assertions.

Managing the Life Cycle of the Reliable Message Sequence

The following figure shows a one-way reliable message exchange.

Figure 8-1 Web Service Reliable Message Exchange

Description of Figure 8-1 follows
Description of ''Figure 8-1 Web Service Reliable Message Exchange''

A reliable message sequence is used to track the progress of a set of messages that are exchanged reliably between an RM source and RM destination. A sequence can be used to send zero or more messages, and is identified by a string identifier. This identifier is used to reference the sequence when using reliable messaging.

The web service client application sends a message for reliable delivery which is transmitted by the RM source to the RM destination. The RM destination acknowledges that the reliable message has been received and delivers it to the web service application. The message may be retransmitted by the RM source until the acknowledgement is received.

A web service client sends messages to a target web service by invoking methods on a JAX-RPC stub. The stub is associated with the port type of the reliable web service and represents a programmatic interface to that service. WebLogic stores the identifier for the reliable message sequence within this stub. This causes the reliable message sequence to be connected to a single JAX-RPC stub. All messages that are sent using a given stub will use the same reliable messaging sequence, regardless of the number of messages that are sent using the stub. The JAX-RPC stub is created by the <clientgen> child element of the "jwsc" Ant task.

Because WebLogic Server retains resources associated with the reliable sequence, it is recommended that you take steps to release these resources in a timely fashion. WebLogic Server provides a utility class, weblogic.wsee.reliability.WsrmUtils, for use with the web service reliable messaging. Use this class to perform common tasks such as set configuration options, get the sequence id, and terminate a reliable sequence.

Under normal circumstances, a reliable sequence should be retained until all messages have been sent and acknowledged by the RM destination. To facilitate the timely and proper termination of a sequence, it is recommended that you identify the final message in a reliable message sequence. Doing so indicates you are done sending messages to the RM destination and that WebLogic Server can begin looking for the final acknowledgement before automatically terminating the reliable sequence. Indicate the final message using the weblogic.wsee.reliability.WsrmUtils.setFinalMessage() method, passing the JAX-RPC stub being used to send messages to the RM destination.

When you identify a final message, after all messages up to and including the final message are acknowledged, the reliable message sequence is terminated, and all resources are released. Otherwise, the sequence is terminated automatically after the configured sequence expiration period is reached.

Although not recommended, you can terminate the sequence reliable message sequence regardless of whether all messages have been acknowledged using the terminateSequence() method. Once issued, no further reliable messages can be sent on this stub.

Note:

The JAX-RPC stub is not fully initialized until shortly after the first method is invoked on the reliable web service. When the first method is invoked, the RM source sends a CreateSequence message to the RM destination requesting that the RM destination create and register the reliable sequence. The RM destination, at some later time, responds with the ID for the newly created sequence. Until this response ID is received, the RM source cannot have any further communication with the RM destination and the JAX-RPC stub representing the target service at the RM destination cannot be used.

You cannot perform operations on the reliable message sequence until it is fully initialized; otherwise an error is returned. Use the weblogic.wsee.reliability.WsrmUtils.waitForSequenceInitialization() method to monitor whether or not the reliable message sequence has been initialized. Once the reliable sequence is initialized, this method returns the ID of the sequence.

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 table summarizes the steps to create a reliable web service, as well as a client web service that invokes an operation of the reliable web service. The procedure describes 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 describes how to configure the source and destination WebLogic Server instances.

Table 8-2 Steps to Create and Invoke a Reliable Web Service

#
Step Description

1

Configure the destination and source WebLogic Server instances.

You will deploy the reliable web service to the destination WebLogic Server instance. For information about configuring the destination WebLogic Server instance, see Configuring the Destination WebLogic Server Instance.

You will deploy the client web service that invokes the reliable web service to the source WebLogic Server instance. For information about configuring the source WebLogic Server instance, see Configuring the Source WebLogic Server Instance.

2

Create the WS-Policy file. (Optional)

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. For details about creating your own WS-Policy file, see Creating the Web Service Reliable Messaging WS-Policy File.

This step is not required if you plan to use one of the WS-Policy files that are included in WebLogic Server; see Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging," for more information.

3

Create or update the JWS file that implements the reliable web service.

This web service will be deployed to the destination WebLogic Server instance. See Programming Guidelines for the Reliable JWS File.

4

Update the build.xml file that is used to compile the reliable web services.

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.

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

5

Compile and deploy the reliable JWS file.

Compile the reliable JWS file by calling the appropriate target and deploy to the destination WebLogic Server. For example:

prompt> ant build-mainService deploy-mainService

6

Configure the reliable web service.

Configure the reliable messaging options for the reliable web service using the WebLogic Server Administration Console. See Configuring Reliable Messaging for a Reliable Web Service.

7

Create or update the JWS file that implements the client web service.

This service invokes the reliable web service and will be deployed to the source WebLogic Server. See Programming Guidelines for the JWS File That Invokes a Reliable Web Service.

8

Update the build.xml file that is used to compile the client web service.

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

9

Compile and deploy the client JWS file.

Compile your client JWS file by calling the appropriate target and deploy to the source WebLogic Server. For example:

prompt> ant build-clientService deploy-clientService

Each of these steps is described in more detail in the following sections.

In addition, the following advanced topics are discussed:

Prerequisites

It is assumed that you have completed the following tasks:

  • You have created the destination and source WebLogic Server instances.

  • You have set up an Ant-based development environment for each environment.

  • You have working build.xml files that you can edit, for example, to add targets for running the jwsc Ant task and deploying the generated reliable web service.

For more information, see "Developing JAX-RPC Web Services".

Configuring the Destination WebLogic Server Instance

To configure the WebLogic Server instance on which the reliable web service is deployed, configure the JMS and store and forward (SAF) resources.

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

Note:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Understanding the 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 8-3 Steps to Configure the Destination WebLogic Server Instance Manually

#
Step Description

1

Invoke the WebLogic Server Administration Console for the domain that contains the destination WebLogic Server.

To invoke the WebLogic Server 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 Understanding WebLogic Web Services for Oracle WebLogic Server.

2

Create persistent file store. (Optional)

Optionally create a persistent store (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.

See "Create file stores" in Oracle WebLogic Server Administration Console Online Help.

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

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 system modules" and "Create queues in a system module" in Oracle WebLogic Server Administration Console Online Help.

Clustering Considerations:

If you are using the web service reliable messaging 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.

5

Create a store and forward (SAF) agent.

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

When you create the SAF agent:

  • Set the Agent Type field to Both to enable both sending and receiving agents.

  • Be sure to target the SAF agent by clicking Next on the first assistant page to view the Select targets page (rather than clicking Finish).

Clustering Considerations:

  • If you are using reliable messaging within a cluster, you must target the SAF agent to the cluster.

See "Create Store-and-Forward agents" in Oracle WebLogic Server Administration Console Online Help.

6

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve web service Performance" in Tuning Performance of Oracle WebLogic Server.

7

Restart the server.

In order for the configuration changes to take effect, you must restart the server, as described in "Starting and Stopping Servers" in Administering Server Startup and Shutdown for Oracle WebLogic Server.


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.

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

Notes:

Alternatively, you can use WLST to configure the resources. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Understanding the 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 8-4 Steps to Configure the Source WebLogic Server Instance

#
Step Description

1

Invoke the WebLogic Server Administration Console for the domain that contains the source WebLogic Server.

To invoke the WebLogic Server 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 Understanding WebLogic Web Services for Oracle WebLogic Server.

2

Create persistent file store. (Optional)

Optionally 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, or the default store that always exists, if you do not want to create a new one.

See "Create file stores" in Oracle WebLogic Server Administration Console Online Help.

3

Create as store and forward (SAF) agent.

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

When you create the SAF agent, set the Agent Type field to Both to enable both sending and receiving agents.

See "Create Store-and-Forward agents" in Oracle WebLogic Server Administration Console Online Help.

6

Tune your domain environment, as required. (Optional)

Review "Tuning Heavily Loaded Systems to Improve web service Performance" in Tuning Performance of Oracle WebLogic Server.

7

Restart the server.

In order for the configuration changes to take effect, you must restart the server, as described in "Starting and Stopping Servers" in Administering Server Startup and Shutdown for Oracle WebLogic Server.


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.

WebLogic Server includes pre-packaged WS-Policy files that contain typical reliable messaging assertions that you can use if you do not want to create your own WS-Policy file. The pre-packaged WS-Policy files are listed in the following table.

Note:

The DefaultReliability.xml and LongRunningReliability.xml files are deprecated in this release. Use of the DefaultReliability1.1.xml, Reliability1.1_SequenceTransportSecurity, or Reliability1.0_1.1.xml file is recommended and required to comply with the 1.1 version of the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf.

Table 8-5 Pre-packaged WS-Policy Files

Pre-packaged WS-Policy File Description
DefaultReliability1.1.xml

Specifies policy assertions related to quality of service. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. See DefaultReliability1.1.xml (WS-Policy File).

Reliability1.1_SequenceTransportSecurity

Specifies policy assertions related to transport-level security and quality of service. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. See Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File).

Reliability1.0_1.1.xml

Combines 1.1 and 1.0 WS Reliable Messaging policy assertions. This sample relies on smart policy selection to determine the policy assertion that is applied at runtime. See Reliability1.0_1.1.xml (WS-Policy.xml File)

DefaultRelibility.xml

Deprecated. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf. In this release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

Specifies typical values for the reliable messaging policy assertions, such as inactivity timeout of 10 minutes, acknowledgement interval of 200 milliseconds, and base retransmission interval of 3 seconds. See DefaultReliability.xml (WS-Policy File) [Deprecated].

LongRunningReliability.xml

Deprecated. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 for long running processes. In this release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

Similar to the preceding default reliable messaging WS-Policy file, except that it specifies a much longer activity timeout interval (24 hours.) See LongRunningReliability.xml (WS-Policy File) [Deprecated].


You can use one of the pre-packaged reliable messaging WS-Policy files included in WebLogic Server; these files are adequate for most use cases. You cannot modify the pre-packaged files. If the values do not suit your needs, you must create a custom WS-Policy file. The following sections describe how to create a custom WS-Policy file.

Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.1

This section describes how to create a custom WS-Policy file that contains web service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion Version 1.1 at http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.pdf. In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

The root element of the WS-Policy file is <Policy> and it should include the following namespace declaration:

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

You wrap all web service reliable messaging policy assertions inside of a <wsrmp:RMAssertion> element. This element should include the following namespace declaration for using web service reliable messaging policy assertions:

<wsrmp:RMAssertion
   xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"> 

The following table lists the web service reliable messaging assertions that you can specify in the WS-Policy file. The order in which the assertions appear is important. You can specify the following assertions; the order they appear in the following list is the order in which they should appear in your WS-Policy file:

Table 8-6 Web Service Reliable Messaging Assertions (Version 1.1)

Assertion Description
<wsrmp:SequenceSTR>

To secure messages in a reliable sequence, the runtime will use the wsse:SecurityTokenReference that is referenced in the CreateSequence message. You can only specify one security assertion; that is, you can specify wsrmp:SequenceSTR or wsrmp:SequenceTransportSecurity, but not both.

<wsrmp:SequenceTransportSecurity>

To secure messages in a reliable sequence, the runtime will use the SSL transport session that is used to send the CreateSequence message. This assertion must be used in conjunction with the sp:TransportBinding assertion that requires the use of some transport-level security mechanism (for example, sp:HttpsToken). You can only specify one security assertion; that is, you can specify wsrmp:SequenceSTR or wsrmp:SequenceTransportSecurity, but not both.

<wsrm:DeliveryAssurance>

Delivery assurance (or quality of service) of the web service. Valid values are AtMostOnce, AtLeastOnce, ExactlyOnce, and InOrder. You can set one of the delivery assurances defined in the following table. If not set, the delivery assurance defaults to ExactlyOnce.


The following example shows a simple web service reliable messaging WS-Policy file:

<?xml version="1.0"?>

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsrmp:RMAssertion
         xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
    <wsrmp:SequenceTransportSecurity/>
    <wsrmp:DeliveryAssurance>
      <wsp:Policy>
        <wsrmp:ExactlyOnce/>
      </wsp:Policy>
    </wsrmp:DeliveryAssurance>
  </wsrmp:RMAssertion>
</wsp:Policy>

For more information about Reliable Messaging policy assertions in the WS-Policy file, see "Web Service Reliable Messaging Policy Assertion Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

Creating a Custom WS-Policy File Using WS-ReliableMessaging Policy Assertions Version 1.0 (Deprecated)

This section describes how to create a custom WS-Policy file that contains web service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion Version 1.0 at http://schemas.xmlsoap.org/ws/2005/02/rm/WS-RMPolicy.pdf.

Note:

In the current release, many of the reliable messaging policy assertions are managed through JWS annotations or configuration.

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 at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf. The assertions that use the beapolicy: namespace are WebLogic-specific. See "Web Service Reliable Messaging Policy Assertion Reference" in the WebLogic Web Services Reference for Oracle WebLogic Server for details.

The following table lists the web service reliable messaging assertions that you can specify in the WS-Policy file. All web service reliable messaging assertions are optional, so only set those whose default values are not adequate. The order in which the assertions appear is important. You can specify the following assertions; the order they appear in the following list is the order in which they should appear in your WS-Policy file,

Table 8-7 Web Service Reliable Messaging Assertions (Version 1.0)

Assertion Description
<wsrm:InactivityTimeout>

Number of milliseconds, specified with the Milliseconds attribute, which defines an inactivity interval. After this amount of time, if the destination endpoint has not received a message from the source endpoint, the destination endpoint may consider the sequence to have terminated due to inactivity. The same is true for the source endpoint. By default, sequences never timeout.

<wsrm:BaseRetransmissionInterval>

Interval, in milliseconds, that the source endpoint waits after transmitting a message and before it retransmits the message if it receives no acknowledgment for that message. Default value is set by the SAF agent on the source endpoint's WebLogic Server instance.

<wsrm:ExponentialBackoff>

Specifies that the retransmission interval will be adjusted using the exponential backoff algorithm. This element has no attributes.

<wsrm:AcknowledgmentInterval>

Maximum interval, in milliseconds, in which the destination endpoint must transmit a stand-alone acknowledgement. The default value is set by the SAF agent on the destination endpoint's WebLogic Server instance.

<beapolicy:Expires>

Amount of time after which the reliable web service expires and does not accept any new sequence messages. The default value is to never expire. This element has a single attribute, Expires, whose data type is an XML Schema duration type (see http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#duration). For example, if you want to set the expiration time to one day, use the following: <beapolicy:Expires Expires="P1D" />.

<beapolicy:QOS>

Delivery assurance level, as described in Table 8-9. The element has one attribute, QOS, which you set to one of the following values: AtMostOnce, AtLeastOnce, or ExactlyOnce. You can also include the InOrder string to specify that the messages be in order. The default value is ExactlyOnce InOrder. This element is typically not set.


The following example shows a simple web service reliable messaging WS-Policy file:

<?xml version="1.0"?>

<wsp:Policy
   xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
   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:BaseRetransmissionInterval
      Milliseconds="500" />
   <wsrm:ExponentialBackoff />
   <wsrm:AcknowledgementInterval
      Milliseconds="2000" />

 </wsrm:RMAssertion>

</wsp:Policy>

For more information about Reliable Messaging policy assertions in the WS-Policy file, see "Web Service Reliable Messaging Policy Assertion Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

Using Multiple Policy Alternatives

You can configure multiple policy alternatives—also referred to as smart policy alternatives—for a single web service by creating a custom policy file. At runtime, WebLogic Server selects which of the configured policies to apply. It excludes policies that are not supported or have conflicting assertions and selects the appropriate policy, based on your configured preferences, to verify incoming messages and build the response messages.

The following example provides an example of a security policy that supports both 1.1and 1.0 WS-Reliable Messaging. Each policy alternative is enclosed in a <wsp:All> element.

Note:

The 1.0 web service reliable messaging assertions are prefixed by wsrmp10.
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
  <wsp:ExactlyOne>
    <wsp:All> 
      <wsrmp10:RMAssertion
       xmlns:wsrmp10="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
        <wsrmp10:InactivityTimeout Milliseconds="1200000"/>
        <wsrmp10:BaseRetransmissionInterval Milliseconds="60000"/>
        <wsrmp10:ExponentialBackoff/>
        <wsrmp10:AcknowledgementInterval Milliseconds="800"/>
      </wsrmp10:RMAssertion>
    </wsp:All>
    <wsp:All>
      <wsrmp:RMAssertion
           xmlns:wsrmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702">
        <wsrmp:SequenceSTR/>
        <wsrmp:DeliveryAssurance>
          <wsp:Policy>
            <wsrmp:AtMostOnce/>
          </wsp:Policy>
        </wsrmp:DeliveryAssurance>
      </wsrmp:RMAssertion>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

For more information about multiple policy alternatives, see "Smart Policy Selection" in "Configuring Message-Level Security" in Securing WebLogic Web Services for Oracle WebLogic Server.

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.

Table 8-8 JWS Annotations for Reliable Messaging

Annotation Description
@weblogic.jws.Policy

Required. Specifies that the web service has a WS-Policy file attached to it that contains reliable messaging assertions. See Using the @Policy Annotation.

@javax.jws.Oneway

Required only if you invoke the reliable web service operation synchronously (that is, you are not using the asynchronous request-response feature). See Using the @Oneway Annotation.

@weblogic.jws.BufferQueue

Optional. Specifies the JNDI name of the JMS queue which WebLogic Server uses to store reliable messages internally. See Using the @BufferQueue Annotation.

@weblogic.jws.ReliabilityBuffer

Optional. Specifies the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the web service implementation and the amount of time that the server should wait in between retries. See Using the @ReliabilityBuffer Annotation


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 {

  private static String onewaySavedInput = null;

/**
 * A one-way helloWorld method that saves the given string for later 
 * concatenation to the end of the message passed into helloWorldReturn.
 */
  @WebMethod()
  @Oneway() 
  @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds") 

  public void helloWorld(String input) {
    System.out.println(" Hello World " + input);
    onewaySavedInput = input;
   }

/**
 * This echo method concatenates the saved message from helloWorld 
 * onto the end of the provided message, and returns it.
 */
  @WebMethod()
  @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds") 

  public String echo(String input2) {
    System.out.println(" Hello World " + input2 + onewaySavedInput);
    return input + onewaySavedInput;
  }
}

In the example, the custom ReliableHelloWorldPolicy.xml policy 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. For information about the pre-packaged policies available and creating a custom policy, see Creating the Web Service Reliable Messaging WS-Policy 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 re-delivery if, for example, the transaction is rolled back or otherwise does not commit.

The echo() method has been marked with the @WebMethod and JWS annotation, which means it is a public operation called echo. Because of the @Policy annotation, the operation can be invoked reliably. It uses the same reliability buffer configuration as the helloWorld() method.

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. WebLogic Server delivers a set of pre-packaged WS-Policy files, as described in Appendix A, "Pre-Packaged WS-Policy Files for Reliable Messaging."

Follow the following guidelines 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:

    • If you have created your own WS-Policy file, specify its location relative to the JWS file. For example:

      @Policy(uri="ReliableHelloWorldPolicy.xml",
                direction=Policy.Direction.both,
                attachToWsdl=true)
      

      In this example, the ReliableHelloWorldPolicy.xml file is located in the same directory as the JWS file.

    • To specify one of the pre-packaged WS-Policy files or a WS-Policy file that is packaged in a shared Java EE library, use the policy: prefix along with the name and path of the policy file. This syntax tells the jwsc Ant task at build-time not to look for an actual file on the file system, but rather, that the web service will retrieve the WS-Policy file from WebLogic Server at the time the service is deployed.

      Note:

      Shared Java EE libraries are useful when you want to share a WS-Policy file with multiple web services that are packaged in different Enterprise applications. As long as the WS-Policy file is located in the META-INF/policies or WEB-INF/policies directory of the shared Java EE library, you can specify the policy file in the same way as if it were packaged in the same archive at the web service. See "Creating Shared Java EE Libraries and Optional Packages" in Developing Applications for Oracle WebLogic Server for information about creating libraries and setting up your environment so the web service can locate the policy files.
    • To specify that the policy file is published on the Web, use the http: prefix along with the URL, as shown in the following example:

      @Policy(uri="http://someSite.com/policies/mypolicy.xml"
              direction=Policy.Direction.both,
              attachToWsdl=true)
      
  • By default, WS-Policy files are applied to both the request (inbound) and response (outbound) SOAP messages. You can change this default behavior with the direction attribute by setting the attribute to Policy.Direction.inbound or Policy.Direction.outbound.

  • You can specify whether the web service requires the operations to be invoked reliably and have the responses delivered reliably using the wsp:optional attribute within the policy file specified by uri.

    If the optional attribute is set to false for outbound on any operation, then:

    If the optional attribute is set to true for outbound on all operations, then:

    • The client is not required to provide an offer sequence.

    • Responses will be sent reliably if the client provides an offer sequence; otherwise, responses will be sent non-reliably.

  • Set the attachToWsdl 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.

For more information about the @Policy annotation, see "weblogic.jws.Policy" in WebLogic Web Services Reference for Oracle WebLogic Server.

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 you must annotate the implementing method 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 Chapter 7, "Invoking a Web Service Using Asynchronous Request-Response," and Chapter 11, "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 WebLogic Server Administration Console.

For more information about the @BufferQueue annotation, see "weblogic.jws.BufferQueue" in WebLogic Web Services Reference for Oracle WebLogic Server.

Using the @ReliabilityBuffer Annotation

Use the @ReliabilityBuffer annotation to specify the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the web service implementation and the amount of time that the server should wait in between retries.

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:

  • seconds

  • minutes

  • hours

  • days

  • years

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")

The retry count and delay default to 3 and 5 seconds, respectively.

For more information about the @ReliabilityBuffer annotation, see "weblogic.jws.ReliabilityBuffer" in WebLogic Web Services Reference for Oracle WebLogic Server.

Configuring Reliable Messaging for a Reliable Web Service

If necessary, you can edit the reliable message configuration options for a reliable web service that are stored in the weblogic-webservices.xml descriptor by updating the application deployment plan. The deployment plan associates new values with specific locations in the descriptors for your application. At deployment time, a deployment plan is merged with the descriptors in the application by applying the values in its variable assignments to the locations in the application descriptors to which the variables are linked.

The following table summarizes the reliable messaging options that can be configured for the reliable web service.

Table 8-9 Configuration Options for Reliable Messaging

Configuration Option Description

Customize Reliable Message Configuration

Flag that specifies whether you want to customize the reliable message configuration defined in the web service descriptor or deployment plan at the web service endpoint level. This flag is available only when configuring reliable messaging at the web service endpoint level If not checked, the reliable message configuration specified for the WebLogic Server is used.

Note: This flag does not reflect the configuration of Reliable Messaging in other forms, such as, WS-RM policy directly specified in the WSDL.

Base Retransmission Interval

Interval of time that must pass before a message is retransmitted to the RM destination.

If the source endpoint does not receive an acknowledgement for a given message within the specified interval, the source endpoint retransmits the message. The source endpoint can modify this retransmission interval at any point during the lifetime of the sequence of messages.

This element can be used in conjunction with the Retransmission Exponential Backoff element to specify the algorithm that is used to adjust the retransmission interval.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT3S (3 seconds).

Enable Retransmission Exponential Backoff

Flag that specifies whether the message retransmission interval will be adjusted using the exponential backoff algorithm.

This element is used in conjunction with the Base Retransmission Interval element. If a destination endpoint does not acknowledge a sequence of messages for the time interval specified by the Base Retransmission Interval, the exponential backoff algorithm is used for timing successive retransmissions by the source endpoint, should the message continue to go unacknowledged.

The exponential backoff algorithm specifies that successive retransmission intervals should increase exponentially, based on the base retransmission interval. For example, if the base retransmission interval is 2 seconds, and the exponential backoff element is set, successive retransmission intervals if messages continue to go unacknowledged are 2, 4, 8, 16, 32, and so on.

This value defaults to false, the same retransmission interval is used in successive retries; the interval does not increase exponentially.

Acknowledgement Interval

Maximum interval during which the destination endpoint must transmit a stand-alone acknowledgement.

A destination endpoint can send an acknowledgement on the return message immediately after it has received a message from a source endpoint, or it can send one separately as a stand-alone acknowledgement. If a return message is not available to send an acknowledgement, a destination endpoint may wait for up to the acknowledgement interval before sending a stand-alone acknowledgement. If there are no unacknowledged messages, the destination endpoint may choose not to send an acknowledgement.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT0.2S (200 milliseconds).

Inactivity Timeout

Inactivity interval. If, during the inactivity timeout interval, an endpoint (the RM source or destination) has not received messages application or control messages, the endpoint may consider the RM sequence to have been terminated due to inactivity.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT600S (600 seconds).

Sequence Expiration

Expiration time for a sequence regardless of activity.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P1D (1 day).

Buffer Retry Count

Number of times to retry a reliable request. This value defaults to 3.

Buffer Retry Delay

Amount of time to wait before retrying a reliable request.

The retry attempts are between the client's request message on the JMS queue and delivery of the message to the web service implementation.

The value specified must be a positive value and conform to the XML schema duration lexical format, PnYnMnDTnHnMnS, where nY specifies the number of years, nM specifies the number of months, nD specifies the number of days, T is the date/time separator, nH specifies the number of hours, nM specifies the number of minutes, and nS specifies the number of seconds. This value defaults to P0DT5S (5 seconds).


You can set the reliable messaging configuration options using the WebLogic Server Administration Console or WLST, as described in the following sections.

Using the Administration Console

To configure reliable messaging for the web service endpoint using the WebLogic Server Administration Console:

  1. Invoke the WebLogic Server Administration Console, as described in "Invoking the Administration Console" in Understanding WebLogic Web Services for Oracle WebLogic Server.

  2. In the left navigation pane, select Deployments.

  3. Click the name of the web service in the Deployments table.

  4. Select the Configuration tab, then the Ports tab.

  5. Click the name of the web service endpoint in the Ports table.

  6. Select the Reliable Message tab.

  7. Click Customize Reliable Message Configuration and follow the instructions to save the deployment plan, if required.

  8. Set the reliable messaging properties, as required.

  9. Click Save.

Using WLST

For a complete description and example of using WLST to update an application's deployment plan to configure reliable messaging, see "Updating the Deployment Plan" in Understanding the WebLogic Scripting Tool.

For your reference, the following table summarizes the XPath values for the WS-RM configuration options.

Table 8-10 WS_RM Configuration Variable Names and XPath Values

Configuration Option Example Variable Name XPath Value

Inactivity Timeout

ReliabilityConfig_
InactivityTimeout
/weblogic-webservices/webservice-description/
[webservice-description-name="
service_name"]/port-component/
[port-component-name="port_name"]
/reliability-config/inactivity-timeout

Base Retransmission Interval

ReliabilityConfig_
BaseRetransmission
Interval
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/base-retransmission-interval

Retransmission Exponential Backoff

ReliabilityConfig_
Retransmission
ExponentialBackoff
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]/reliability-
config/retransmission-exponential-backoff

Acknowledgement Interval

ReliabilityConfig_
AcknowledgementInterval
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/acknowledgement-interval

Sequence Expiration

ReliabilityConfig_
SequenceExpiration
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/sequence-expiration

Buffer Retry Count

ReliabilityConfig_
BufferRetryCount
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-count

Buffer Retry Delay

ReliabilityConfig_
BufferRetryDelay
/weblogic-webservices/webservice-description/
[webservice-description-name=
"service_name"]/port-component/
[port-component-name="port-name"]
/reliability-config/buffer-retry-delay

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.

package examples.webservices.reliable;

import java.rmi.RemoteException;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.rpc.Stub;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.ServiceClient; 
import weblogic.jws.ReliabilityErrorHandler; 

import weblogic.jws.AsyncFailure;
import weblogic.jws.AsyncResponse;

import examples.webservices.reliable.ReliableHelloWorldPortType; 

import weblogic.wsee.reliability.ReliabilityErrorContext; 
import weblogic.wsee.reliability.ReliableDeliveryException; 
import weblogic.wsee.reliability.WsrmUtils; 

@WebService(name="ReliableClientPortType",
            serviceName="ReliableClientService")

@WLHttpTransport(contextPath="ReliableClient",
                 serviceUri="ReliableClient",
                 portName="ReliableClientServicePort")

public class ReliableClientImpl
{
  private static String responseMessage = null;

  @ServiceClient( 
     serviceName="ReliableHelloWorldService", 
     portName="ReliableHelloWorldServicePort") 

  private ReliableHelloWorldPortType port; 

  @WebMethod
  public void callHelloWorld(String input, String input2, String serviceUrl)
     throws RemoteException {

    ((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl); 

    port.helloWorld(input); 

    System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );
    WsrmUtils.setFinalMessage((Stub)port);
    port.echo(input2);
    System.out.println(" Invoked the ReliableHelloWorld.echo operation reliably." );
  }

  @AsyncResponse(target = "port", operation = "echo")
  public void onEchoAsyncResponse(String msg) {
 
    System.out.println("ClientService: Got async response for request : " + msg);
    responseMessage = msg;
  }
 
  @AsyncFailure(target = "port", operation = "echo")
  public void onEchoAsyncFailure(Throwable t) {
    System.out.println("ClientService: Got async FAILURE for request : " + t);
    t.printStackTrace();
  }

  @ReliabilityErrorHandler(target="port") 
  public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) { 

    ReliableDeliveryException fault = ctx.getFault(); 
    String message = null; 
    if (fault != null) { 
      message = ctx.getFault().getMessage(); 
    } 
    String operation = ctx.getOperationName(); 
    System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message); 
  }

}

As illustrated in the previous examples (in bold text), follow these guidelines when programming the JWS file that invokes a reliable web service:

  • Import the @ServiceClient and @ReliabilityErrorHandler JWS annotations:

    import weblogic.jws.ServiceClient;
    import weblogic.jws.ReliabilityErrorHandler;
    
  • Import the WebLogic APIs that you will use in the method that handles the error that results when the client web service does not receive an acknowledgement of message receipt from the reliable web service:

    import weblogic.wsee.reliability.ReliabilityErrorContext;
    import weblogic.wsee.reliability.ReliableDeliveryException;
    
  • Import the APIs used for asynchronous response and failure.

    import weblogic.jws.AsyncFailure;
    import weblogic.jws.AsyncResponse;
    
  • Import the JAX-RPC stub, created later by the <clientgen> child element of the jwsc Ant task, of the port type of the reliable web service you want to invoke. The stub package is specified by the packageName attribute of <clientgen>, and the name of the stub is determined by the WSDL of the invoked web service.

    import examples.webservices.reliable.ReliableHelloWorldPortType;
    
  • Import the APIs used for life cycle management (to set properties and specify the final message later).

    import javax.xml.rpc.Stub;
    import weblogic.wsee.reliability.WsrmUtils;
    
  • In the body of the JWS file, use the @ServiceClient JWS annotation to specify the name and port of the reliable web service you want to invoke. You specify this annotation at the field-level on a private variable, whose data type is the JAX-RPC port type of the web service you are invoking.

    @ServiceClient(
         serviceName="ReliableHelloWorldService",
         portName="ReliableHelloWorldServicePort")
    
      private ReliableHelloWorldPortType port;
    
  • Use the port._setProperty method to dynamically specify the target service endpoint address within the web service client.

    ((Stub)port)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);
    
  • Using the stub you annotated with the @ServiceClient annotation, invoke the helloWorld reliable operation:

    port.helloWorld(input);
    

    Because the operation has been marked one-way, it does not return a value.

  • Create a method that handles the error when the client web service does not receive an acknowledgement from the reliable web service that the latter has received a message and annotate this method with the @weblogic.jws.ReliabilityErrorHandler annotation:

    @ReliabilityErrorHandler(target="port")
    public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {
        ReliableDeliveryException fault = ctx.getFault();
        String message = null;
        if (fault != null) {
          message = ctx.getFault().getMessage();
        }
        String operation = ctx.getOperationName();
        System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
      }
    

    This method takes ReliabilityErrorContext as its single parameter and returns void.

    See "weblogic.jws.ReliabilityErrorHandler" in WebLogic Web Services Reference for Oracle WebLogic Server for details about programming this error-handling method.

  • Because the service is not conversational, any state kept in the port field will be lost when this method returns. In the case of reliable messaging, this state includes the ID of the reliable sequence being used to send messages. The setFinalMessage method specifies that this is the final message to be sent on this sequence. This will allow the reliable messaging subsystem to proactively clean up the reliable sequence instead of timing out.

    WsrmUtils.setFinalMessage((Stub)port);
    
  • Using the stub you annotated with the @ServiceClient annotation, invoke the echo reliable operation:

    port.echo(input2);
    
  • Create methods to handle the asynchronous response or failure. Use the @weblogic.jws.AsyncResponse and @weblogic.jws.AsyncFailure annotations:

    @AsyncResponse(target = "port", operation = "echo")
    public void onEchoAsyncResponse(String msg) {
      System.out.println("ClientService: Got async response for request : " + msg);
      responseMessage = msg;
    }
     
    @AsyncFailure(target = "port", operation = "echo")
    public void onEchoAsyncFailure(Throwable t) {
      System.out.println("ClientService: Got async FAILURE for request : " + t);
      t.printStackTrace();
    }
    

    For more information about generating asynchronous response and failure methods, see Writing the Asynchronous JWS File.

When programming the client web service:

  • Do not specify any reliable messaging annotations (other than @ReliabilityErrorHandler) or use any reliable messaging assertions in the associated WS-Policy files.

  • Do not specify the wsdlLocation attribute of the @ServiceClient annotation. This is because the runtime retrieval of the specified WSDL might not succeed; therefore, it is better for WebLogic Server to use a local WSDL file instead.

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 taskdef and a build-reliable-client targets similar to the following:

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

<target name="build-reliable-client">

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

        <jws file="examples/webservices/reliable/ReliableClientImpl.java">

          <clientgen 
            wsdl="http://${wls.destination.host}:${wls.destination.port}/ReliableHelloWorld/ReliableHelloWorld?WSDL" 
            packageName="examples.webservices.reliable"/> 

        </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 ReliableHelloWorld 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 ReliableClientImpl JWS file imports and uses one of the generated classes.

Using Reliable Messaging With MTOM

The following example shows a simple JWS file that implements a reliable web service and uses MTOM/XOP to optimize the transmission of XML data of type xs:base64Binary in SOAP messages; see the explanation after the example for coding guidelines that correspond to the Java code in bold. This example builds on the example provided in Programming Guidelines for the JWS File That Invokes a Reliable Web Service.

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; 
import weblogic.jws.Policies; 

/**
 * Simple reliable Web Service.
 */

@WebService(name="ReliableHelloWorldPortType",
              serviceName="ReliableHelloWorldService")

@WLHttpTransport(contextPath="ReliableHelloWorld",
      serviceUri="ReliableHelloWorld",
      portName="ReliableHelloWorldServicePort")

@Policies({@Policy(uri="ReliableHelloWorldPolicy.xml", 
           direction=Policy.Direction.both, 
           attachToWsdl=true), 
           @Policy(uri = "policy:Mtom.xml")}) 

@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);

  }

  @WebMethod

  public byte[] echoBinary(byte[] bytes) { 
    return bytes; 
  } 
}

As illustrated in the previous example (in bold text), follow these guidelines when programming the JWS file that invokes a reliable web service with MTOM:

  • Use the "@weblogic.jws.Policy" annotation to specify that the pre-packaged Mtom.xml file should be applied to your web service. Use the "@weblogic.jws.Policies" annotation to group multiple WS-Policy files, including the reliable messaging policy file and the MTOM policy file.

    @Policies({@Policy(uri="ReliableHelloWorldPolicy.xml",
               direction=Policy.Direction.both,
               attachToWsdl=true),
               @Policy(uri = "policy:Mtom.xml")})
    
  • Use the Java byte[] data type in your web service operations as either a return value or input parameter whenever you want the resulting SOAP message to use MTOM/XOP to send or receive the binary data.

    public byte[] echoBinary(byte[] bytes) {
       return bytes;
    }
    

    Note:

    In this release of WebLogic Server, the only supported Java data type when using MTOM/XOP is byte[]; other binary data types, such as image, are not supported.

Client Considerations When Redeploying a Reliable Web Service

WebLogic Server supports production redeployment, which means that you can deploy a new version of an updated reliable WebLogic web service alongside an older version of the same web service.

WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the web service during the redeployment continue to use the older version of the service until they complete their work, at which point WebLogic Server automatically retires the older web service. If the client is connected to a reliable web service, its work is considered complete when the existing reliable message sequence is explicitly ended by the client or as a result of a timeout.

For additional information about production redeployment and web service clients, see "Client Considerations When Redeploying a Web Service".

Using Reliable Messaging With a Proxy Server

Client applications that invoke reliable web services 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.

This procedure describes how to create a network channel, the primary configurable WebLogic Server resource for managing network connection. Network channels enable you to provide a consistent way to access the front-end address of a cluster. For more information about network channels, see "Understanding Network Channels" in Administering Server Environments for Oracle WebLogic Server.

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.

    See "Configure custom network channels" in Oracle WebLogic Server Administration Console Online Help 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.

  3. Disable the asynchronous response service on the WebLogic Server proxy server by starting the WebLogic Server instance using the -Dweblogic.wsee.skip.async.response=true Java system property.

    By default, every WebLogic Server instance deploys an internal asynchronous web service that handles the asynchronous request-response feature. If you do not specify this system property, asynchronous messages will never get to the cluster, as required, because the asynchronous service on the proxy server will consume them instead.