weblogic.wsee.reliability2.api
Interface WsrmClient

public interface WsrmClient

RM-specific interface providing client functions for dealing with sequences and the messages within them.

dispose

void dispose()

Release any resource held by this client.

reset

void reset()

Clear all RequestContext properties, related to WS-RM, that should not be retained for a new sequence being used by this client. This method is generally called to allow a client to reuse a Port/Dispatch instance for a new sequence of messages. For example, consider a single web method that might want to send multiple 'batches' of messages, each on a new reliable sequence. Such a client could achieve this using a single Port/Dispatch instance by calling reset between batches.

getId

String getId()

Get the ID for this client instance. This ID is used by reliable messaging to track retry operations on reliable requests and other purposes. Note, this property is read-only (no setter). To specify the client ID, you must create the client instance (Port/Dispatch instance) hosting this WsrmClient by specifying a ClientIdentityFeature and the client instance identity for this client instance is derived automatically from the client identity.

See Also:

ClientIdentityFeature

getSequenceId

String getSequenceId()

Get the sequence ID being managed on this client. This may be null if no sequence messages have yet been sent.

setSequenceId

void setSequenceId(String seqId)

Set the sequence ID on a newly created client instance in order to reconnect it to an existing sequence after the client VM has restarted.

getSequenceState

SequenceState getSequenceState()

Get the state of the sequence being managed on this client. This may be null if no sequence messages have been sent or the sequence has been terminated/removed.

requestAcknowledgement

void requestAcknowledgement()
                            throws weblogic.wsee.reliability2.exception.WsrmException

Send an acknowledgement request to the RM destination. This will stimulate an acknowlegement from the RM destination back to the RM source, containing all current ack ranges. The caller should then call getAckRanges() to see any new acks that have arrived (note, the new acks may not be available immediately if this client is using async transport). Clients should be careful to not call this method frequently as it does cause a new message to be sent out over the wire, and consumes resources on the RM destination to process the message, and generate the response.

Throws:

weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException - if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated.

weblogic.wsee.reliability2.exception.WsrmException - if any other error occurs sending the message.

getAckRanges

SortedSet<MessageRange> getAckRanges()
                                     throws weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException

Gets a set of MessageRange objects indicating which requests have been acknowledged by the RM destination for this client.

Throws:

weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException - if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated.

getMostRecentMessageNumber

long getMostRecentMessageNumber()

Gets the most recently assigned message number for a reliable message that was sent from this stub. This message number is a monotonically increasing long value, starting from 1. This method will return -1 if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated, or before the first reliable message is sent on this stub.

getMessageInfo

weblogic.wsee.reliability2.sequence.SourceMessageInfo getMessageInfo(long msgNum)
                                                                     throws weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException

Get information describing a reliable message sent from this stub, given that message's message number. This method can be used in tandem with getMostRecentMessageNumber to obtain message information on the most recently send reliable message.

Throws:

weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException - if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated.

setFinalMessage

void setFinalMessage()

Indicates that the next message sent on this stub is to be considered the final message that will be sent on the stub. Indicating this allows WS-RM to proactively clean up the sequence, and any offer sequence or other resources that are associated with it, when this request, and all requests before it, have been sent, acknowledged, and any response for them received, and acknowledged.

closeSequence

void closeSequence()
                   throws weblogic.wsee.reliability2.exception.WsrmException

Closes a sequence, as defined by the WS-RM 1.1 spec. This method cannot be used on clients that specify the use of WS-RM 1.0. WS-RM 1.1 defines a process for \x91closing\x92 a sequence. Closing a sequence essentially locks a sequence such that no new sequence messages can be accepted on the RM destination, and no new sequence messages can be sent by the RM source. A closed sequence is still tracked by the RM destination, and will still service acknowledgement requests against it. This allows the RM source to get a full and final accounting of the sequence before actually terminating it. Note, closing a sequence is essentially a \x91last resort\x92 action that should be taken only when the client has given up all hope of ever getting acknowledgements on the full range of requests in the sequence. Clients can see the ranges of requests that have been acknowledged at any time (getCurrentAckRanges) in the life cycle of a sequence. This allows the client to intelligently manage the reliable sequence, possibly closing the sequence in order to perform any error handling needed to account for unacknowledged messages after some client-specific maximum time.

Throws:

weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException - if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated.

weblogic.wsee.reliability2.exception.WsrmException - if any other error occurs sending the message.

sendWsrm10EmptyLastMessage

void sendWsrm10EmptyLastMessage()
                                throws weblogic.wsee.reliability2.exception.WsrmException

Deprecated. 

Use with WS-RM 1.0 only Indicate that the final message for this sequence has already been sent by sending a message with an empty body and a WS-RM sequence header with the LastMessage flag. This will indicate to both sides of the sequence that we should be looking for our final acks that should be forthcoming. Customers should use this method only when they learn that a recently sent message was the final message for a sequence. If they know ahead of time they should call setFinalMessage.

Throws:

weblogic.wsee.reliability2.exception.WsrmException

terminateSequence

void terminateSequence()
                       throws weblogic.wsee.reliability2.exception.WsrmException

Forcibly terminate a sequence. This method should be used with caution, as it immediately terminates the sequence associated with this stub, and prevents the delivery of any pending requests, or receipt of any pending responses on the offer sequence associated with this stub. It is generally better to use setFinalMessage() when possible (when the final message is known in advance of sending it).

Throws:

weblogic.wsee.reliability2.sequence.UnknownSourceSequenceException - if this method is called before the sequence ID has been established for this stub (getSequenceId returns non-null), or after the sequence for this stub has been terminated.

weblogic.wsee.reliability2.exception.WsrmException - if any other error occurs sending the message.