19.2. WS-RM Interceptors

Overview

In Apache CXF, WS-RM functionality is implemented as interceptors. The Apache CXF runtime uses interceptors to intercept and work with the raw messages that are being sent and received. When a transport receives a message, it creates a message object and sends that message through an interceptor chain. If the application's interceptor chain includes the WS-RM interceptors, the application can participate in reliable messaging sessions. The WS-RM interceptors handle the collection and aggregation of the message chunks. They also handle all of the acknowledgement and retransmission logic.

Apache CXF WS-RM Interceptors

The Apache CXF WS-RM implementation consists of four interceptors, which are described in Table 19.1, “Apache CXF WS-ReliableMessaging Interceptors”.

Table 19.1. Apache CXF WS-ReliableMessaging Interceptors

InterceptorDescription
org.apache.cxf.ws.rm.RMOutInterceptor
Deals with the logical aspects of providing reliability guarantees for outgoing messages.
Responsible for sending the CreateSequence requests and waiting for their CreateSequenceResponse responses.
Also responsible for aggregating the sequence properties—ID and message number—for an application message.
org.apache.cxf.ws.rm.RMInInterceptorResponsible for intercepting and processing RM protocol messages and SequenceAcknowledgement messages that are piggybacked on application messages.
org.apache.cxf.ws.rm.RMCaptureInInterceptor
Caching incoming messages for persistent storage.
org.apache.cxf.ws.rm.RMDeliveryInterceptor
Assuring InOrder delivery of messages to the application.
org.apache.cxf.ws.rm.soap.RMSoapInterceptorResponsible for encoding and decoding the reliability properties as SOAP headers.
org.apache.cxf.ws.rm.RetransmissionInterceptorResponsible for creating copies of application messages for future resending.

Enabling WS-RM

The presence of the WS-RM interceptors on the interceptor chains ensures that WS-RM protocol messages are exchanged when necessary. For example, when intercepting the first application message on the outbound interceptor chain, the RMOutInterceptor sends a CreateSequence request and waits to process the original application message until it receives the CreateSequenceResponse response. In addition, the WS-RM interceptors add the sequence headers to the application messages and, on the destination side, extract them from the messages. It is not necessary to make any changes to your application code to make the exchange of messages reliable.
For more information on how to enable WS-RM, see Section 19.3, “Enabling WS-RM”.

Configuring WS-RM Attributes

You control sequence demarcation and other aspects of the reliable exchange through configuration. For example, by default Apache CXF attempts to maximize the lifetime of a sequence, thus reducing the overhead incurred by the out-of-band WS-RM protocol messages. To enforce the use of a separate sequence per application message configure the WS-RM source’s sequence termination policy (setting the maximum sequence length to 1).
For more information on configuring WS-RM behavior, see Section 19.5, “Configuring WS-RM”.