5 Using Web Services Reliable Messaging

The following sections describe how to use Web Services reliable messaging.

Overview of Web Services 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 endpoints (Web service and client) in the presence of software component, system, or network failures.

WebLogic Web services conform to the WS-ReliableMessaging 1.2 specification (February 2009) at http://docs.oasis-open.org/ws-rx/wsrm/200702 (and supports version 1.1). This specification describes how two endpoints (Web service and client) 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 5-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.


This document describes how to create reliable Web services and clients and how to configure WebLogic Server instances to which the Web services are deployed.

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 Pre-packaged WS-Policy Files for Web Services Reliable Messaging and MakeConnection. 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.

Supported Transport Types for Reliable Messaging

You can use Web service reliable messaging asynchronously or synchronously. When delivering messages asynchronously, you can configure buffering to support automatic message delivery retries, if desired.

The following table summarizes the transport type support for Web services reliable messaging. For information about transport type support for Web service clients, see Invoking a Reliable Web Service from a Web Service Client. For failure recovery information, see Reliable Messaging Failure Recovery Scenarios

Note:

Message buffering is configurable for Web services, as described in Chapter 7, "Configuring Message Buffering for Web Services.". For Web service clients, message buffering is enabled by default.

Table 5-2 Transport Types for Web Services Reliable Messaging

Transport Type Features

Asynchronous transport

For buffered Web services:

For non-buffered Web services:

  • Less overhead than asynchronous, buffered usage mode.

  • Persists sequence state only.

  • Uses non-anonymous ReplyTo.

  • Web service clients can use asynchronous or synchronous invocation semantics to invoke the Web service. For more information, see Table 3-1, "Support for Asynchronous Web Service Invocation".

Synchronous transport

  • Offers the least overhead and simplest programming model.

  • Uses anonymous ReplyTo.

  • Web service clients can use asynchronous or synchronous invocation semantics to invoke the Web service. For more information, see Table 3-1, "Support for Asynchronous Web Service Invocation".

  • If a Web service client invokes a buffered Web service using synchronous transport, one of following will result:

    - If this is the first request of the sequence, the destination sequence will be set to be non-buffered (as though the Web service configuration was set as non-buffered).

    - If this is not the first request of the sequence (that is, the client sent a request using asynchronous transport previously), then the request is rejected and a fault returned.


The Life Cycle of the Reliable Message Sequence

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

Figure 5-1 Web Service Reliable Message Exchange

Description of Figure 5-1 follows
Description of "Figure 5-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. The RM destination, if configured to buffer requests, may redeliver the request to the Web service if the Web service fails to process the request.

A Web service client sends messages to a target Web service by invoking methods on the client instance (port or Dispatch instance). A port is associated with the port type of the reliable Web service and represents a programmatic interface to that service. The port is created by the <clientgen> child element of the jwsc Ant task. A Dispatch instance is a loosely-typed, general-purpose interface for delivering whole messages from the client to the Web service. For more information about Dispatch clients, see Developing a Web Service Dispatch Client..

WebLogic stores the identifier for the reliable message sequence within this client instance. This causes the reliable message sequence to be connected to a single client instance. All messages that are sent using a given client instance will use the same reliable messaging sequence, regardless of the number of messages that are sent. (Unless you using batching, as described in Grouping Messages into Business Units of Work (Batching).)

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. this can be done by managing the lifecycle of the client instance itself, or by using the weblogic.wsee.reliability2.api.WsrmClient API. Use the WsrmClient API to perform common tasks such as set configuration options, get the sequence id, and terminate a reliable sequence. For more information, see Managing the Life Cycle of a Reliable Message Sequence.

Reliable Messaging Failure Recovery Scenarios

The following sections outline reliable messaging failure recovery for various scenarios.

The first three scenarios assume that buffering is enabled on both the Web service and client. The last scenario describes reliable messaging failure recovery for non-buffered Web services. Buffering is enabled on Web service client by default. To configure buffering on the Web service, see Chapter 7, "Configuring Message Buffering for Web Services."

RM Destination Down Before Request Arrives

Table 5-3 describes the reliable messaging failure recovery scenario when an RM destination is unavailable before a request from the RM source arrives.

It is assumed that Web service buffering is enabled on both the Web service and client. Buffering is enabled on Web service client by default. To configure buffering on the Web service, see Chapter 7, "Configuring Message Buffering for Web Services."

Table 5-3 Reliable Messaging Failure Recovery Scenario—RM Destination Down Before Request Arrives

Transport Type Scenario Description

Asynchronous Transport

  1. Client invokes an asynchronous method.

  2. Reliable messaging runtime accepts the request; client returns to do other work.

  3. Reliable messaging runtime attempts to deliver the request and fails because the RM destination is down.

  4. Reliable messaging runtime waits for the retry interval and tries to send the request again. The request delivery fails again.

  5. RM destination comes up.

  6. Reliable messaging runtime waits for the retry interval and tries to send the request again. The request delivery succeeds.

  7. Acknowledgement is sent to the client which includes the message number of the request. The reliable messaging runtime removes the message from the retry list.

  8. Response arrives and the client processes it.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.

Synchronous Transport

  1. Client invokes a synchronous method.

  2. Reliable messaging runtime accepts the request and blocks the client thread.

  3. Reliable messaging runtime attempts to deliver the request and fails because the RM destination is down.

  4. Reliable messaging runtime waits for the retry interval and tries to send the request again. The request delivery fails again.

  5. RM destination comes up.

  6. Reliable messaging runtime waits for the retry interval and tries to send the request again. The request delivery succeeds.

  7. Response and acknowledgement are sent to the client via the transport back-channel. The acknowledgement includes the message number of the request. The reliable messaging runtime removes the message from the retry list.

  8. Reliable messaging runtime unblocks the client thread and returns the response.

  9. Client receives the response as the return value of the method invocation, and processes the response.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.

Note: To achieve true reliability with synchronous transport, it is recommended that you use MakeConnection. For more information, see Using Asynchronous Web Service Clients From Behind a Firewall (MakeConnection).


RM Source Down After Request is Made

Table 5-4 describes the reliable messaging failure recovery scenario when an RM source goes down after a request is made.

It is assumed that Web service buffering is enabled on both the Web service and client. Buffering is enabled on Web service clients by default. To configure buffering on the Web service, see Chapter 7, "Configuring Message Buffering for Web Services."

Table 5-4 Reliable Messaging Failure Recovery Scenario—RM Source Down After Request is Made

Transport Type Scenario Description

Asynchronous Transport

  1. Client invokes an asynchronous method.

  2. Reliable messaging runtime accepts the request; client returns to do other work.

  3. Client (RM source) goes down.

  4. Client comes up. Client must re-initialize the client instance using the same client ID. The runtime will use this client ID to retrieve the reliable sequence ID that was active for the client. For more information, see Managing the Client ID.

  5. Reliable messaging runtime detects the reliable sequence ID that was in use prior to the client going down and recovers the accepted requests.

    Note: This step is accomplished only after the client re-initializes the client instance that was used to send the request because delivery of the request depends on resources provided by the client instance. It is recommended that clients initialize the client instance in a static block, or use a @PostConstruct annotation or other mechanism to ensure early initialization of the client instance. For more information, see the best practices examples presented in Roadmaps for Developing Web Service Clients.

  6. Reliable messaging runtime sends the request and succeeds.

  7. Acknowledgement is sent to the client which includes the message number of the request. The reliable messaging runtime removes the message from the retry list.

  8. Response arrives and the client processes it.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.

Synchronous Transport

  1. Client invokes a synchronous method.

  2. Reliable messaging runtime accepts the request and blocks the client thread.

  3. Reliable messaging runtime attempts to deliver the request. The request delivery succeeds.

  4. Before response can be sent, the client (RM source) goes down. Client thread is lost as the VM exits, along with the invocation state and calling stack of the client itself.

  5. Client (RM source) comes up. Client must re-initialize the client instance (port or Dispatch) using the same client ID. For more information, see Managing the Client ID

  6. Reliable messaging runtime detects the previous sequence ID for the client, and sees that the last request was made synchronously.

  7. Reliable messaging runtime delivers a permanent failure notification for this request, and fails the entire RM sequence associated with the client instance. Any ReliabilityErrorListener associated with the client instance will be called at this point.

  8. Client is responsible for retrieving the original request (via some client-specific mechanism) and resending it by re-invoking the client instance with the request.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.

Note: To achieve true reliability with synchronous transport, it is recommended that you use MakeConnection. For more information, see Using Asynchronous Web Service Clients From Behind a Firewall (MakeConnection).


RM Destination Down After Request Arrives

Table 5-5 describes the reliable messaging failure recovery scenario when an RM destination is unavailable after a request has been accepted from the RM source.

It is assumed that Web service buffering is enabled on both the Web service and client. Buffering is enabled on Web service client by default. To configure buffering on the Web service, see Chapter 7, "Configuring Message Buffering for Web Services."

Table 5-5 Reliable Messaging Failure Recovery Scenario—RM Destination Down After Request Arrives

Transport Type Scenario Description

Asynchronous Transport

  1. Client invokes an asynchronous method.

  2. Reliable messaging runtime accepts the request; client returns to do other work.

  3. Reliable messaging runtime attempts to deliver the request and succeeds.

  4. The RM destination accepts the request and send an acknowledgement on the back channel.

  5. Reliable messaging runtime sees the acknowledgement and removes the message from the retry list.

  6. RM destination goes down.

  7. Reliable messaging runtime on RM source retries any pending requests during this time.

  8. RM destination comes up.

  9. RM destination recovers the stored request, processes it, and sends the response.

  10. Response arrives and the client processes it.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.

Synchronous Transport

Note: If you attempt to invoke a buffered Web service using synchronous transport, one of following will result:

  • If this is the first request of the sequence, the destination sequence will be set to be non-buffered (as though the Web service configuration was set as non-buffered).

  • If this is not the first request of the sequence (that is, the client sent a request using asynchronous transport previously), then the request is rejected and a fault returned.

The following describes the sequence of this scenario:

  1. Client invokes a synchronous method.

  2. Reliable messaging runtime accepts the request and blocks the client thread.

  3. Reliable messaging runtime attempts to deliver the request. The request delivery succeeds.

  4. RM destination accepts the request and sends an acknowledgement via the transport back channel.

  5. Client (RM source) detects the acknowledgement and removes the request from the retry list.

  6. RM destination goes down.

  7. Client thread remains blocked.

  8. RM Destination comes up, recovers, and processes the request, and sends the response to the client.

  9. Reliable messaging runtime unblocks the client thread and returns the response.

  10. Client receives the response as the return value of the method invocation, and processes the response.

Note: At any time, the client can check acknowledgement status, access information about a message, and so on, as described in Managing the Life Cycle of a Reliable Message Sequence.


Failure Scenarios with Non-buffered Reliable Web Services

A non-buffered Web service operates differently than a buffered Web service in that it does not buffer a request to hardened storage before acknowledging it and attempting to process it. A non-buffered Web service will not attempt to reprocess a request if the service logic fails, whereas a buffered Web service will attempt to reprocess the request. In both cases, buffered or non-buffered, any response generated by the Web service will be buffered before it is sent back to the client.

A non-buffered Web service may be useful in the following cases:

  • Web service operates against non-transactional resources and should not process any request more than once (because rolling back the transaction that dequeued the buffered request cannot roll back the side effects of the non-transactional service).

  • Web service is relatively light weight, and does not take very long to process requests.

  • Web service performance is of paramount importance and risk of losing request or response is acceptable. Non-buffered Web services will not incur the overhead of buffering the request to a store, and thus can deliver better throughput than a buffered Web service. The performance gain is dependent on how much time and resources are required to buffer the requests (for example, very large request messages may take significant time and resources to buffer).

A non-buffered Web service is operationally similar to a buffered Web service in most failure scenarios. The exceptions are cases where the service (RM destination) itself fails. For example, in all the RM source failure scenarios described, the behavior is the same for a buffered or a non-buffered Web service (RM destination). For non-buffered Web services the failure window is open between the following two points:

  • The request is accepted for processing.

  • The response from the Web service is registered for delivery to the client (RM source).

If the Web service (RM destination) fails between these two points, the RM source will assume the request has been successfully processed (since it has been acknowledged) but will never receive a response, and the request may never have been processed.

Carefully consider this failure window before configuring a Web service to run as non-buffered.

Steps to Create and Invoke a Reliable Web Service

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 custom 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 client code is deployed, as well as the destination WebLogic Server instance on which the reliable Web service itself is deployed.

Table 5-6 summarizes the steps to create a reliable Web service and a client that invokes an operation of the reliable Web service. The procedure describes how to create the JWS files that implement the Web service and client 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.

It is assumed that you have completed the following tasks:

  • You have created the destination and source WebLogic Server instances. You deploy the reliable Web service to the destination WebLogic Server instance, and the client that invokes the reliable Web service to the source WebLogic Server instance.

  • You have set up an Ant-based development 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 WebLogic Web Services" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server. For best practices for developing asynchronous and reliable Web services and clients, see Roadmap for Developing Reliable Web Services and Clients.

Table 5-6 Steps to Create and Invoke a Reliable Web Service

#
Step Description

1

Configure the destination and source WebLogic Server instances.

You deploy the reliable Web service to the destination WebLogic Server instance, and the client that invokes the reliable Web service to the source WebLogic Server instance. For information about configuring the destination WebLogic Server instance, see Configuring the Source and Destination WebLogic Server Instances.

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.

Note: 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 Web Services Reliable Messaging and MakeConnection" 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.

For examples demonstrating best practices, see Roadmap for Developing Reliable Web Services and Clients.

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

6

Create or update the Web service client.

The Web service client invokes the reliable Web service and will be deployed to the source WebLogic Server. See Invoking a Reliable Web Service from a Web Service Client.

7

Configure reliable messaging. (Optional)

Configure reliable messaging for the reliable Web service using the Administration Console. The WS-Policy file attached to the reliable Web service provides the initial configuration settings. See Configuring Reliable Messaging.

8

Implement a reliability error listener. (Optional)

Implement a reliability error listener to receive notifications if a reliable delivery fails. See Implementing the Reliability Error Listener.

9

Manage the life cycle of a reliable message sequence. (Optional)

WebLogic Server provides a client API, weblogic.wsee.reliability2.api.WsrmClient, for use with the Web service reliable messaging. Use this API to perform common life cycle tasks such as set configuration options, get the reliable sequence id, and terminate a reliable sequence. See Managing the Life Cycle of a Reliable Message Sequence.

10

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

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

11

Compile and deploy the Web service client file.

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

prompt> ant build-clientService deploy-clientService

12

Monitor Web services reliable messaging.

Use the Administration Console to monitor Web services reliable messaging. See Monitoring Web Services Reliable Messaging.


Each of these steps is described in more detail in the following sections. In addition, the following topics are discussed:

Configuring the Source and Destination WebLogic Server Instances

You need to configure Web service persistence on the destination and source WebLogic Server instances. You deploy the reliable Web service to the destination WebLogic Server instance, and the client that invokes the reliable Web service to the source WebLogic Server instance.

When using Web services reliable messaging, the Web services reliable messaging sequence is saved to the Web service persistent store any time its state changes. Examples of state change include:

  • Reliable messaging state is updated (creating, created, terminating, terminated, and so on).

  • Security property is updated (such as security context token)

  • Message is sent on the reliable messaging sequence (if message buffering is enabled)

  • Acknowledgement when a message arrives

You can configure Web service persistence using the Configuration Wizard to extend the WebLogic Server domain using a Web services-specific extension template. Alternatively, you can configure the resources required for these advanced features using the Oracle WebLogic Administration Console or WLST. For information about configuring Web service persistence, see Configuring Web Service Persistence.

You may also wish to configure buffering for Web services. For considerations and steps to configure message buffering, see Chapter 7, "Configuring Message Buffering for Web Services."

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. This table also specifies whether the WS-Policy file can be attached at the method level; if the value in this column is no, then the WS-Policy file can be attached at the class level only. For more information, see Appendix A, "Pre-packaged WS-Policy Files for Web Services Reliable Messaging and MakeConnection"

Note:

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

Table 5-7 Pre-packaged WS-Policy Files That Support Reliable Messaging

Pre-packaged WS-Policy File Description Method Level Attachment?
DefaultReliability1.2.xml

Specifies policy assertions related to delivery assurance. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.2 at http://docs.oasis-open.org/ws-rx/wsrmp/200702. See DefaultReliability1.1.xml (WS-Policy File).

Yes

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.html. See DefaultReliability1.1.xml (WS-Policy File).

Yes

Reliability1.2_ExactlyOnce_WithMC1.1.xml

Specifies policy assertions related to quality of service. It enables MakeConnection support on the Web service and specifies usage as optional on the Web service client. See Reliability1.2_ExactlyOnce_WithMC1.1.xml (WS-Policy File).

No

Reliability1.2_SequenceSTRSecurity

Specifies that in order to secure messages in a reliable sequence, the runtime will use the wsse:SecurityTokenReference that is referenced in the CreateSequence message. It enables MakeConnection support on the Web service and specifies usage as optional on the Web service client. The Web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.2 at http://docs.oasis-open.org/ws-rx/wsrmp/200702. See Reliability1.2_SequenceTransportSecurity.xml (WS-Policy File).

No

Reliability1.1_SequenceSTRSecurity

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.html. See Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File)

Yes

Reliability1.2_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.2 at http://docs.oasis-open.org/ws-rx/wsrmp/200702. See Reliability1.2_SequenceTransportSecurity.xml (WS-Policy File).

Yes

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.html. See Reliability1.1_SequenceTransportSecurity.xml (WS-Policy File).

Yes

Reliability1.0_1.2.xml

Combines 1.2 and 1.0 WS-Reliable Messaging policy assertions. The policy assertions for the 1.2 version MakeConnection support on the Web service and specifies usage as optional on the Web service client. This sample relies on smart policy selection to determine the policy assertion that is applied at runtime. See Reliability1.0_1.2.xml (WS-Policy File).

No

Reliability1.0_1.1.xml

Combines 1.1 and 1.0 WS Reliable Messaging policy assertions. See Reliability1.0_1.1.xml (WS-Policy.xml File).

Yes

DefaultReliability.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 (WS-Policy) [Deprecated].

Yes

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 (WS-Policy) [Deprecated].

Yes


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 Versions 1.2 and 1.1

This section describes how to create a custom WS-Policy file that contains Web service reliable messaging assertions that are based on the following specifications:

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 5-8 Web Service Reliable Messaging Assertions (Versions 1.2 and 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. For more information about delivery assurance, see Table 5-1.


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:

Many of the reliable messaging policy assertions described in this section 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 5-9 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 5-1. 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.2 and 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 Securing WebLogic Web Services for Oracle WebLogic Server.

Programming Guidelines for the Reliable JWS File

Note:

For best practices for developing reliable Web services, see Chapter 4, "Roadmap for Developing Reliable Web Services and Clients."

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 Web Services Reliable Messaging and MakeConnection".

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.

    Please note:

    • If the client uses synchronous transport to invoke a Web service, and the inbound direction of the operation requires reliability (optional attribute is false), the client must provide an offer sequence (<wsrm: Offer...> as described in the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf) for use when sending reliable responses.

    • If the client uses asynchronous transport, the client is not required to send an offer sequence. If a request is made reliably, and the outbound direction has any RM policy (optional or not), the reliable messaging runtime will enforce the handshaking of a new RM sequence for sending the response. This new sequence will be associated with the request sequence, and all responses from that point onward are sent on the new response sequence. The response sequence is negotiated with the endpoint indicated by the ReplyTo address of the request.

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

Example 5-1shows a simple JWS file that implements a reliable Web service.

Example 5-1 Example of a Reliable Web Service

import javax.jws.WebService;
 
import weblogic.jws.Policies;
import weblogic.jws.Policy;
 
/**
 * Example Web service for reliable client best practice examples
 */
@WebService
// Enable RM on this service.
@Policies( { @Policy(uri = "policy:DefaultReliability1.2.xml") })
public class BackendReliableService {
 
  public String doSomething(String what) {
 
    System.out.println("BackendReliableService doing: " + what);
 
    return "Did (Reliably) '" + what + "' at: " + System.currentTimeMillis();
  }
}

In the example, the predefined DefaultReliability1.2.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 doSomething() operation can be invoked reliably. The policy file is applied to both request and response by default. For information about the pre-packaged policies available and creating a custom policy, see Creating the Web Service Reliable Messaging WS-Policy File.

Invoking a Reliable Web Service from a Web Service Client

Note:

For best practices for developing reliable Web service clients, see Roadmap for Developing Reliable Web Service Clients.

The following table summarizes how to invoke a reliable Web service from a Web service client based on the transport type that you want to employ. For a description of transport types, see Table 5-2.

Table 5-10 Invoking a Reliable Web Service Based on Transport Type

Transport Type Description

Asynchronous transport

To use asynchronous transport, perform the following steps:

  1. Implement the Web service client, as described in Table 3-3, "Steps to Invoke Web Services Asynchronously".

    In step 3 of Table 3-3, implement one of the following transport mechanisms, depending on whether the client is behind a firewall or not:

    -Asynchronous client transport feature, as described in Developing Scalable Asynchronous JAX-WS Clients (Asynchronous Client Transport).

    - MakeConnection if the client is behind a firewall, as described in Using Asynchronous Web Service Clients From Behind a Firewall (MakeConnection).

  2. Invoke the Web service using either asynchronous or synchronous invocation semantics.

    Note: You can invoke synchronous operations when asynchronous client transport or MakeConnection is enabled, as described in Configuring Asynchronous Client Transport for Synchronous Operations and Configuring MakeConnection as the Transport for Synchronous Methods.

Synchronous transport

To use synchronous transport, invoke an asynchronous or synchronous method on the reliable messaging service port instance using the standard JAX-WS Reference Implementation, as described in Using the JAX-WS Reference Implementation.

Note: If you attempt to invoke a buffered Web service using synchronous transport, one of following will result:

  • If this is the first request of the sequence, the destination sequence will be set to be non-buffered (as though the Web service configuration was set as non-buffered).

  • If this is not the first request of the sequence (that is, the client sent a request using asynchronous transport previously), then the request is rejected and a fault returned.


For additional control on the client side, you may wish to perform one or more of the following tasks:

Configuring Reliable Messaging

Note:

For best practices for configuring reliable Web services, see Chapter 4, "Roadmap for Developing Reliable Web Services and Clients."

You can configure properties for a reliable Web service and client at the WebLogic Server, Web service endpoint, or Web service client level.

The properties that you define at the WebLogic Server level apply to all reliable Web services and clients on that server. For information about configuring reliable messaging at the WebLogic Server level, see Configuring Reliable Messaging on WebLogic Server.

If desired, you can override the reliable message configuration options defined at the server level, as follows:

  • At the Web service endpoint level by updating the application deployment plan. The deployment plan associates new values with specific locations in the descriptors for your application, and is stored in the weblogic-webservices.xml descriptor. 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. For more information, see Configuring Reliable Messaging on the Web Service Endpoint

  • At the Web service client level, as described in Configuring Reliable Messaging on Web Service Clients

The following sections describe how to configure reliable messaging at the WebLogic Server, Web service endpoint, and Web service client levels.

Configuring Reliable Messaging on WebLogic Server

You can configure reliable messaging on WebLogic Server using the Administration Console or WLST, as described in the following sections.

Using the Administration Console

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

  1. Invoke the Administration Console, as described in "Using the WebLogic Server Administration Console" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

  2. In the left navigation pane, select Environment, then Servers.

  3. Select the Configuration tab and in the Server tables, click on the name of the server for which you want to configure reliable messaging.

  4. Click the Configuration tab, then the Web Services tab, then the Reliable Message tab.

  5. Edit the reliable messaging properties, as described in the following sections:

  6. Click Save.

For more information, see "Web Service Reliable Messaging" in the Oracle WebLogic Server Administration Console Help.

Using WLST

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

Configuring Reliable Messaging on the Web Service Endpoint

By default, Web service endpoints use the reliable messaging configuration defined for the server. You can override the reliable messaging configuration used by the Web service endpoint using the Administration Console, as follows:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console, as described in "Invoking the Administration Console" in Getting Started With JAX-WS 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 Port Components 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. Edit the reliable messaging properties, as described in the following sections:

  9. Click Save.

For more information, see "Configure Web Service Reliable Messaging" in the Oracle WebLogic Server Administration Console Help.

Configuring Reliable Messaging on Web Service Clients

For general information about configuring reliable messaging on Web service clients, see "Configuring Web Service Clients" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

For information about using the weblogic.wsee.reliability2.api.WsrmClientInitFeature when creating a Web services reliable messaging client, refer to the following sections:

Configuring the Base Retransmission Interval

If the source endpoint does not receive an acknowledgement for a given message within the specified base retransmission 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 interval can be used in conjunction with the retransmission exponential backoff, described in Configuring the Retransmission Exponential Backoff, 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 P0DT5S (5 seconds).

The following sections describe how to configure the base retransmission interval:

Configuring the Base Retransmission Interval on WebLogic Server or the Web Service Endpoint

To configure the retransmission exponential backoff on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Base Retransmission Interval value, as required.

Configuring the Base Retransmission Interval on the Web Service Client

Note:

For more information about configuring Web service clients, see "Configuring Web Service Clients" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Table 5-11 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature methods for configuring the interval of time that must pass before a message is retransmitted to the RM destination.

Table 5-11 Methods for Configuring the Base Retransmission Interval

Method Description

String getBaseRetransmissionInterval()

Gets the base retransmission interval.

void setBaseRetransmissionInterval(String interval)

Sets the base retransmission interval.


In the following example, the base retransmission interval is set to 3 hours.

import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import wsrm_jaxws.example.client_service.*;
import wsrm_jaxws.example.client_service.EchoResponse;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    @WebServiceRef(name="ReliableEchoService")
    private ReliableEchoService service;
    private ReliableEchoPortType port = null;
    WsrmClientInitFeature initFeature = new WsrmClientInitFeature(true);
    initFeature.setBaseRetransmissionInterval("P0DT3H");
    port = service.getMyReliableServicePort(initFeature);
...

The base retransmission interval configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
      <stub-property>
        <name>weblogic.wsee.wsrm.BaseRetransmissionInterval</name>
        <value>PT30S</value>
      </stub-property>
...
  </port-info>
</service-reference-description>

Configuring the Retransmission Exponential Backoff

The retransmission exponential backoff is used in conjunction with the base retransmission interval, described in Configuring the Base Retransmission Interval. 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.

By default, this flag is disabled (false), indicating that the same retransmission interval is used in successive retries; the interval does not increase exponentially.

The following sections describe how to configure the retransmission exponential backoff:

Configuring the Retransmission Exponential Backoff on WebLogic Server or Web Service Endpoint

To configure the retransmission exponential backoff on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Enable Retransmission Exponential Backoff flag, as required.

Configuring the Retransmission Exponential Backoff on the Web Service Client

Note:

For more information about configuring Web service clients, see "Configuring Web Service Clients" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Table 5-12 defines the weblogic.wsee.reliability2.api.WsrmClientInitFeature methods for configuring whether the message retransmission interval will be adjusted using the retransmission exponential backoff algorithm.

Table 5-12 Methods for Configuring the Retransmission Exponential Backoff

Method Description

Boolean isRetransmissionExponentialBackoff()

Indicates whether retransmission exponential backoff is enabled.

void setBaseRetransmissionExponentialBackoff(boolean value)

Specifies whether base retransmission exponential backoff is enabled. Valid values are true or false.


In the following example, the retransmission exponential backoff is enabled.

import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import wsrm_jaxws.example.client_service.*;
import wsrm_jaxws.example.client_service.EchoResponse;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    @WebServiceRef(name="ReliableEchoService")
    private ReliableEchoService service;
    private ReliableEchoPortType port = null;
    WsrmClientInitFeature initFeature = new WsrmClientInitFeature(true);
    initFeature.setBaseRetransmissionInterval("P0DT3H");
    initFeature.setBaseRetransmissionExponentialBackoff(true);
    port = service.getMyReliableServicePort(initFeature);
...

The retransmission exponential backoff configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
         <stub-property>
            <name>weblogic.wsee.wsrm.RetransmissionExponentialBackoff</name>
            <value>true</value>
         </stub-property>
...
  </port-info>
</service-reference-description>

Configuring the Sequence Expiration

The sequence expiration specifies the 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).

The following sections describe how to configure the sequence expiration:

Configuring the Sequence Expiration on WebLogic Server or Web Service Endpoint

To configure the sequence expiration on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Sequence Expiration value, as required.

Configuring Sequence Expiration on the Web Service Client

Note:

For more information about configuring Web service clients, see "Configuring Web Service Clients" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Table 5-13 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature methods for expiration time for a sequence regardless of activity.

Table 5-13 Methods for Configuring Sequence Expiration

Method Description

String getSequenceExpiration()

Returns the sequence expiration currently configured.

void setSequenceExpiration(String expiration)

Expiration time for a sequence regardless of activity.


In the following example, the sequence expiration is set to 36 hours.

import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import wsrm_jaxws.example.client_service.*;
import wsrm_jaxws.example.client_service.EchoResponse;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    @WebServiceRef(name="ReliableEchoService")
    private ReliableEchoService service;
    private ReliableEchoPortType port = null;
    WsrmClientInitFeature initFeature = new WsrmClientInitFeature(true);
    initFeature.setSequenceExpiration("P0DT36H");
    port = service.getMyReliableServicePort(initFeature);
...

The sequence expiration configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
         <stub-property>
            <name>weblogic.wsee.wsrm.SequenceExpiration</name>
            <value>PT10M</value>
         </stub-property>
...
  </port-info>
</service-reference-description>

Configuring Inactivity Timeout

If, during the inactivity timeout interval, an endpoint (the RM source or destination) has not received messages application or protocol 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).

The following sections describe how to configure the inactivity timeout:

Configuring the Inactivity Timeout on WebLogic Server or Web Service Endpoint

To configure the inactivity timeout on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Inactivity Timeout value, as required.

Configuring the Inactivity Timeout on the Web Service Client

Note:

For more information about configuring Web service clients, see "Configuring Web Service Clients" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Table 5-14 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature methods for configuring the inactivity timeout.

Table 5-14 Methods for Configuring Inactivity Timeout

Method Description

String getInactivityTimeout()

Returns the inactivity timeout currently configured.

void setInactivityTimeout(String timeout)

Sets the inactivity timeout.


In the following example, the inactivity timeout interval is set to 1 hour.

import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import wsrm_jaxws.example.client_service.*;
import wsrm_jaxws.example.client_service.EchoResponse;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    @WebServiceRef(name="ReliableEchoService")
    private ReliableEchoService service;
    private ReliableEchoPortType port = null;
    WsrmClientInitFeature initFeature = new WsrmClientInitFeature(true);
    initFeature.setInactivityTimeout("P0DT1H");
    port = service.getMyReliableServicePort(initFeature);
...

The inactivity timeout configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
         <stub-property>
            <name>weblogic.wsee.wsrm.InactivityTimeout</name>
            <value>PT5M</value>
         </stub-property>
...
  </port-info>
</service-reference-description>

Configuring a Non-buffered Destination for a Web Service

You can control whether you want to disable message buffering on a particular destination server to control whether buffering is used when receiving messages. You can configure non-buffering on the destination server at the WebLogic Server or Web service endpoint level only, not at the Web service client level (buffering is enabled by default on a Web service client).

Note:

If you configure a non-buffered destination, any Web service client that uses @WebServiceRef to define a reference to the configuration will receive responses without buffering them.

The non-buffered destination configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
         <stub-property>
           <name>weblogic.wsee.wsrm.NonBufferedDestination</name>
           <value>true</value>
         </stub-property>
...
  </port-info>
</service-reference-description>

For more information about @WebServiceRef, see "Defining a Web Service Reference Using the @WebServiceRef Annotation" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

To configure the destination server to disable message buffering, on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Non-buffered Destination value, to configure the destination server, respectively, as required.

    Note:

    On the source server, message buffering should always be enabled. That is, the Non-buffered Source value should always be disabled.

Configuring the Acknowledgement Interval

The acknowledgement interval specifies the maximum interval during which the destination endpoint must transmit a stand-alone acknowledgement. You can configure the acknowledgement interval at the WebLogic Server or Web service endpoint level only, not at the Web service client level.

Note:

A Web service client that uses @WebServiceRef to define a reference to the Web service uses the acknowledgement interval value to control the amount of time that the client's response handling will wait until acknowledging responses that it receives. In other words, the client acts like an RM destination when receiving response messages.

The non-buffered destination configuration appears in the weblogic.xml file as follows:

<service-reference-description>
...
   <port-info>
         <stub-property>
          <name>weblogic.wsee.wsrm.AcknowledgementInterval</name>
          <value>PT5S</value>
         </stub-property>
...
  </port-info>
</service-reference-description>

For more information about @WebServiceRef, see "Defining a Web Service Reference Using the @WebServiceRef Annotation" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

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 (0.2 seconds).

To configure the acknowledgement interval, on WebLogic Server or the Web service endpoint level using the Administration Console, perform the following steps:

Note:

Alternatively, you can use WLST to configure reliable messaging. For information about using WLST to extend the domain, see "Configuring Existing Domains" in Oracle WebLogic Scripting Tool.
  1. Invoke the Administration Console and access the Web service reliable messaging pages at the server-level or Web service endpoint level, as described in the following sections, respectively:

  2. Set the Acknowledgement Interval value, as required.

Implementing the Reliability Error Listener

To receive notifications related to reliability delivery failures in the event that a request cannot be delivered, you can implement the following weblogic.wsee.reliability2.api.ReliabilityErrorListener interface:

public interface ReliablityErrorListener {

   public void onReliabilityError(ReliabilityErrorContext context);
}

Table 5-15 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature methods for configuring the reliability error listener.

Table 5-15 Methods for Configuring the Reliability Error Listener

Method Description

ReliabilityErrorListener getReliabilityListener()

Gets the reliability listener currently configured.

void setErrorListener(ReliabilityErrorListener errorListener)

Sets the reliability error listener.


The following provides an example of how to implement and use a reliability error listener in your Web service client. This example is excerpted from Example 4-1, "Reliable Web Service Client Best Practices Example".

import weblogic.wsee.reliability2.api.ReliabilityErrorListener;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    WsrmClientInitFeature rmFeature = new WsrmClientInitFeature();
    features.add(rmFeature);
 
    ReliabilityErrorListener listener = new ReliabilityErrorListener() {
      public void onReliabilityError(ReliabilityErrorContext context) {
 
        // At a *minimum* do this
        System.out.println("RM sequence failure: " +
                           context.getFaultSummaryMessage());
        _lastResponse = context.getFaultSummaryMessage();
 
        // And optionally do this...
 
        // The context parameter tells you whether a request or the entire
        // sequence has failed. If a sequence fails, you'll get a notification
        // for each undelivered request (if any) on the sequence.
        if (context.isRequestSpecific()) {
          // We have a single request failure (possibly as part of a larger
          // sequence failure).
          // We can get the original request back like this:
          String operationName = context.getOperationName();
          System.out.println("Failed to deliver request for operation '" +
                             operationName + "'. Fault summary: " +
                             context.getFaultSummaryMessage());
          if ("DoSomething".equals(operationName)) {
            try {
              String request = context.getRequest(JAXBContext.newInstance(),
                                                  String.class);
              System.out.println("Failed to deliver request for operation '" +
                                 operationName + "' with content: " +
                                 request);
              Map<String, Serializable> requestProps =
                context.getUserRequestContextProperties();
              if (requestProps != null) {
                // Fetch back any property you sent in
                // JAXWSProperties.PERSISTENT_CONTEXT when you sent the
                // request.
                String myProperty = (String)requestProps.get(MY_PROPERTY);
                System.out.println(myProperty + " failed!");
              }
            } catch (Exception e) {
              e.printStackTrace();
            }
          }
        } else {
          // The entire sequence has encountered an error.
          System.out.println("Entire sequence failed: " +
                             context.getFaultSummaryMessage());
 
        }
      }
    };
 
  rmFeature.setReliabilityErrorListener(listener);
 
  _features = features.toArray(new WebServiceFeature[features.size()]);
 
  BackendReliableService anotherPort =
    _service.getBackendReliableServicePort(_features);
...

Managing the Life Cycle of a Reliable Message Sequence

WebLogic Server provides a client API, weblogic.wsee.reliability2.api.WsrmClient, for use with the Web service reliable messaging. Use this API to perform common life cycle tasks such as set configuration options, get the reliable sequence id, and terminate a reliable sequence.

An instance of the WsrmClient API can be accessed from the reliable Web service port using the weblogic.wsee.reliability2.api.WsrmClientFactory method, as follows:

package wsrm_jaxws.example;
import java.xml.ws.WebService;
import java.xml.ws.WebServiceRef;
import wsrm_jaxws.example.client_service.*;
import wsrm_jaxws.example.client_service.EchoResponse;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
...
@WebService
public class ClientServiceImpl {
...
    @WebServiceRef(name="ReliableEchoService")
    private ReliableEchoService service;
    private ReliableEchoPortType port = null;
    port = service.getReliableEchoPort();
    WsrmClient wsrmClient = WsrmClientFactory.getWsrmClientFromPort(port);
...

The following sections describe how to manage the life cycle of a reliable message sequence using WsrmClient.

For complete details on the Web service reliable messaging client API, see weblogic.wsee.reliability2.api.WsrmClient in Oracle WebLogic Server API Reference.

Managing the Reliable Sequence

To manage the reliable sequence, you can perform one or more of the following tasks.

Getting and Setting the Reliable Sequence ID

The sequence ID is used to identify a specific reliable sequence. You can get and set the sequence ID using the weblogic.wsee.reliability2.api.WsrmClient.getSequenceID() and weblogic.wsee.reliability2.api.WsrmClient.setSequenceID() methods, respectively. If no messages have been sent when you issue the getSequenceID() method, the value returned is null.

For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
...
   _service = new BackendReliableServiceService();
...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
   _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   // Will be null 
   String sequenceId = rmClient.getSequenceId();
   // Send first message
   anotherPort.doSomething("Bake a cake");
   // Will be non-null
   sequenceId = rmClient.getSequenceId();

During recovery from a server failure, you can set the reliable sequence on a newly created Web service port or dispatch instance after a client or server restart. Setting the sequence ID for a client instance is an advanced feature. Advanced clients may use setSequenceId to connect a client instance to a known RM sequence.

Accessing the State of the Reliable Sequence

To access the state of a sequence, use weblogic.wsee.reliability2.api.WsrmClient.getSequenceState(). This method returns an java.lang.Enum constant of the type weblogic.wsee.reliability2.api.SequenceState.

The following table defines valid values that may be returned for sequence state.

Table 5-16 Sequence State Values

Sequence State Description

CLOSED

Reliable sequence is closed.

Note: Closing a sequence should be considered a last resort, and only to prepare to close down a reliable messaging sequence for which you do not expect to receive the full range of requests. For more information, see Closing the Reliable Sequence

CLOSING

Reliable sequence is in the process of being closed.

Note: Closing a sequence should be considered a last resort, and only to prepare to close down a reliable messaging sequence for which you do not expect to receive the full range of requests. For more information, see Closing the Reliable Sequence

CREATED

Reliable sequence has been created and the initial handshaking is complete.

CREATING

Reliable sequence is being created; the initial handshaking is in progress.

LAST_MESSAGE

Deprecated. WS-ReliableMessaging 1.0 only. The last message in the sequence has been received.

LAST_MESSAGE_PENDING

Deprecated. WS-ReliableMessaging 1.0 only. The last message in the sequence is pending.

NEW

Reliable sequence is in its initial state. Initial handshaking has not started.

TERMINATED

Reliable sequence is terminated.

Under normal processing, after all messages up to and including the final message are acknowledged, the reliable message sequence is terminated. Though not recommended, you can force the termination of a reliable sequence, as described in Terminating the Reliable Sequence.

TERMINATING

Reliable sequence is in the process of being terminated.

Under normal processing, after all messages up to and including the final message are acknowledged, the reliable message sequence is terminated. Though not recommended, you can force the termination of a reliable sequence, as described in Terminating the Reliable Sequence.


For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
import weblogic.wsee.reliability2.api.SequenceState;
...
   _service = new BackendReliableServiceService();
...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
        _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   SequenceState rmState = rmClient.getSequenceState();
   if (rmState == SequenceState.TERMINATED) {
         ... Do some work or log a message ...
   }    
...

Managing the Client ID

The client ID identifies the Web service client. Each client has its own unique ID. The client ID can be used to access saved requests that may exist for a reliable sequence after a client or server restart.

The client ID is configured automatically by WebLogic Server. You can set the client ID to a custom value when creating the port using the weblogic.wsee.jaxws.persistence.ClientIdentityFeature. For more information, see "Managing Client Identity" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Reliable messaging uses the client ID to find any requests that were sent prior to a VM restart that were not sent before the VM exited. When you establish the first client instance using the prior client ID, reliable messaging uses the resources associated with that port to begin sending requests on behalf of the restored client ID.

You can get the client ID using the weblogic.wsee.reliability2.api.WsrmClient.getID() method.

For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
...
   _service = new BackendReliableServiceService();
...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
      _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   String clientId = rmClient.getId();
...

Managing the Acknowledged Requests

Use the weblogic.wsee.reliability2.api.WsrmClient.ackRanges() method to display the requests that have been acknowledged during the life cycle of a reliable message sequence. The ackRanges() method returns a set of weblogic.wsee.reliability.MessageRange objects.

After reviewing the range of requests that have been acknowledged, the client may choose to:

  • Send an acknowledgement request to the RM destination using the weblogic.wsee.reliability2.api.WsrmClient.requestAcknowledgement() method.

  • Close the sequence (see Closing the Reliable Sequence) and perform error handling to account for unacknowledged messages after a specific amount of time.

Note: Clients may call getAckRanges() repeatedly, to keep track of the reliable message sequence over time. However, you should take into account that there is a certain level of additional overhead associated each call.

Accessing Information About a Message

Use the weblogic.wsee.reliability2.api.WsrmClient.getMessageInfo() method to get information about a reliable message sent from the client based on the message number. This method accepts a long value representing the sequential message number of a request message sent from the client instance, and returns information about the message of type weblogic.wsee.reliability2.sequence.SourceMessageInfo. You can use the WsrmClient.getMostRecentMessageNumber() method to determine the maximum value of the message number value to pass to getMessageInfo().

The returned SourceMessageInfo object should be treated as immutable, and only the get methods should be used.

The following table list the SourceMessageInfo methods that you can use to access specific details about the source message.

Table 5-17 Methods for SourceMessageInfo()

Method Description

getMessageID()

Gets the message ID as a String value.

getMessageNum()

Gets the number of the message as a long value.

getResponseMessageInfo()

Returns a weblogic.wsee.reliability2.sequence.DestinationMessageInfo object representing the response that has been correlated to the request represented by the current SourceMessageInfo() object. Returns NULL if no response has been received for this request or if none is expected (for example, request was one way).

isAck()

Indicates whether the message has been acknowledged.


The following table lists the DestinationMessageInfo methods that you can use to access specific details about the destination message.

Table 5-18 Methods for DestinationMessageInfo()

Method Description

getMessageID()

Gets the message ID as a String value.

getMessageNum()

Gets the number of the message as a long value.


The getMessageInfo() method can be used in conjunction with weblogic.wsee.reliability2.api.WsrmClient.getMostRecentMessageNumber() to obtain information about the most recently sent reliable message. This method returns a monotonically increasing long value, starting from 1. This method will return -1 in the following circumstances:

  • If the reliable sequence ID has not been established (getSequenceID() returns null).

  • The first reliable message has not been sent yet.

  • The reliable sequence has been terminated.

Identifying the Final Message in a Reliable Sequence

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. 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.reliability2.api.WsrmClient.setFinalMessage() method.

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.

For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
...
   _service = new BackendReliableServiceService();
   ...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
        _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   anotherPort.doSomething("One potato");
   anotherPort.doSomething("Two potato");
   anotherPort.doSomething("Three potato");
   // Indicate this next invoke marks the 'final' message for the sequence
   rmClient.setFinalMessage();
   anotherPort.doSomething("Four");
...

Closing the Reliable Sequence

Use the weblogic.wsee.reliability2.api.WsrmClient.closeMessage() to close a reliable messaging sequence.

Note:

This method is valid for WS-ReliableMessaging 1.1 only; it is not supported for WS-ReliableMessaging 1.0.

When a reliable messaging sequence is closed, no new messages will be accepted by the RM destination or sent by the RM source. A closed sequence is still tracked by the RM destination and continues to service acknowledgment requests against it. It allows the RM source to get a full and final accounting of the reliable messaging sequence before terminating it.

Note: Closing a sequence should be considered a last resort, and only to prepare to close down a reliable messaging sequence for which you do not expect to receive the full range of requests. For example, after reviewing the range of requests that have been acknowledged (see Managing the Acknowledged Requests), the client may decide it necessary to close the sequence and perform error handling to account for unacknowledged messages after a specific amount of time.

Once a reliable messaging sequence is closed, it is up to the client to terminate the sequence; it will no longer be terminated automatically by the server after a configured timeout has been reached. See Terminating the Reliable Sequence.

For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
...
   _service = new BackendReliableServiceService();
...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
      _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   anotherPort.doSomething("One potato");
   anotherPort.doSomething("Two potato");
   // ... Wait some amount of time, and check for acks 
   // ... using WsrmClient.getAckRanges() ...
   // ... If we don't find all of our acks ...
   rmClient.closeSequence();
   // ... Do some error recovery like telling our
   // ... client we couldn't deliver all requests ...
   rmClient.terminateSequence();
...

Terminating the Reliable Sequence

Although not recommended, you can terminate the reliable message sequence regardless of whether all messages have been acknowledged using the weblogic.wsee.reliability2.api.WsrmClient.terminateSequence() method.

Note:

It is recommended that, instead, you use the setFinalMessage() method to identify the final message in a reliable sequence. 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. For more information, see Identifying the Final Message in a Reliable Sequence.

Terminating a sequence causes the RM source and RM destination to remove all state associated with that sequence. The client can no longer perform any action on a terminated sequence. When a sequence is terminated, any pending requests being delivered through server-side retry (SAF agents) for the sequence are rejected and sent as a notification on the ReliablityErrorListener.

For example:

import weblogic.wsee.reliability2.api.WsrmClientFactory;
import weblogic.wsee.reliability2.api.WsrmClient;
...
   _service = new BackendReliableServiceService();
...
   features.add(... some features ...);
   _features = features.toArray(new WebServiceFeature[features.size()]);
...
   BackendReliableService anotherPort =
      _service.getBackendReliableServicePort(_features);
...
   WsrmClient rmClient = WsrmClientFactory.getWsrmClientFromPort(anotherPort); 
...
   anotherPort.doSomething("One potato");
   anotherPort.doSomething("Two potato");
   // ... Wait some amount of time, and check for acks 
   // ... using WsrmClient.getAckRanges() ...
   // ... If we don't find all of our acks ...
   rmClient.closeSequence();
   // ... Do some error recovery like telling our
   // ... client we couldn't deliver all requests ...
   rmClient.terminateSequence();
...

Resetting a Client to Start a New Message Sequence

Use the weblogic.wsee.reliability2.api.WsrmClient.reset() method to clear all RequestContext properties related to reliable messaging that do not need to be retained once the reliable sequence is closed. Typically, this method is called when you want to initiate another sequence of reliable messages from the same client.

For an example of using reset(), see Example B-1, "Example Client Wrapper Class for Batching Reliable Messages".

Monitoring Web Services Reliable Messaging

You can monitor reliable messaging sequences for a Web service or client using the Administration Console. For each reliable messaging sequence, runtime monitoring information is displayed, such as the sequence state, the source and destination servers, and so on. You can customize the information that is shown in the table by clicking Customize this table.

In particular, you can use the monitoring pages to determine:

  • Whether or not you are cleaning up sequences in a timely fashion. If you view a large number of sequences in the monitoring tab, you may wish to review your client code to determine why.

  • Whether an individual sequence has unacknowledged requests, or has not received expected responses.

To monitor reliable messaging sequences for a Web service, click on the Deployments node in the left pane and, in the Deployments table that appears in the right pane, locate the Enterprise application in which the Web service is packaged. Expand the application by clicking the + node; the Web services in the application are listed under the Web Services category. Click on the name of the Web service and select Monitoring> Ports> Reliable Messaging.

To monitor reliable messaging sequences for a Web service client, click on the Deployments node in the left pane and, in the Deployments table that appears in the right pane, locate the Enterprise application in which the Web service client is packaged. Expand the application by clicking the + node and click on the application module within which the Web service client is located. Click the Monitoring tab, then click the Web Service Clients tab. Then click Monitoring> Servers> Reliable Messaging.

Grouping Messages into Business Units of Work (Batching)

Often, the messages flowing between a Web service client and service are part of a single business transaction or unit of work. An example might be a travel agency reservation process that requires messages between the agency, airline, hotel, and rental car company. All of the messages flowing between any two endpoints could be considered a business unit of work.

Reliable messaging is tailored to handling messages related to a unit of work by grouping them into an RM sequence. The entire unit of work (or sequence) is treated as a whole, and error recovery, and so on can be applied to the entire sequence (see the IncompleteSequenceBehavior element description in the WS-ReliableMessaging 1.2 specification (February 2009) at http://docs.oasis-open.org/ws-rx/wsrm/200702). For example, an RM sequence can be configured to discard requests that occur after a gap in the sequence, or to discard the entire sequence of requests if any request is missing from the sequence.

You can indicate that a message is part of a business unit of work by creating a new client instance before sending the first message in the unit, and by disposing of the client instance after the last message in the unit. Alternatively, you can use the WsrmClient API (obtained by passing a client instance to the WsrmClientFactory.getWsrmClientFromPort() method) to identify the final request in a sequence is about to be sent. This is done by calling WsrmClient.setFinalMessage() just before performing the invoke on the client instance, as described in Identifying the Final Message in a Reliable Sequence.

There is some significant overhead associated with the RM protocol. In particular, creating and terminating a sequence involves a round-trip message exchange with the service (RM destination). This means that four messages must go across the wire to establish and then terminate an RM sequence. For this reason, it is to your advantage to send the requests within a single business unit of work on a single RM sequence. This allows you to amortize the cost of the RM protocol overhead over a number of business messages.

In some cases, the client instance being used to talk to the reliable service runs in an environment where there is no intrinsic notion of the business unit of work to which the messages belong. An example of this is an intermediary such as a message broker. In this case, the broker is often aware only of the message itself, and not the context in which the message is being sent. The broker may not do anything to demarcate the start and end of a business unit of work (or sequence); as a result, when using reliable messaging to send requests, the broker will incur the RM sequence creation and termination protocol overhead for every message it sends. This can result in a serious negative performance impact.

In cases where no intrinsic business unit of work is known for a message, you can choose to arbitrarily group (or batch) messages into an artificially created unit of work (called a batch). Batching of reliable messages can overcome the performance impact described above and can be used to tune and optimize network usage and throughput between a reliable messaging client and service. Testing has shown that batching otherwise unrelated requests into even small batches (say 10 requests) can as much as triple the throughput between the client and service when using reliable messaging (when sending small messages).

Note:

Oracle does not recommend batching requests that already have an association with a business unit of work. This is because error recovery can become complicated when RM sequence boundaries and unit of work boundaries do not match. For example, when you add a ReliabilityErrorListener to your client instance (via WsrmClientInitFeature), as described in Implementing the Reliability Error Listener, this listener can be used to perform error recovery for single requests in a sequence or whole-sequence failures. When batching requests, this error recovery logic would need to store some information about each request in order to properly handle the failure of a request. A client that does not employ batching will likely have more context about the request given the business unit of work it belongs to.

The following code excerpt shows an example class called BatchingRmClientWrapper that can be used to make batching of RM requests simple and effective. This class batches requests into groups of a specified number of requests. It allows you to create a dynamic proxy that takes the place of your regular client instance. When you make invocations on the client instance, the batching wrapper seamlessly groups the outgoing requests into batches, and assigns each batch its own RM sequence. The batching wrapper also takes a duration specification that indicates the maximum lifetime of any given batch. This allows incomplete batches to be completed in a timely fashion even if there are not enough outgoing requests to completely fill a batch. If the batch has existed for the maximum lifetime specified, it will be closed as if the last message in the batch had been sent.

An example of the client wrapper class that can be used for batching reliable messaging is provided in Appendix B, "Example Client Wrapper Class for Batching Reliable Messages". You can use this class as-is in your own application code, if desired.

Example 5-2 Example of Grouping Messages into Units of Work (Batching)

import java.io.IOException;
import java.util.*;
import java.util.*;
 
import javax.servlet.*;
import javax.xml.ws.*;
 
import weblogic.jws.jaxws.client.ClientIdentityFeature;
import weblogic.jws.jaxws.client.async.AsyncClientHandlerFeature;
import weblogic.jws.jaxws.client.async.AsyncClientTransportFeature;
import weblogic.wsee.reliability2.api.ReliabilityErrorContext;
import weblogic.wsee.reliability2.api.ReliabilityErrorListener;
import weblogic.wsee.reliability2.api.WsrmClientInitFeature;
 
/**
 * Example client for invoking a reliable Web service and 'batching' requests
 * artificially into a sequence. A wrapper class called
 * BatchingRmClientWrapper is called to begin and end RM sequences for each batch of
 * requests. This avoids per-message RM sequence handshaking
 * and termination overhead (delivering better performance).
 */
public class BestPracticeAsyncRmBatchingClient
  extends GenericServlet {
 
  private BackendReliableServiceService _service;
  private BackendReliableService _singletonPort;
  private BackendReliableService _batchingPort;
 
  private static int _requestCount;
  private static String _lastResponse;
 
  @Override
  public void init()
    throws ServletException {
 
    _requestCount = 0;
    _lastResponse = null;
 
    // Only create the Web service object once as it is expensive to create repeatedly.
    if (_service == null) {
      _service = new BackendReliableServiceService();
    }
 
    // Best Practice: Use a stored list of features, per client ID, to create client instances.
    // Define all features for the Web service port, per client ID, so that they are 
    // consistent each time the port is called. For example: 
    // _service.getBackendServicePort(_features);
 
    List<WebServiceFeature> features = new ArrayList<WebServiceFeature>();
 
    // Best Practice: Explicitly define the client ID.
    ClientIdentityFeature clientIdFeature =
      new ClientIdentityFeature("MyBackendServiceAsyncRmBatchingClient");
    features.add(clientIdFeature);
 
    // Best Practice: Always implement a reliability error listener. 
    // Include this feature in your reusable feature list. This enables you to determine
    // a reason for failure, for example, RM cannot deliver a request or the RM sequence fails in
    // some way (for example, client credentials refused at service).
    WsrmClientInitFeature rmFeature = new WsrmClientInitFeature();
    features.add(rmFeature);
    rmFeature.setErrorListener(new ReliabilityErrorListener() {
      public void onReliabilityError(ReliabilityErrorContext context) {
        // At a *minimum* do this
        System.out.println("RM sequence failure: " +
                           context.getFaultSummaryMessage());
        _lastResponse = context.getFaultSummaryMessage();
      }
    });
 
    // Asynchronous endpoint
    AsyncClientTransportFeature asyncFeature =
      new AsyncClientTransportFeature(getServletContext());
    features.add(asyncFeature);
 
    // Best Practice: Define a port-based asynchronous callback handler,
    // AsyncClientHandlerFeature, for asynchronous and dispatch callback handling.
    BackendReliableServiceAsyncHandler handler =
      new BackendReliableServiceAsyncHandler() {
        public void onDoSomethingResponse(Response<DoSomethingResponse> res) {
          // ... Handle Response ...
          try {
            DoSomethingResponse response = res.get();
            _lastResponse = response.getReturn();
            System.out.println("Got reliable/async/batched response: " + _lastResponse);
          } catch (Exception e) {
            _lastResponse = e.toString();
            e.printStackTrace();
          }
        }
      };
    AsyncClientHandlerFeature handlerFeature =
      new AsyncClientHandlerFeature(handler);
    features.add(handlerFeature);
 
    // Set the features used when creating clients with
    // this client ID "MyBackendServiceAsyncRmBatchingClient"
 
    WebServiceFeature[] featuresArray =
      features.toArray(new WebServiceFeature[features.size()]);
 
    // Best Practice: Define a singleton port instance and initialize it when 
    // the client container initializes (upon deployment).
    // The singleton port will be available for the life of the servlet.
    // Creation of the singleton port triggers the asynchronous response endpoint to be published
    // and it will remain published until our container (Web application) is undeployed.
    // Note, we will get a call to destroy() before this.
    _singletonPort = _service.getBackendReliableServicePort(featuresArray);
 
    // Create a wrapper class to 'batch' messages onto RM sequences so
    // a client with no concept of which messages are related as a unit can still achieve
    // good performance from RM. The class will send a given number of requests on
    // the same sequence, and then terminate that sequence before starting
    // another to carry further requests. A batch has both a max size and
    // lifetime so no sequence is left open for too long.
    // The example batches 10 messages or executes for 20 seconds, whichever comes
    // first. Assuming there were 15 total requests to send, the class would start and complete
    // one full batch of 10 requests, then send the next batch of five requests.
    // Once the batch of five requests has been open for 20 seconds, it will be closed and the
    // associated sequence terminated (even though 10 requests were not sent to fill the batch).
    BackendReliableService batchingPort =
      _service.getBackendReliableServicePort(featuresArray);
    BatchingRmClientWrapper<BackendReliableService> batchingSeq
      = new BatchingRmClientWrapper<BackendReliableService>(batchingPort,
                                                   BackendReliableService.class,
                                                   10, "PT20S",
                                                   System.out);
    _batchingPort = batchingSeq.createProxy();
  }
 
  @Override
  public void service(ServletRequest req, ServletResponse res)
    throws ServletException, IOException {
 
    // TODO: ... Read the servlet request ...
 
    // For this simple example, echo the _lastResponse captured from 
    // an asynchronous DoSomethingResponse response message.
 
    if (_lastResponse != null) {
      res.getWriter().write(_lastResponse);
      System.out.println("Servlet returning _lastResponse value: " + _lastResponse);
      _lastResponse = null; // Clear the response so we can get another
      return;
    }
 
    // Synchronize on _batchingPort since it is a class-level variable and it might
    // be in this method on multiple threads from the servlet engine.
    
    synchronized(_batchingPort) {
 
      // Use the 'batching' port to send the requests instead of creating a
      // new request each time.
      BackendReliableService port = _batchingPort;
 
      // Set the endpoint address for BackendService.
      ((BindingProvider)port).getRequestContext().
        put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
            "http://localhost:7001/BestPracticeReliableService/BackendReliableService");
 
    // Make the invocation. Our asynchronous handler implementation (set 
    // into the AsyncClientHandlerFeature above) receives the response.
      String request = "Protected and serve " + (++_requestCount);
      System.out.println("Invoking DoSomething reliably/async/batched with request: " +
                         request);
      port.doSomethingAsync(request);
    }
 
    // Return a canned string indicating the response was not received
    // synchronously. Client needs to invoke the servlet again to get
    // the response.
    res.getWriter().write("Waiting for response...");
  }
 
  @Override
  public void destroy() {
 
    try {
      // Best Practice: Explicitly close client instances when processing is complete.
      // Close the singleton port created during initialization. Note, the asynchronous
      // response endpoint generated by creating _singletonPort *remains*
      // published until our container (Web application) is undeployed.
      ((java.io.Closeable)_singletonPort).close();
      // Best Practice: Explicitly close client instances when processing is complete.
      // Close the batching port created during initialization. Note, this will close
      // the underlying client instance used to create the batching port.
      ((java.io.Closeable)_batchingPort).close();

      // Upon return, the Web application is undeployed, and the asynchronous
      // response endpoint is stopped (unpublished). At this point,
      // the client ID used for _singletonPort will be unregistered and will no longer be
      // visible from the Administration Console and WLST.
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

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

Interoperability with WebLogic Web Service Reliable Messaging

The WebLogic Web services reliable messaging implementation will interoperate with the Web service reliable messaging implementations provided by the following third-party vendor Web services: IBM and Microsoft .NET. For best practices when interoperating with Microsoft .NET, see "Interoperability with Microsoft WCF/.NET" in Introducing WebLogic Web Services for Oracle WebLogic Server.

To enhance interoperability with Oracle SOA services that use Web services reliable messaging, please consider the following interoperability guidelines:

  • Do no use MakeConnection for asynchronous transport, as described in Using Asynchronous Web Service Clients From Behind a Firewall (MakeConnection). Reliable SOA services do not support MakeConnection.

  • Do no use WS-SecureConversation to secure reliable Web services. SOA services do not support the use of Web services reliable messaging and WS-SecureConversation together.

  • For reliable WebLogic Web service clients that are accessing reliable SOA services:

    • Use synchronous (anonymous WS-Addressing ReplyTo EPR) request-reply or one-way MEP (Message exchange pattern).

    • Do not use asynchronous (non-anonymous WS-Addressing ReplyTo EPR) request-reply MEP (Message exchange pattern).

  • For reliable SOA clients that are accessing reliable WebLogic Web services, use one of the following:

    • Synchronous (anonymous WS-Addressing ReplyTo EPR) request-reply or one-way MEP (Message exchange pattern).

    • Asynchronous (non-anonymous WS-Addressing ReplyTo EPR) request-reply MEP (Message exchange pattern).