Programming Web Services for WebLogic Server

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Web Service Reliable Messaging Policy Assertion Reference

The following sections provide reference information about Web Service reliable messaging policy assertions in a WS-Policy file:

 


Overview of a WS-Policy File That Contains Web Service Reliable Messaging Assertions

You use WS-Policy files to configure the reliable messaging capabilities of a WebLogic Web Service running on a destination endpoint. Use the @Policy JWS annotations in the JWS file that implements the Web Service to specify the name of the WS-Policy file that is associated with a Web Service.

A WS-Policy file is an XML file that conforms to the WS-Policy specification. The root element of a WS-Policy file is always <wsp:Policy>. To configure Web Service reliable messaging, you first add a <wsrm:RMAssertion> child element; its main purpose is to group all the reliable messaging policy assertions together. Then you add as child elements to <wsrm:RMAssertion> the assertions that enable the type of Web Service reliable messaging you want. All these assertions conform to the WS-PolicyAssertions specification.

WARNING: You must enter the assertions in the ordered listed in the graphic below. See Graphical Representation.

WebLogic Server includes two WS-Policy files (DefaultReliability.xml and LongRunningReliability.xml) that contain typical reliable messaging assertions that you can use if you do not want to create your own WS-Policy file. For details about these two files, see Use of WS-Policy Files for Web Service Reliable Messaging Configuration.

See Using Web Service Reliable Messaging for task-oriented information about creating a reliable WebLogic Web Service.

 


Graphical Representation

The following graphic describes the element hierarchy of Web Service reliable messaging policy assertions in a WS-Policy file.

Figure 13-1 Element Hierarchy of Web Service Reliable Messaging Policy Assertions

Element Hierarchy of Web Service Reliable Messaging Policy Assertions

 


Example of a WS-Policy File With Web Service Reliable Messaging Assertions

The following example shows a simple WS-Policy file used to configure reliable messaging for a WebLogic Web Service:

<?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="3000" />
<wsrm:ExponentialBackoff />
<wsrm:AcknowledgementInterval
Milliseconds="200" />
<beapolicy:Expires Expires="P1D" optional="true"/>
</wsrm:RMAssertion>
</wsp:Policy>

 


Element Description

beapolicy:Expires

Specifies an amount of time after which the reliable Web Service expires and does not accept any new sequences. Client applications invoking this instance of the reliable Web Service will receive an error if they try to invoke an operation after the expiration duration.

The default value of this element, if not specified in the WS-Policy file, is for the Web Service to never expires.

Table C-1 Attributes of <beapolicy:Expires>
Attribute
Description
Required?
Expires
The amount of time after which the reliable Web Service expires. The format of this attribute conforms to the XML Schema duration data type. For example, to specify that the reliable Web Service expires after 3 hours, specify Expires="P3H".
Yes

beapolicy:QOS

Specifies the delivery assurance (or Quality Of Service) of the Web Service:

The default value of this element, if not specified in the WS-Policy file, is ExactlyOnce InOrder.

Table C-2 Attributes of <beapolicy:QOS>
Attribute
Description
Required?
QOS
Specifies the delivery assurance. You can specify exactly one of the following values:
  • AtMostOnce
  • AtLeastOnce
  • ExactlyOnce
You can also add the InOrder string to specify that the messages be delivered in order.
If you specify one of the XXXOnce values, but do not specify InOrder, then the messages are not guaranteed to be in order. This is different from the default value if the entire QOS element is not specified (exactly once in order).
Example: <beapolicy:QOS QOS="AtMostOnce InOrder" />
Yes

wsrm:AcknowledgementInterval

Specifies the maximum interval, in milliseconds, in which the destination endpoint must transmit a stand alone acknowledgement.

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

This assertion does not alter the formulation of messages or acknowledgements as transmitted. Its purpose is to communicate the timing of acknowledgements so that the source endpoint may tune appropriately.

This element is optional. If you do not specify this element, the default value is set by the store and forward (SAF) agent configured for the destination endpoint.

Table C-3 Attributes of <wsrm:AcknowledgementInterval>
Attribute
Description
Required?
Milliseconds
Specifies the maximum interval, in milliseconds, in which the destination endpoint must transmit a stand alone acknowledgement.
Yes.

wsrm:BaseRetransmissionInterval

Specifies the interval, in milliseconds, that the source endpoint waits after transmitting a message and before it retransmits the message.

If the source endpoint does not receive an acknowledgement for a given message within the interval specified by this element, 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 assertion does not alter the formulation of messages as transmitted, only the timing of their transmission.

This element can be used in conjunctions with the <wsrm:ExponentialBackoff> element to specify that the retransmission interval will be adjusted using the algorithm specified by the <wsrm:ExponentialBackoff> element.

This element is optional. If you do not specify this element, the default value is set by the store and forward (SAF) agent configured for the source endpoint. If using the Administration Console to configure the SAF agent, this value is labeled Retry Delay Base.

Table C-4 Attributes of <wsrm:BaseRetransmissionInterval>
Attribute
Description
Required?
Milliseconds
Number of milliseconds the source endpoint waits to retransmit message.
Yes.

wsrm:ExponentialBackoff

Specifies that the retransmission interval will be adjusted using the exponential backoff algorithm.

This element is used in conjunction with the <wsrm:BaseRetransmissionInterval> element. If a destination endpoint does not acknowledge a sequence of messages for the amount of time specified by <wsrm:BaseRetransmissionInterval>, the exponential backoff algorithm will be used for timing of 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 in the WS-Policy file, successive retransmission intervals if messages continue to be unacknowledged are 2, 4, 8, 16, 32, and so on.

This element is optional. If not set, the same retransmission interval is used in successive retries, rather than the interval increasing exponentially.

This element has no attributes.

wsrm:InactivityTimeout

Specifies (in milliseconds) a period of inactivity for a sequence of messages. A sequence of messages is defined as a set of messages, identified by a unique sequence number, for which a particular delivery assurance applies; typically a sequence originates from a single source endpoint. If, during the duration specified by this element, a destination endpoint has received no messages from the source endpoint, the destination endpoint may consider the sequence to have been terminated due to inactivity. The same applies to the source endpoint.

This element is optional. If it is not set in the WS-Policy file, then sequences never time-out due to inactivity.

Table C-5 Attributes of <wsrm:InactivityTimeout>
Attribute
Description
Required?
Milliseconds
The number of milliseconds that defines a period of inactivity.
Yes.

wsrm:RMAssertion

Main Web Service reliable messaging assertion that groups all the other assertions under a single element.

The presence of this assertion in a WS-Policy file indicates that the corresponding Web Service must be invoked reliably.

Table C-6 Attributes of <wsrm:RMAssertion>
Attribute
Description
Required?
optional
Specifies whether the Web Service requires the operations to be invoked reliably.
Valid values for this attribute are true and false. Default value is false.
No.


  Back to Top       Previous  Next