IBM WebSphere Application ServerTM
Release 7

com.ibm.wsspi.wsrm
Interface WSRMSequenceManager


public interface WSRMSequenceManager

The WSRMSequenceManager is used for controlling the reliable messaging sequence been a Web service requester and Web service provider. Most methods take an Object as one of the parameters. This object is either an instance of a JAX-WS Dispatch object, or an instance of the Dynamic Proxy client. The Dispatch instance is created using the jax.xml.ws.Dispatch classes and can be created in a similar way to the following: Service svc = Service.create((QName)serviceQName); svc.addPort((QName)portQName, null, endPointUri); Dispatch dispatch = svc.createDispatch( portQName, String.class, null); All methods will throw a WSRMNotEnabledException if Web services - reliable messaging has not been enabled for the application invoking the method


Method Summary
 void closeSequence(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Closes the Web services reliable messaging session from this application to the end point url specified.
 void createNewWSRMSequence(java.lang.Object clientObject, javax.xml.namespace.QName portQName, WSRMSequenceProperties sequencePropeties)
          Initiates a new sequence handshake between this client and the target EPR specified in the WSRMSequenceProperties instance.
 WSRMSequenceProperties createNewWSRMSequenceProperties()
          Creates a new WSRMSequenceProperties object which can be used to set the properties for a new web services reliable messaging sequence.
 java.lang.Exception getLastWSRMError(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Due to the asynchronous behaviour of web services reliable messaging errors may occur, such as endpoint unreachable that are not exposed to the client.
 long getLastWSRMErrorTimestamp(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Due to the asynchronous behaviour of web services reliable messaging errors may occur, such as endpoint unreachable that are not exposed to the client.
 void sendAcknowledgementRequest(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Sending an acknowledgement request sends the ACK requested message to the specified target endPointUri.
 void terminateSequence(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Terminates Web services reliable messaging session from this application to the end point url specified.
 boolean waitForAllMessagesToBeAcked(java.lang.Object clientInstance, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
           
 boolean waitForAllMessagesToBeAcked(java.lang.Object clientInstance, javax.xml.namespace.QName portQName, java.lang.String endPointUri, long waitTime)
           
 boolean waitUntilSequenceCompleted(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri)
          Waits until all messages between this application and target endpoint url are completed before returning control to the application.
 boolean waitUntilSequenceCompleted(java.lang.Object clientObject, javax.xml.namespace.QName portQName, java.lang.String endPointUri, long waitTime)
          Waits until all messages between this application and target endpoint url are completed before returning control to the application.
 

Method Detail

createNewWSRMSequenceProperties

WSRMSequenceProperties createNewWSRMSequenceProperties()
Creates a new WSRMSequenceProperties object which can be used to set the properties for a new web services reliable messaging sequence. When the WSRMSequenceProperties have been populated, the createNewWSRMSequence method can be called to establish the new reliable messaging sequence.

Returns:
A new WSRMSequenceProperties instance

createNewWSRMSequence

void createNewWSRMSequence(java.lang.Object clientObject,
                           javax.xml.namespace.QName portQName,
                           WSRMSequenceProperties sequencePropeties)
                           throws WSRMNotEnabledException,
                                  WSRMSequenceAlreadyExistsException
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.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
sequencePropeties - The properties for creating the reliable messaging sequence
Throws:
java.lang.NullPointerException - if the sequenceProperties object is null, or the target EPR is null
WSRMNotEnabledException
WSRMSequenceAlreadyExistsException

sendAcknowledgementRequest

void sendAcknowledgementRequest(java.lang.Object clientObject,
                                javax.xml.namespace.QName portQName,
                                java.lang.String endPointUri)
                                throws WSRMNotEnabledException,
                                       WSRMSequenceUnknownException,
                                       WSRMSequenceTerminatedException,
                                       WSRMSequenceClosedException
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.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
portQName -
endPointUri - The target end point uri
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceTerminatedException
WSRMSequenceClosedException

closeSequence

void closeSequence(java.lang.Object clientObject,
                   javax.xml.namespace.QName portQName,
                   java.lang.String endPointUri)
                   throws WSRMNotEnabledException,
                          WSRMSequenceUnknownException,
                          WSRMSequenceClosedException,
                          WSRMSequenceTerminatedException
Closes the Web services reliable messaging session from this application to the end point url specified. Throws a WSRMSequenceTerminatedException if f 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 end point url or the sequence has previously been terminated and removed.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
endPointUri - The target endpoint url
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceClosedException
WSRMSequenceTerminatedException

terminateSequence

void terminateSequence(java.lang.Object clientObject,
                       javax.xml.namespace.QName portQName,
                       java.lang.String endPointUri)
                       throws WSRMNotEnabledException
Terminates Web services reliable messaging session from this application to the end point url specified. Throws a WSRMSequenceTerminatedException when the session between this application and the target endpoint has already been terminated. Throws WSRMSequenceNotKnown exception when either reliable messaging is not engaged to the specified end point url or the sequence has previously been terminated and removed.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
endPointUri - The target endpoint url
Throws:
WSRMNotEnabledException
WSRMSequenceTerminatedException
WSRMSequenceUnknownException

waitUntilSequenceCompleted

boolean waitUntilSequenceCompleted(java.lang.Object clientObject,
                                   javax.xml.namespace.QName portQName,
                                   java.lang.String endPointUri)
                                   throws WSRMNotEnabledException,
                                          WSRMSequenceUnknownException,
                                          WSRMTransactionInUseException
Waits until all messages between this application and target endpoint url are completed before returning control to the application. This will implicitly call closeSequence and terminateSequence under the covers to ensure that the sequence will complete. This has the effect of setting a waitTime of -1. Returns true if the sequence has completed successfully, false otherwise Throws WSRMTransactionInUseException if sequence has an outstanding uncommitted transaction. Throws WSRMSequenceUnknownException exception when either reliable messaging is not engaged to the specified end point url or the sequence has previously been terminated and removed.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
endPointUri - The target endpoint url
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMTransactionInUseException

waitUntilSequenceCompleted

boolean waitUntilSequenceCompleted(java.lang.Object clientObject,
                                   javax.xml.namespace.QName portQName,
                                   java.lang.String endPointUri,
                                   long waitTime)
                                   throws WSRMNotEnabledException,
                                          WSRMSequenceUnknownException,
                                          WSRMTransactionInUseException
Waits until all messages between this application and target endpoint url are completed before returning control to the application. This will implicitly call closeSequence and terminateSequence under the covers to ensure that the sequence will complete. If all messages are not acknowledged within the wait time specified, then the sequence will not be closed or terminated and false will be returned to indicate that the sequence is not complete. Returns true if the sequence has completed successfully, false otherwise Throws WSRMTransactionInUseException if sequence has an outstanding uncommitted transaction. Throws WSRMSequenceUnknownException exception when either reliable messaging is not engaged to the specified end point url or the sequence has previously been terminated and removed.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
endPointUri - The target endpoint url
waitTime - The length of time to wait for the sequence to be terminated and all messages to have been processed. A wait time of -1 means an infinite wait.
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMTransactionInUseException

getLastWSRMError

java.lang.Exception getLastWSRMError(java.lang.Object clientObject,
                                     javax.xml.namespace.QName portQName,
                                     java.lang.String endPointUri)
                                     throws WSRMNotEnabledException,
                                            WSRMSequenceUnknownException,
                                            WSRMSequenceTerminatedException,
                                            WSRMSequenceClosedException
Due to the asynchronous behaviour of web services reliable messaging errors may occur, such as endpoint unreachable that are not exposed to the client. These exceptions can be retrieved by calling getLastWSRMError which will return the last problem that the RM code may have encountered. These problems may be transient (such as enpoint unreachable as the target service may become available at a later time) and the method will return null if no errors have been encountered.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
portQName -
endPointUri -
Returns:
The last error that the WS-Reliable messaging code encountered. This may be null if no errors have been encountered
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceClosedException
WSRMSequenceTerminatedException

getLastWSRMErrorTimestamp

long getLastWSRMErrorTimestamp(java.lang.Object clientObject,
                               javax.xml.namespace.QName portQName,
                               java.lang.String endPointUri)
                               throws WSRMNotEnabledException,
                                      WSRMSequenceUnknownException,
                                      WSRMSequenceTerminatedException,
                                      WSRMSequenceClosedException
Due to the asynchronous behaviour of web services reliable messaging errors may occur, such as endpoint unreachable that are not exposed to the client. These exceptions can be retrieved by calling getLastWSRMError and the time at which the error was logged can be obtained using getLastWSRMErrorTimestamp which will return. This method will return -1 if no error has been encountered.

Parameters:
clientObject - The JAX-WS Dispatch instance, or the Dynamic Proxy client instance.
portQName -
endPointUri -
Returns:
The last error that the WS-Reliable messaging code encountered. This may be null if no errors have been encountered
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceClosedException
WSRMSequenceTerminatedException

waitForAllMessagesToBeAcked

boolean waitForAllMessagesToBeAcked(java.lang.Object clientInstance,
                                    javax.xml.namespace.QName portQName,
                                    java.lang.String endPointUri,
                                    long waitTime)
                                    throws WSRMNotEnabledException,
                                           WSRMSequenceUnknownException,
                                           WSRMSequenceTerminatedException,
                                           WSRMSequenceClosedException,
                                           WSRMTransactionInUseException
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceTerminatedException
WSRMSequenceClosedException
WSRMTransactionInUseException

waitForAllMessagesToBeAcked

boolean waitForAllMessagesToBeAcked(java.lang.Object clientInstance,
                                    javax.xml.namespace.QName portQName,
                                    java.lang.String endPointUri)
                                    throws WSRMNotEnabledException,
                                           WSRMSequenceUnknownException,
                                           WSRMSequenceTerminatedException,
                                           WSRMSequenceClosedException,
                                           WSRMTransactionInUseException
Throws:
WSRMNotEnabledException
WSRMSequenceUnknownException
WSRMSequenceTerminatedException
WSRMSequenceClosedException
WSRMTransactionInUseException

IBM WebSphere Application ServerTM
Release 7