com.sun.xml.ws.rm.runtime.sequence
Interface Sequence


public interface Sequence


Nested Class Summary
static class Sequence.AckRange
           
static class Sequence.Status
           
 
Field Summary
static long MAX_MESSAGE_ID
           
static long MIN_MESSAGE_ID
           
static long NO_EXPIRATION
           
static long UNSPECIFIED_MESSAGE_ID
           
 
Method Summary
 void acknowledgeMessageId(long messageId)
          Registers given message identifier with the sequence as aknowledged
 void acknowledgeMessageIds(java.util.List<Sequence.AckRange> ranges)
          Registers given message identifiers with the sequence as aknowledged
 void clearAckRequestedFlag()
          This method should be called to clear the AckRequested flag, which indicates that any pending requests for acknowledgement of all message identifiers registered with this sequence were satisfied.
 void close()
          Closes the sequence.
 long generateNextMessageId()
          This operation is supported by outbound sequences only.
 java.util.List<Sequence.AckRange> getAcknowledgedMessageIds()
          Provides a collection of ranges of messages identifier acknowledged with the sequence
 java.lang.String getBoundSecurityTokenReferenceId()
          Provides information on a security session to which this sequence is bound to.
 java.lang.String getId()
          Returns unique identifier of the sequence
 long getLastActivityTime()
          Provides information on the last activity time of this sequence
 long getLastMessageId()
          Provides information on the last message id sent on this sequence
 Sequence.Status getStatus()
          Provides information on the status of the message sequence
 boolean hasPendingAcknowledgements()
          The method may be called to determine whether the sequence has some unacknowledged messages or not
 boolean isAcknowledged(long messageId)
          Determines whether such message number has been already acknowledged on the sequence or not.
 boolean isAckRequested()
          Provides information on the actual AckRequested flag status
 boolean isClosed()
          Provides information on the sequence closed status.
 boolean isExpired()
          Provides information on the sequence expiration status.
 void preDestroy()
          The method is called during the sequence termination to allow sequence object to release its allocated resources
 java.lang.Object retrieveMessage(long correlationId)
          This operation is supported by outbound sequences only.
 void setAckRequestedFlag()
          This method should be called to set the AckRequested flag, which indicates a pending request for acknowledgement of all message identifiers registered with this sequence.
 void storeMessage(long correlationId, long id, java.lang.Object message)
          This operation is supported by outbound sequences only.
 void updateLastActivityTime()
          Manually updates the last activit time of the sequence to present time
 

Field Detail

UNSPECIFIED_MESSAGE_ID

static final long UNSPECIFIED_MESSAGE_ID
See Also:
Constant Field Values

MIN_MESSAGE_ID

static final long MIN_MESSAGE_ID
See Also:
Constant Field Values

MAX_MESSAGE_ID

static final long MAX_MESSAGE_ID
See Also:
Constant Field Values

NO_EXPIRATION

static final long NO_EXPIRATION
See Also:
Constant Field Values
Method Detail

getId

java.lang.String getId()
Returns unique identifier of the sequence

Returns:
unique sequence identifier

generateNextMessageId

long generateNextMessageId()
                           throws MessageNumberRolloverException,
                                  java.lang.IllegalStateException,
                                  java.lang.UnsupportedOperationException
This operation is supported by outbound sequences only.

Generates a new message identifier and registers it within the sequence

Returns:
the next message identifier that should be used for the next message sent on the sequence.
Throws:
MessageNumberRolloverException - in case the message identifier counter overflows
java.lang.IllegalStateException - in case the sequence is closed
java.lang.UnsupportedOperationException - in case the sequence is inbound and does not support generating message identifiers

storeMessage

void storeMessage(long correlationId,
                  long id,
                  java.lang.Object message)
                  throws java.lang.IllegalStateException,
                         java.lang.UnsupportedOperationException
This operation is supported by outbound sequences only.

Stores a message within the sequence. The message is guaranteed to remain stored in the sequence until the message id associated with the message is acknowledged

Parameters:
correlationId - identifier of a message that correlates with the stored message
id - message identifier attached to the message
message - the message that is supposed to be stored in the sequence until the message is not acknowledged as received
Throws:
java.lang.IllegalStateException - in case the sequence is closed
java.lang.UnsupportedOperationException - in case the sequence is inbound and does not support generating message identifiers

retrieveMessage

java.lang.Object retrieveMessage(long correlationId)
                                 throws java.lang.UnsupportedOperationException,
                                        IllegalMessageIdentifierException
This operation is supported by outbound sequences only.

Retrieves a message stored within the sequence if avalable. May return null if no stored message under given message id is available.

Availability of the message depends on the message identifier acknowledgement. Message, if stored (see #storeMessage(long, java.lang.Object) remains available for retrieval until it is acknowledged. Once the message identifier associated with the stored message has been acknowledged, availability of the stored message is no longer guaranteed and stored message becomes eligible for garbage collection.

Note however, that message MAY still be available even after it has been acknowledged. Thus it is NOT safe to use this method as a test of a message acknowledgement.

Parameters:
correlationId - identifier of a message that correlates with the stored message
Returns:
the message that is stored in the sequence if available, null otherwise.
Throws:
IllegalMessageIdentifierException - in case the message number is not registered with the sequence.
java.lang.UnsupportedOperationException - in case the sequence is inbound and does not support generating message identifiers

acknowledgeMessageIds

void acknowledgeMessageIds(java.util.List<Sequence.AckRange> ranges)
                           throws IllegalMessageIdentifierException,
                                  java.lang.IllegalStateException
Registers given message identifiers with the sequence as aknowledged

Parameters:
ranges - message identifier ranges to be acknowledged
Throws:
IllegalMessageIdentifierException - in case this is an InboundSequence instance and a messages with the given identifiers have been already registered
java.lang.IllegalStateException - in case the sequence is closed

acknowledgeMessageId

void acknowledgeMessageId(long messageId)
                          throws IllegalMessageIdentifierException,
                                 java.lang.IllegalStateException
Registers given message identifier with the sequence as aknowledged

Parameters:
messageId - message identifier to be acknowledged
Throws:
IllegalMessageIdentifierException - in case this is an InboundSequence instance and a message with the given identifier has been already registered
java.lang.IllegalStateException - in case the sequence is closed

isAcknowledged

boolean isAcknowledged(long messageId)
Determines whether such message number has been already acknowledged on the sequence or not.

Parameters:
messageId - message identifier to test
Returns:
true or false depending on whether a message with such message identifer has been already acknowledged or not

getLastMessageId

long getLastMessageId()
Provides information on the last message id sent on this sequence

Returns:
last message identifier registered on this sequence

getAcknowledgedMessageIds

java.util.List<Sequence.AckRange> getAcknowledgedMessageIds()
Provides a collection of ranges of messages identifier acknowledged with the sequence

Returns:
collection of ranges of messages identifier registered with the sequence

hasPendingAcknowledgements

boolean hasPendingAcknowledgements()
The method may be called to determine whether the sequence has some unacknowledged messages or not

Returns:
true if the sequence has any unacknowledged message identifiers, false otherwise

getStatus

Sequence.Status getStatus()
Provides information on the status of the message sequence

Returns:
current status of the message sequence

setAckRequestedFlag

void setAckRequestedFlag()
This method should be called to set the AckRequested flag, which indicates a pending request for acknowledgement of all message identifiers registered with this sequence.


clearAckRequestedFlag

void clearAckRequestedFlag()
This method should be called to clear the AckRequested flag, which indicates that any pending requests for acknowledgement of all message identifiers registered with this sequence were satisfied.


isAckRequested

boolean isAckRequested()
Provides information on the actual AckRequested flag status

Returns:
true if the AckRequested flag is set, false otherwise

getBoundSecurityTokenReferenceId

java.lang.String getBoundSecurityTokenReferenceId()
Provides information on a security session to which this sequence is bound to.

Returns:
security token reference identifier to which this sequence is bound to.

close

void close()
Closes the sequence. Subsequent calls to this method have no effect.

Once this method is called, any subsequent calls to the #getNextMessageId() method will result in a IllegalStateException being raised. It is however still possible to accept message identifier acknowledgements, as well as retrieve any other information on the sequence.


isClosed

boolean isClosed()
Provides information on the sequence closed status.

Returns:
true if the sequence has been closed, false otherwise

isExpired

boolean isExpired()
Provides information on the sequence expiration status.

Returns:
true if the sequence has already expired, false otherwise

getLastActivityTime

long getLastActivityTime()
Provides information on the last activity time of this sequence

Returns:
last actiit time on the sequence in miliseconds

updateLastActivityTime

void updateLastActivityTime()
Manually updates the last activit time of the sequence to present time


preDestroy

void preDestroy()
The method is called during the sequence termination to allow sequence object to release its allocated resources