cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dennis Sosnoski (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache CXF Documentation > WS-ReliableMessaging
Date Sun, 13 Oct 2013 21:42:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-ReliableMessaging">WS-ReliableMessaging</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~dsosnoski">Dennis
Sosnoski</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Added description of runtime property values and JMX usage to control RM operation<br
/>
    </div>
        <br/>
                         <h4>Changes (5)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >CXF supports both the official [1.1/1.2
Web Services Reliable Messaging|http://docs.oasis-open.org/ws-rx/wsrm/200702] (WS-ReliableMessaging)
protocol using the {nl:http://docs.oasis-open.org/ws-rx/wsrm/200702} namespace and the outdated
[February 2005 submission version|http://schemas.xmlsoap.org/ws/2005/02/rm/] using the {nl:http://schemas.xmlsoap.org/ws/2005/02/rm/}
namespace. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The submission version specified
an outdated version of WS-Addressing, using the <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">{nl:</span>http://schemas.xmlsoap.org/ws/2004/08/addressing<span
class="diff-added-chars"style="background-color: #dfd;">}</span></span> namespace,
which has since been replaced by the official <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">{nl:</span>http://www.w3.org/2005/08/addressing<span
class="diff-added-chars"style="background-color: #dfd;">}</span></span> namespace.
Most other web services implementations supporting the submission version of WS-ReliableMessaging
have deviated from the specification by moving to the official WS-Addressing release with
the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[http://www.w3.org/2005/08/addressing]</span>
<span class="diff-added-words"style="background-color: #dfd;">{nl:http://www.w3.org/2005/08/addressing}</span>
namespace. CXF supports the submission version of RM with either WS-Addressing namespace.
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>For compatibility with
older versions of CXF, the default is to use the February 2005 submission version of RM with
the submission version of WS-Addressing. On the client side, you can CXF for whichever version
of WS-ReliableMessaging you want to use (see [Reliable Messaging Configuration Guide|WSRMConfiguration]).
On the provider side, CXF adapts to whichever version of WS-ReliableMessaging is used by the
client and responds appropriately. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>|| Key || Value || <br></td></tr>
            <tr><td class="diff-changed-lines" >| WSRM_VERSION_PROPERTY | String
WS-RM version namespace <span class="diff-changed-words">(<span class="diff-added-chars"style="background-color:
#dfd;">{nl:</span>http://schemas.xmlsoap.org/ws/2005/02/rm/<span class="diff-added-chars"style="background-color:
#dfd;">}</span></span> or <span class="diff-changed-words"><span class="diff-added-chars"style="background-color:
#dfd;">{nl:</span>http://docs.oasis-open.org/ws-rx/wsrm/200702<span class="diff-added-chars"style="background-color:
#dfd;">}</span>)</span> | <br></td></tr>
            <tr><td class="diff-changed-lines" >| WSRM_WSA_VERSION_PROPERTY |
String WS-Addressing version namespace <span class="diff-changed-words">(<span class="diff-added-chars"style="background-color:
#dfd;">{nl:</span>http://schemas.xmlsoap.org/ws/2004/08/addressing<span class="diff-added-chars"style="background-color:
#dfd;">}</span></span> or <span class="diff-changed-words"><span class="diff-added-chars"style="background-color:
#dfd;">{nl:</span>http://www.w3.org/2005/08/addressing<span class="diff-added-chars"style="background-color:
#dfd;">}</span>)</span> - this property is ignored unless you&#39;re using
the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color:
#dfd;">{nl:</span>http://schemas.xmlsoap.org/ws/2005/02/rm/<span class="diff-added-chars"style="background-color:
#dfd;">}</span></span> RM namespace) | <br></td></tr>
            <tr><td class="diff-unchanged" >| WSRM_LAST_MESSAGE_PROPERTY | Boolean
value TRUE to tell the RM code that the last message is being sent, allowing the code to close
the RM sequence and release resources (as of the 3.0.0 version of CXF the RM code will by
default close the RM sequence when you close your client; earlier versions of CXF did not
close the sequence unless told to using this flag, or if configured with a source policy &lt;wsrm-mgr:sequenceTerminationPolicy
terminateOnShutdown=&quot;true&quot;/&gt;) | <br>| WSRM_INACTIVITY_TIMEOUT_PROPERTY
| Long inactivity timeout in milliseconds | <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >| WSRM_ACKNOWLEDGEMENT_INTERVAL_PROPERTY
| Long acknowledgement interval in milliseconds | <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">You
can also monitor and control many aspects of RM using the JMX+Management features of CXF.
 <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">You
can also monitor and control many aspects of RM using the [JMX Management] features of CXF.
The full list of JMX operations is defined by org.apache.cxf.ws.rm.ManagedRMManager and org.apache.cxf.ws.rm.ManagedRMEndpoint,
but these operations include viewing the current RM state down to the individual message level.
You can also use JXM to close and/or terminate an RM sequence, and to receive notification
of when previously-sent messages are acknowledged by the remote RM endpoint. <br> <br>For
example, if you have the JMX server enabled in your client configuration you could use this
code to track the last acknowledgement number received: <br>{code} <br>    private
static class AcknowledgementListener implements NotificationListener { <br>        private
volatile long lastAcknowledgement; <br> <br>        @Override <br>     
  public void handleNotification(Notification notification, Object handback) { <br>
           if (notification instanceof AcknowledgementNotification) { <br>         
      AcknowledgementNotification ack = (AcknowledgementNotification)notification; <br>
               lastAcknowledgement = ack.getMessageNumber(); <br>            } <br>
       } <br>    } <br>        // initialize client <br>    ... <br>
       // attach to JMX bean for notifications <br>        //  NOTE: you must have sent
at least one message to initialize RM before executing this code <br>        Endpoint
ep = ClientProxy.getClient(client).getEndpoint(); <br>        InstrumentationManager
im = bus.getExtension(InstrumentationManager.class); <br>        MBeanServer mbs = im.getMBeanServer();
<br>        RMManager clientManager = bus.getExtension(RMManager.class); <br>
       ObjectName name = RMUtils.getManagedObjectName(clientManager, ep); <br>     
  System.out.println(&quot;Looking for endpoint name &quot; + name); <br>  
     AcknowledgementListener listener = new AcknowledgementListener(); <br>        mbs.addNotificationListener(name,
listener, null, null); <br> <br>        // send messages using RM with acknowledgement
status reported to listener <br>    ... <br> <br>{code} <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="WS-ReliableMessaging-WSReliableMessaging"></a>WS-Reliable
Messaging</h1>

<p>CXF supports both the official <a href="http://docs.oasis-open.org/ws-rx/wsrm/200702"
class="external-link" rel="nofollow">1.1/1.2 Web Services Reliable Messaging</a>
(WS-ReliableMessaging) protocol using the http://docs.oasis-open.org/ws-rx/wsrm/200702 namespace
and the outdated <a href="http://schemas.xmlsoap.org/ws/2005/02/rm/" class="external-link"
rel="nofollow">February 2005 submission version</a> using the http://schemas.xmlsoap.org/ws/2005/02/rm/
namespace.</p>

<p>The submission version specified an outdated version of WS-Addressing, using the
http://schemas.xmlsoap.org/ws/2004/08/addressing namespace, which has since been replaced
by the official http://www.w3.org/2005/08/addressing namespace. Most other web services implementations
supporting the submission version of WS-ReliableMessaging have deviated from the specification
by moving to the official WS-Addressing release with the http://www.w3.org/2005/08/addressing
namespace. CXF supports the submission version of RM with either WS-Addressing namespace.</p>

<p>For compatibility with older versions of CXF, the default is to use the February
2005 submission version of RM with the submission version of WS-Addressing. On the client
side, you can CXF for whichever version of WS-ReliableMessaging you want to use (see <a
href="/confluence/display/CXF20DOC/WSRMConfiguration" title="WSRMConfiguration">Reliable
Messaging Configuration Guide</a>). On the provider side, CXF adapts to whichever version
of WS-ReliableMessaging is used by the client and responds appropriately.</p>

<p>Like most other features in CXF, it is interceptor based. The WS-Reliable Messaging
implementation consists of 6 interceptors in total:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Interceptor </th>
<th class='confluenceTh'> Task </th>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.RMOutInterceptor </td>
<td class='confluenceTd'> Responsible for sending CreateSequence requests and waiting
for their CreateSequenceResponse responses, and and aggregating the sequence properties (id
and message number) for an application message. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.RMInInterceptor </td>
<td class='confluenceTd'> Intercepting and processing RM protocol messages (these will
not the application level), as well as SequenceAcknowledgments piggybacked on application
messages. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.RMCaptureInInterceptor </td>
<td class='confluenceTd'> Caching messages for later retransmission. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.RMDeliveryInterceptor </td>
<td class='confluenceTd'> Assuring InOrder delivery of messages to the application.
</td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.soap.RMSoapInterceptor </td>
<td class='confluenceTd'> Encoding and decoding the RM headers </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.rm.soap.RetransmissionInterceptor </td>
<td class='confluenceTd'> Responsible for creating copies of application messages for
future resends. </td>
</tr>
</tbody></table>
</div>


<h2><a name="WS-ReliableMessaging-InterceptorBasedQOS"></a>Interceptor Based
QOS</h2>

<p>The presence of the RM interceptors on the respective interceptor chains alone will
take care that RM protocol messages are exchanged when necessary. For example, upon intercepting
the first application message on the outbound interceptor chain, the RMOutInterceptor will
send a CreateSequence request and only proceed with processing the original application message
after it has the CreateSequenceResponse response. Furthermore, the RM interceptors are responsible
for adding the Sequence headers to the application messages and, on the destination side,
extracting them from the message.</p>

<p>This means that no changes to application code are required to make the message exchange
reliable&#33;</p>

<p>You can still control sequence demarcation and other aspects of the reliable exchange
through configuration however. For example, while CXF by default attempts to maximize the
lifetime of a sequence, thus reducing the overhead incurred by the RM protocol messages, you
can enforce the use of a separate sequence per application message by configuring the RM source's
sequence termination policy (setting the maximum sequence length to 1). See the <a href="/confluence/display/CXF20DOC/WSRMConfiguration"
title="WSRMConfiguration">Reliable Messaging Configuration Guide</a> for more details
on configuring this and other aspects of the reliable exchange.</p>

<h2><a name="WS-ReliableMessaging-Runtimecontrol"></a>Runtime control</h2>

<p>Several message context property values can be set in client code to control the
RM operation at runtime, with key values defined by public constants in org.apache.cxf.ws.rm.RMManager:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Key </th>
<th class='confluenceTh'> Value </th>
</tr>
<tr>
<td class='confluenceTd'> WSRM_VERSION_PROPERTY </td>
<td class='confluenceTd'> String WS-RM version namespace (http://schemas.xmlsoap.org/ws/2005/02/rm/
or http://docs.oasis-open.org/ws-rx/wsrm/200702) </td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_WSA_VERSION_PROPERTY </td>
<td class='confluenceTd'> String WS-Addressing version namespace (http://schemas.xmlsoap.org/ws/2004/08/addressing
or http://www.w3.org/2005/08/addressing) - this property is ignored unless you're using the
http://schemas.xmlsoap.org/ws/2005/02/rm/ RM namespace) </td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_LAST_MESSAGE_PROPERTY </td>
<td class='confluenceTd'> Boolean value TRUE to tell the RM code that the last message
is being sent, allowing the code to close the RM sequence and release resources (as of the
3.0.0 version of CXF the RM code will by default close the RM sequence when you close your
client; earlier versions of CXF did not close the sequence unless told to using this flag,
or if configured with a source policy &lt;wsrm-mgr:sequenceTerminationPolicy terminateOnShutdown="true"/&gt;)
</td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_INACTIVITY_TIMEOUT_PROPERTY </td>
<td class='confluenceTd'> Long inactivity timeout in milliseconds </td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_RETRANSMISSION_INTERVAL_PROPERTY </td>
<td class='confluenceTd'> Long base retransmission interval in milliseconds </td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_EXPONENTIAL_BACKOFF_PROPERTY </td>
<td class='confluenceTd'> Boolean exponential backoff flag </td>
</tr>
<tr>
<td class='confluenceTd'> WSRM_ACKNOWLEDGEMENT_INTERVAL_PROPERTY </td>
<td class='confluenceTd'> Long acknowledgement interval in milliseconds </td>
</tr>
</tbody></table>
</div>


<p>You can also monitor and control many aspects of RM using the <a href="/confluence/display/CXF20DOC/JMX+Management"
title="JMX Management">JMX Management</a> features of CXF. The full list of JMX operations
is defined by org.apache.cxf.ws.rm.ManagedRMManager and org.apache.cxf.ws.rm.ManagedRMEndpoint,
but these operations include viewing the current RM state down to the individual message level.
You can also use JXM to close and/or terminate an RM sequence, and to receive notification
of when previously-sent messages are acknowledged by the remote RM endpoint.</p>

<p>For example, if you have the JMX server enabled in your client configuration you
could use this code to track the last acknowledgement number received:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
    private static class AcknowledgementListener implements NotificationListener {
        private volatile long lastAcknowledgement;
        
        @Override
        public void handleNotification(Notification notification, Object handback) {
            if (notification instanceof AcknowledgementNotification) {
                AcknowledgementNotification ack = (AcknowledgementNotification)notification;
                lastAcknowledgement = ack.getMessageNumber();
            }
        }
    }
        // initialize client
    ...
        // attach to JMX bean for notifications
        //  NOTE: you must have sent at least one message to initialize RM before executing
this code
        Endpoint ep = ClientProxy.getClient(client).getEndpoint();
        InstrumentationManager im = bus.getExtension(InstrumentationManager.class);
        MBeanServer mbs = im.getMBeanServer();
        RMManager clientManager = bus.getExtension(RMManager.class);
        ObjectName name = RMUtils.getManagedObjectName(clientManager, ep);
        System.out.println("Looking for endpoint name " + name);
        AcknowledgementListener listener = new AcknowledgementListener();
        mbs.addNotificationListener(name, listener, null, null);
        
        // send messages using RM with acknowledgement status reported to listener
    ...

</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=CXF20DOC">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-ReliableMessaging">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=63532&revisedVersion=5&originalVersion=4">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message