Web Service Reliable Messaging Policy Assertion Reference

WebLogic Web Services Reference

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
WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.1
WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.0 (Deprecated)

This section applies only to JAX-RPC Web Services, and not to JAX-WS Web Services.

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

You use WS-Policy files to configure 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 <wsrmp:RMAssertion> child element; its main purpose is to group all the reliable messaging policy assertions together. Then you add as child elements to <wsrmp:RMAssertion> to define the Web Service reliable messaging. All these assertions conform to the WS-PolicyAssertions specification.
WebLogic Server includes default 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 default WS-Policy files are defined in “Default WS-Policy File for Reliable Messaging” in Programming Advanced Features of WebLogic Web Services.
For task-oriented information about creating a reliable WebLogic Web Service, see ”Using Web Service Reliable Messaging” in Programming Advanced Features of WebLogic Web Services.

WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.1

The following sections describe how to create a WS-Policy file with Web Service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion Version 1.1.

Graphical Representation

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

You must enter the assertions in the ordered listed in the graphic below. Figure 4-1 Element Hierarchy of Web Service Reliable Messaging Policy Assertions 1.1

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

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:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

    <wsrmp:RMAssertion

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

        <wsrmp:SequenceSTR/>

        <wsrmp:DeliveryAssurance>

          <wsp:Policy>

            <wsrmp:ExactlyOnce/>

          </wsp:Policy>

        </wsrmp:DeliveryAssurance>

    </wsrmp:RMAssertion>

</wsp:Policy>
Element Descriptions

The following sections describe the elements in the Web Services Reliable Messaging WS-Policy file.
wsp:Policy

Groups nested policy assertions.
wsrmp: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.
The following table summarizes the attributes of the wsrmp:RMAssertion element.
Table B-32 Attributes of <wsrmp:RMAssertion>
Attribute Description Required?
optional 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

wsrmp:SequenceSTR

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

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

Specifies the delivery assurance (or quality of service) of the Web Service. You can set one of the delivery assurances defined in the following table. If not set, the delivery assurance defaults to ExactlyOnce.

Table 4-1 Delivery Assurances for Reliable Messaging
Delivery Assurance Description
wsrmp:AtMostOnce Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all.
wsrmp:AtLeastOnce Every message is delivered at least once. It is possible that some messages are delivered more than once.
wsrmp:ExactlyOnce Every message is delivered exactly once, without duplication.This value is enabled by default.
wsrmp:InOrder Messages are delivered in the order that they were sent. This delivery assurance can be combined with one of the preceding three assurances. This value is enabled by default.

The delivery assurance must be enclosed by wsp:Policy element. For example:
<wsrmp:DeliveryAssurance>

  <wsp:Policy>

    <wsrmp:ExactlyOnce/>

  </wsp:Policy>

</wsrmp:DeliveryAssurance>
WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.0 (Deprecated)

The following sections describe how to create a WS-Policy file with Web Service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion 1.0.

Graphical Representation

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

You must enter the assertions in the ordered listed in the graphic below. Figure 4-2 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

The following sections describe the elements in the Web Services Reliable Messaging WS-Policy file.
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 B-33 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:

Table B-34 Attributes of <beapolicy:QOS>
Attribute Description Required?
QOS Delivery assurance. You can specify exactly one of the following values:

AtMostOnce—Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all.
AtLeastOnce—Every message is delivered at least once. It is possible that some messages be delivered more than once.
ExactlyOnce—Every message is delivered exactly once, without duplication.
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). This attribute defaults to ExactlyOnce InOrder. 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 B-35 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 B-36 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 B-37 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 B-38 Attributes of <wsrm:RMAssertion>
Attribute Description Required?
optional 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

Delivery Assurance	Description
wsrmp:AtMostOnce	Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all.
wsrmp:AtLeastOnce	Every message is delivered at least once. It is possible that some messages are delivered more than once.
wsrmp:ExactlyOnce	Every message is delivered exactly once, without duplication.This value is enabled by default.
wsrmp:InOrder	Messages are delivered in the order that they were sent. This delivery assurance can be combined with one of the preceding three assurances. This value is enabled by default.