Controlling WS-ReliableMessaging sequences programmatically

Your client application can use the WSRMSequenceManager, part of the WAS SPI for reliable messaging, to gain programmatic control over reliable messaging sequences. This helps manage resources on the server, for example by removing sequences after a client application has finished messaging. We can add code to create sequences, send acknowledgement requests, close sequences, terminate sequences and wait until sequences are complete.

The WAS SPI for reliable messaging always uses the static policy set configuration applied to the client from which the SPI is called. It does not use any alternative policy set that is subsequently configured by WS-Policy to meet the requirements of a WS-Policy intersection.

By closing sequences programmatically, you limit the number of open sequences a single client has to support in a single JVM at one time.

For the client application to gain programmatic control over reliable messaging sequences, it needs access to a WSRMSequenceManager instance. Use the following code fragment to achieve this:

import com.ibm.wsspi.wsrm.WSRMSequenceManager; 
import com.ibm.wsspi.wsrm.WSRMSequenceManagerFactory;

.........

     // Get the factory
     WSRMSequenceManagerFactory factory = WSRMSequenceManagerFactory
         .getInstance();

     // Get the sequence manager instance
     WSRMSequenceManager sequenceManager = factory.createWSRMSequenceManager();

All WSRMSequenceManager methods take the following parameters:

• The client instance object. This is either a Dispatch client instance, or the Dynamic proxy client. For details of the client types, see the JAX-WS client programming model topic.

• The Port QName instance for the target endpoint.

To control WS-ReliableMessaging sequences programmatically, add code to the client application as described in the following steps:

Tasks

• Add code to create a sequence.

  To set the available properties use the following methods:

    /**
     * Sets the target provider endpoint.
     * A null value will cause a NullPointerException when the WSRMSequenceProperties object is used.
     * 
     * @param providerEndPoint The target service endpoint URI
     */
    public void setTargetEndpointUri(String providerEndPoint);
    
    /**
     * This is used to indicate that a response flow is required between the provider and requester and the response
     * flow will be established at create sequence time   
     * 
     * By calling this method it will indicate that a response flow is required.
     */
    public void setUseOfferedSequenceId();
    
    /**
     * Set the Soap version for RM protocol messages.
     * The default value for this property is WSRMSequenceProperties.SOAP_11
     * 
     * @param soapVersion
     */
    public void setSoapVersion(int soapVersion);
    
    /**
     * If the Sequence Acknowledgement messages are to be sent back asynchronously call this method.
     *
     */
    public void useAsyncTransport();
  
  

  To create the reliable messaging sequence use the createNewWSRMSequence method on the WSRMSequenceManager:

    /**
     * Initiates a new sequence handshake between this client and the target EPR specified in the
     * WSRMSequenceProperties instance.
     * 
     * This sequence will only be valid for the client issuing the createNewWSRMSequence call.
     * 
     * When returning from this call, there is no guarantee that the sequence has been established.
     * 
     * @throws NullPointerException if the sequenceProperties object is null, or the target EPR is null
     * 
     * @param clientObject The JAX-WS Dispatch instance, or the Dynamic Proxy client instance. 
     * @param sequencePropeties The properties for creating the reliable messaging sequence
     * @throws WSRMNotEnabledException 
     * @throws WSRMSequenceAlreadyExistsException 
     */
    public void createNewWSRMSequence(Object clientObject, QName portQName, WSRMSequenceProperties sequencePropeties) 
    
    throws WSRMNotEnabledException, 
           WSRMSequenceAlreadyExistsException;
  

• Add code to send an acknowledgment request.

  To send an acknowledgment request for a WS-ReliableMessaging sequence, use the following method on the WSRMSequenceManager:

    /**
     * Sending an acknowledgement request sends the ACK requested message to the specified target endPointUri.
     * The target will respond with a range of messages that can be acknowledged for the current reliable messaging 
     * sequence.
     * 
     * @param clientObject The JAX-WS Dispatch instance, or the Dynamic Proxy client instance. 
     * @param portQName
     * @param endPointUri The target endpoint uri
     * @throws WSRMNotEnabledException 
     * @throws WSRMSequenceUnknownException 
     * @throws WSRMSequenceTerminatedException 
     * @throws WSRMSequenceClosedException 
     */
    public void sendAcknowledgementRequest(Object clientObject, QName portQName, String endPointUri) 
    
    throws WSRMNotEnabledException, 
           WSRMSequenceUnknownException, 
           WSRMSequenceTerminatedException, 
           WSRMSequenceClosedException;
  
  

• Add code to close a sequence.

  To close a WS-ReliableMessaging sequence use the following method on the WSRMSequenceManager:

    /**
     * Closes the web services reliable messaging session from this application to 
     * the endpoint url specified.
     * 
     * Throws a WSRMSequenceTerminatedException if the session between this application 
     * and the target endpoint url is already closed
     * 
     * Throws a WSRMSequenceTerminatedException when the session between this application
     * and the target endpoint has already been terminated.
     * 
     * Throws WSRMSequenceUnknownException exception when either reliable messaging is not engaged to 
     * the specified endpoint url or the sequence has previously been terminated and removed.
     * 
     * @param clientObject The JAX-WS Dispatch instance, or the Dynamic Proxy client instance. 
     * @param endPointUri The target endpoint url
     * 
     * @throws WSRMNotEnabledException    
     * @throws WSRMSequenceUnknownException 
     * @throws WSRMSequenceClosedException
     * @throws WSRMSequenceTerminatedException
     */
    public void closeSequence(Object clientObject, QName portQName, String endPointUri) 
    
    throws WSRMNotEnabledException, 
           WSRMSequenceUnknownException,
           WSRMSequenceClosedException,
           WSRMSequenceTerminatedException;
  
  

• Add code to terminate a sequence.

  To terminate a WS-ReliableMessaging sequence use the following method on the WSRMSequenceManager:

    /**
     * Terminates web services reliable messaging session from this application to 
     * the endpoint url specified.
     * 
     * Throws a WSRMSequenceTerminatedException when the session between this application
     * and the target endpoint has already been terminated.
     * 
     * Throws WSRMSequenceUnknownException exception when either reliable messaging is not engaged to 
     * the specified endpoint url or the sequence has previously been terminated and removed.
     * 
     * @param clientObject The JAX-WS Dispatch instance, or the Dynamic Proxy client instance. 
     * @param endPointUri The target endpoint url
     * @throws WSRMNotEnabledException 
     * 
     * @throws WSRMSequenceTerminatedException
     * @throws WSRMSequenceUnknownException
     */
    public void terminateSequence(Object clientObject, QName portQName, String endPointUri) throws WSRMNotEnabledException;
  
  

• Add code to wait for a sequence to complete.

  To wait for a reliable messaging sequence to complete, we use a method call that ensures that all messages have been sent and acknowledged by the target service. After the sequence is completed, it is terminated and cleaned up.

  There are two ways of using the waitUntilSequenceCompleted method:

  • public boolean waitUntilSequenceCompleted(Object clientObject, 
    QName portQName, String endPointUri, long waitTime) 
    

    This method call waits for the specified waitTime for the reliable messaging sequence to complete. If the sequence does not complete in the specified time, the method returns false. If the sequence does complete in time, the method returns true.

  • public boolean waitUntilSequenceCompleted(Object clientObject, 
    QName portQName, String endPointUri) 
    

    This method call does not return until the reliable messaging sequence is completed.

WS-ReliableMessaging

Detect and fix problems with WS-ReliableMessaging

WS-ReliableMessaging: supported specifications and standards