14 Using Web Services Reliable Messaging
See also Roadmap for Developing Reliable Web Services and Clients.
This chapter includes the following sections:
-
Configuring the Source and Destination WebLogic Server Instances
-
Client Considerations When Redeploying a Reliable Web Service
-
Interoperability with WebLogic Web Service Reliable Messaging
The WebLogic Server Examples Server includes three reliable messaging examples:
-
Configuring Reliable Messaging for JAX-WS Web Services
-
Using Make Connection and Reliable Messaging for JAX-WS Web Services
-
Configuring Secure and Reliable Messaging for JAX-WS Web Services
For more information, see Web Services Samples in the WebLogic Serer Distribution in Understanding WebLogic Web Services for Oracle WebLogic Server.
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 14-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. |
The following sections describe 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 Make Connection. 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 Configuring Message Buffering for Web Services. For web service clients, message buffering is enabled by default.
Table 14-2 Transport Types for Web Services Reliable Messaging
Transport Type | Features |
---|---|
Asynchronous transport |
For buffered web services:
For non-buffered web services:
|
Synchronous transport |
|
The Life Cycle of the Reliable Message Sequence
The following figure shows a one-way reliable message exchange.
Figure 14-1 Web Service Reliable Message Exchange
Description of "Figure 14-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 Configuring Message Buffering for Web Services.
RM Destination Down Before Request Arrives
Table 14-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 Configuring Message Buffering for Web Services.
Table 14-3 Reliable Messaging Failure Recovery Scenario—RM Destination Down Before Request Arrives
Transport Type | Scenario Description |
---|---|
Asynchronous Transport |
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: 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 Make Connection. For more information, see Using Asynchronous Web Service Clients From Behind a Firewall (Make Connection). |
RM Source Down After Request is Made
Table 14-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 Configuring Message Buffering for Web Services.
Table 14-4 Reliable Messaging Failure Recovery Scenario—RM Source Down After Request is Made
Transport Type | Scenario Description |
---|---|
Asynchronous Transport |
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: 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 Make Connection. For more information, see Using Asynchronous Web Service Clients From Behind a Firewall (Make Connection). |
RM Destination Down After Request Arrives
Table 14-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 Configuring Message Buffering for Web Services.
Table 14-5 Reliable Messaging Failure Recovery Scenario—RM Destination Down After Request Arrives
Transport Type | Scenario Description |
---|---|
Asynchronous Transport |
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:
The following describes the sequence of this scenario:
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 14-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 thejwsc
Ant task and deploying the generated reliable web service.
For more information, see Developing JAX-WS Web Services. For best practices for developing asynchronous and reliable web services and clients, see Roadmap for Developing Reliable Web Services and Clients.
Table 14-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 Pre-packaged WS-Policy Files for Web Services Reliable Messaging and Make Connection 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 |
Update your See Running the jwsc WebLogic Web Services Ant Task for general information about using the |
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 WebLogic Server 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, |
10 |
Update the |
Update your See Running the jwsc WebLogic Web Services Ant Task for general information about using the |
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 WebLogic Server 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:
-
Grouping Messages into Business Units of Work (Batching)—Describes how to group messages into business units of work—also called batching—to improve performance when using reliable messaging.
-
Client Considerations When Redeploying a Reliable Web Service—Describes client considerations for when you deploy a new version of an updated reliable WebLogic web service alongside an older version of the same web service.
-
Interoperability with WebLogic Web Service Reliable Messaging—Provides recommendations for interoperating with WebLogic web services reliable messaging.
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 Server 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 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 Pre-packaged WS-Policy Files for Web Services Reliable Messaging and Make Connection.
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 14-7 Pre-packaged WS-Policy Files That Support Reliable Messaging
Pre-packaged WS-Policy File | Description | Method Level Attachment? |
---|---|---|
|
Specifies policy assertions related to delivery assurance. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.2 at |
Yes |
|
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 |
Yes |
|
Specifies policy assertions related to quality of service. It enables Make Connection 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 |
|
Specifies that in order to secure messages in a reliable sequence, the runtime will use the |
No |
|
The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion 1.1 at |
Yes |
|
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 |
Yes |
|
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 |
Yes |
|
Combines 1.2 and 1.0 WS-Reliable Messaging policy assertions. The policy assertions for the 1.2 version Make Connection 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 |
|
Combines 1.1 and 1.0 WS Reliable Messaging policy assertions. See Reliability1.0_1.1.xml (WS-Policy.xml File). |
Yes |
|
Deprecated. The web service reliable messaging assertions are based on WS Reliable Messaging Policy Assertion Version 1.0 at 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 |
|
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:
-
WS Reliable Messaging Policy Assertion Version 1.2 at
http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.2-spec-os.html
-
WS Reliable Messaging Policy Assertion Version 1.1 at
http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.1-spec-os-01.html
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 14-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 |
<wsrmp:SequenceTransportSecurity> |
To secure messages in a reliable sequence, the runtime will use the SSL transport session that is used to send the |
<wsrm:DeliveryAssurance> |
Delivery assurance (or quality of service) of the web service. Valid values are |
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 14-9 Web Service Reliable Messaging Assertions (Version 1.0)
Assertion | Description |
---|---|
<wsrm:InactivityTimeout> |
Number of milliseconds, specified with the |
<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 standalone acknowledgment. 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, |
<beapolicy:QOS> |
Delivery assurance level, as described in Table 14-1. The element has one attribute, |
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 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 Pre-packaged WS-Policy Files for Web Services Reliable Messaging and Make Connection.
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 thejwsc
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
orWEB-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 toPolicy.Direction.inbound
orPolicy.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 byuri
.Please note:
-
If the client uses synchronous transport to invoke a web service, and the inbound direction of the operation requires reliability (
optional
attribute isfalse
), the client must provide an offer sequence (<wsrm: Offer...>
as described in the WS-ReliableMessaging specification athttp://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 istrue
.
For more information about the @Policy
annotation, see weblogic.jws.Policy in WebLogic Web Services Reference for Oracle WebLogic Server.
Example 14-1 shows a simple JWS file that implements a reliable web service.
Example 14-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 14-2.
Table 14-10 Invoking a Reliable Web Service Based on Transport Type
Transport Type | Description |
---|---|
Asynchronous transport |
To use asynchronous transport, perform the following steps:
|
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:
|
For additional control on the client side, you may wish to perform one or more of the following tasks:
-
Configure reliable messaging on the client side, as described in Configuring Reliable Messaging.
-
Implement the reliability error listener to receive notifications if a reliable delivery fails, as described in Implementing the Reliability Error Listener. Oracle recommends that you always implement the reliability error listener as a best practice.
-
Perform common life cycle tasks on the reliable messaging sequence, such as set configuration options, get the reliable sequence id, and terminate a reliable sequence, as described in Managing the Life Cycle of a Reliable Message Sequence.
Configuring Reliable Messaging
Note:
For best practices for configuring reliable web services, see 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 WebLogic Server Administration Console or WLST, as described in the following sections.
Using the Administration Console
To configure reliable messaging for WebLogic Server using the WebLogic Server Administration Console:
For more information, see Web Service Reliable Messaging in the Oracle WebLogic Server Administration Console Online 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 Understanding the 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 WebLogic Server 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 Understanding the WebLogic Scripting Tool.
For more information, see Configure Web Service Reliable Messaging in the Oracle WebLogic Server Administration Console Online Help.
Configuring Reliable Messaging on Web Service Clients
For general information about configuring reliable messaging on web service clients, see Configuring Web Service Clients.
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, P
n
Y
n
M
n
DT
n
H
n
M
n
S
, where n
Y
specifies the number of years, n
M
specifies the number of months, n
D
specifies the number of days, T
is the date/time separator, n
H
specifies the number of hours, n
M
specifies the number of minutes, and n
S
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 WebLogic Server 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 Understanding the WebLogic Scripting Tool.
Configuring the Base Retransmission Interval on the Web Service Client
Note:
For more information about configuring web service clients, see Configuring Web Service Clients.
Table 14-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 14-11 Methods for Configuring the Base Retransmission Interval
Method | Description |
---|---|
|
Gets the base retransmission 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 WebLogic Server 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 Understanding the WebLogic Scripting Tool.
Configuring the Retransmission Exponential Backoff on the Web Service Client
Note:
For more information about configuring web service clients, see Configuring Web Service Clients.
Table 14-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 14-12 Methods for Configuring the Retransmission Exponential Backoff
Method | Description |
---|---|
|
Indicates whether retransmission exponential backoff is enabled. |
|
Specifies whether base retransmission exponential backoff is enabled. Valid values are |
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, P
n
Y
n
M
n
DT
n
H
n
M
n
S
, where n
Y
specifies the number of years, n
M
specifies the number of months, n
D
specifies the number of days, T
is the date/time separator, n
H
specifies the number of hours, n
M
specifies the number of minutes, and n
S
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 WebLogic Server 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 Understanding the WebLogic Scripting Tool.
Configuring the Sequence Expiration on the Web Service Client
Note:
For more information about configuring web service clients, see Configuring Web Service Clients.
Table 14-13 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature
methods for expiration time for a sequence regardless of activity.
Table 14-13 Methods for Configuring Sequence Expiration
Method | Description |
---|---|
|
Returns the sequence expiration currently configured. |
|
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, P
n
Y
n
M
n
DT
n
H
n
M
n
S
, where n
Y
specifies the number of years, n
M
specifies the number of months, n
D
specifies the number of days, T
is the date/time separator, n
H
specifies the number of hours, n
M
specifies the number of minutes, and n
S
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 WebLogic Server 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 Understanding the WebLogic Scripting Tool.
-
Invoke the WebLogic Server 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:
-
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.
Table 14-14 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature
methods for configuring the inactivity timeout.
Table 14-14 Methods for Configuring Inactivity Timeout
Method | Description |
---|---|
|
Returns the inactivity timeout currently configured. |
|
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.
To configure the destination server to disable message buffering, on WebLogic Server or the web service endpoint level using the WebLogic Server 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 Understanding the WebLogic Scripting Tool.
-
Invoke the WebLogic Server 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:
-
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 standalone 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.
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 standalone 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 standalone 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, P
n
Y
n
M
n
DT
n
H
n
M
n
S
. Table 14-15 describes the duration format fields. This value defaults to P0DT0.2S
(0.2 seconds).
Table 14-15 Duration Format Description
Field | Description |
---|---|
|
Number of years ( |
|
Number of months ( |
|
Number of days ( |
T |
Date and time separator. |
|
Number of hours ( |
|
Number of minutes ( |
|
Number of seconds ( |
To configure the acknowledgement interval, on WebLogic Server or the web service endpoint level using the WebLogic Server 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 Understanding the WebLogic Scripting Tool.
-
Invoke the WebLogic Server 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:
-
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 14-16 defines that weblogic.wsee.reliability2.api.WsrmClientInitFeature
methods for configuring the reliability error listener.
Table 14-16 Methods for Configuring the Reliability Error Listener
Method | Description |
---|---|
|
Gets the reliability listener currently configured. |
|
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 13-1.
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 Java API Reference for Oracle WebLogic Server.
Managing the Reliable Sequence
To manage the reliable sequence, you can perform one or more of the following tasks.
-
Get and set the reliable sequence ID, as described in Getting and Setting the Reliable Sequence ID.
-
Access the state of the reliable sequence, for example, to determine if it is active or terminated, as described in Accessing the State of the Reliable Sequence.
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 14-17 Sequence State Values
Sequence State | Description |
---|---|
|
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. |
|
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. |
|
Reliable sequence has been created and the initial handshaking is complete. |
|
Reliable sequence is being created; the initial handshaking is in progress. |
|
Deprecated. WS-ReliableMessaging 1.0 only. The last message in the sequence has been received. |
|
Deprecated. WS-ReliableMessaging 1.0 only. The last message in the sequence is pending. |
|
Reliable sequence is in its initial state. Initial handshaking has not started. |
|
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. |
|
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.
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 14-18 Methods for SourceMessageInfo()
Method | Description |
---|---|
|
Gets the message ID as a String value. |
|
Gets the number of the message as a long value. |
|
Returns a |
|
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 14-19 Methods for DestinationMessageInfo()
Method | Description |
---|---|
|
Gets the message ID as a String value. |
|
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.
Monitoring Web Services Reliable Messaging
You can monitor reliable messaging sequences for a web service or client using the WebLogic Server 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 Example Client Wrapper Class for Batching Reliable Messages. You can use this class as-is in your own application code, if desired.
Example 14-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.
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 Understanding WebLogic Web Services for Oracle WebLogic Server.