4 Web Service Reliable Messaging Policy Assertion Reference
Oracle WebLogic Server supports the use of WS-Policy files to configure reliable message capabilities of a WebLogic web service that are running on a destination endpoint.
This chapter includes the following sections:
- Overview of a WS-Policy File That Contains Web Service Reliable Messaging Assertions
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. - WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.2 and 1.1
You can create a WS-Policy file with web service reliable messaging assertions that are based on Version 1.2 and 1.1 of the WS Reliable Messaging Policy Assertion (WS-RM Policy) namespace. - WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.0 (Deprecated)
Oracle WebLogic Server supports the ability to create a WS-Policy file with web service reliable messaging assertions that are based on WS Reliable Messaging Policy Assertion 1.0.
Overview of a WS-Policy File That Contains Web Service Reliable Messaging Assertions
@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 at http://www.w3.org/TR/ws-policy/
.
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 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 Pre-Packaged WS-Policy Files for Web Services Reliable Messaging and MakeConnection in Developing JAX-WS Web Services for Oracle WebLogic Server.
For task-oriented information about creating a reliable WebLogic web service, see Using Web Services Reliable Messaging in Developing JAX-WS Web Services for Oracle WebLogic Server.
WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.2 and 1.1
http://docs.oasis-open.org/ws-rx/wsrmp/200702
.
Example of a WS-Policy File With Web Service Reliable Messaging Assertions 1.2 and 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 element hierarchy of web service reliable messaging policy assertions in a WS-Policy file is shown below. Each element is described in more detail in the following sections.
Note:
You must enter the assertions in the ordered listed below.
wsp:Policy wsrmp:RMAssertion wsrmp:SequenceSTR wsrmp:SequenceTransportSecurity wsrmp:DeliveryAssurance wsp:Policy
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 |
---|---|
|
Messages are delivered at most once, without duplication. It is possible that some messages may not be delivered at all. |
|
Every message is delivered at least once. It is possible that some messages are delivered more than once. |
|
Every message is delivered exactly once, without duplication.This value is enabled by default. |
|
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>
Parent topic: Element Descriptions
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 4-2 Attributes of <wsrmp:RMAssertion>
Attribute | Description | Required? |
---|---|---|
optional |
Specifies whether the web service requires the operations to be invoked reliably. Valid values for this attribute are |
No |
Parent topic: Element Descriptions
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.
Parent topic: Element Descriptions
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.
Parent topic: Element Descriptions
WS-Policy File With Web Service Reliable Messaging Assertions—Version 1.0 (Deprecated)
http://schemas.xmlsoap.org/ws/2005/02/rm/policy/
.
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 element hierarchy of web service reliable messaging policy assertions in a WS-Policy file is shown below. Each element is described in more detail in the following sections.
Note:
You must enter the assertions in the order listed below.
wsp:Policy wsrm:RMAssertion wsrm:InactivityTimeout wsrm:BaseRetransmissionInterval wsrm:ExponentialBackoff wsrm:AcknowledgementInterval beapolicy:Expires beapolicy:QOS
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 4-3 Attributes of <beapolicy:Expires>
Attribute | Description | Required? |
---|---|---|
|
The amount of time after which the reliable web service expires. The format of this attribute conforms to the XML Schema duration at |
Yes |
Parent topic: Element Description
beapolicy:QOS
Specifies the delivery assurance (or Quality Of Service) of the web service:
Table 4-4 Attributes of <beapolicy:QOS>
Attribute | Description | Required? |
---|---|---|
|
Specifies the delivery assurance. You can specify exactly one of the following values:
You can also add the If you specify one of the This attribute defaults to Example: |
Yes |
Parent topic: Element Description
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 4-5 Attributes of <wsrm:AcknowledgementInterval>
Attribute | Description | Required? |
---|---|---|
|
Specifies the maximum interval, in milliseconds, in which the destination endpoint must transmit a stand alone acknowledgement. |
Yes |
Parent topic: Element Description
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 acknowledgment 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.
Table 4-6 Attributes of <wsrm:BaseRetransmissionInterval>
Attribute | Description | Required? |
---|---|---|
|
Number of milliseconds the source endpoint waits to retransmit message. |
Yes |
Parent topic: Element Description
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.
Parent topic: Element Description
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 4-7 Attributes of <wsrm:InactivityTimeout>
Attribute | Description | Required? |
---|---|---|
|
The number of milliseconds that defines a period of inactivity. |
Yes |
Parent topic: Element Description
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 4-8 Attributes of <wsrm:RMAssertion>
Attribute | Description | Required? |
---|---|---|
|
Specifies whether the web service requires the operations to be invoked reliably. Valid values for this attribute are |
No |
Parent topic: Element Description