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

All Known Implementing Classes:
AbstractSequence, InboundSequence, OutboundSequence

@ManagedData
@Description(value="Reliable Messaging Sequence")
public interface Sequence

Author:
Marek Potociar (marek.potociar at sun.com)

Nested Class Summary
static class Sequence.AckRange
           
static class Sequence.IncompleteSequenceBehavior
           
static class Sequence.State
           
 
Field Summary
static long MAX_MESSAGE_ID
           
static long MIN_MESSAGE_ID
           
static long NO_EXPIRY
           
static long UNSPECIFIED_MESSAGE_ID
           
 
Method Summary
 void acknowledgeMessageNumber(long messageNumber)
          Marks given message number with the sequence as aknowledged
 void acknowledgeMessageNumbers(List<Sequence.AckRange> ranges)
          Marks given message numbers 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.
 List<Sequence.AckRange> getAcknowledgedMessageNumbers()
          Provides a collection of ranges of message numbers acknowledged with the sequence
 String getBoundSecurityTokenReferenceId()
          Provides information on a security session to which this sequence is bound to.
 DeliveryQueue getDeliveryQueue()
          Updates a delivery queue for this sequence with any unacknowledged messages that should be sent and returns the delivery queue instance.
 String getId()
          Returns unique identifier of the sequence
 long getLastActivityTime()
          Provides information on the last activity time of this sequence.
 long getLastMessageNumber()
          Provides information on the message number of the last message registered on this sequence
 Sequence.State getState()
          Provides information on the state of the message sequence
 boolean hasUnacknowledgedMessages()
          The method may be called to determine whether the sequence has some unacknowledged messages or not
 boolean isAcknowledged(long messageNumber)
          Is this message number acknowledged with the sequence?
 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.
 boolean isFailedOver(long messageNumber)
          Determines whether a given message number is registered as received, unacknowledged and failed over.
 boolean isStandaloneAcknowledgementRequestSchedulable(long delayPeriod)
          Determines whether a standalone acnowledgement request can be scheduled or not based on the #hasPendingAcknowledgements() value, last acknowledgement request time (see updateLastAcknowledgementRequestTime()) and delayPeriod parameter.
 void preDestroy()
          The method is called during the sequence termination to allow sequence object to release its allocated resources
 void registerMessage(ApplicationMessage message, boolean storeMessageFlag)
          Registers given message with the sequence
 ApplicationMessage retrieveMessage(String correlationId)
          Retrieves a message stored within the sequence under the provided correlationId if avalable.
 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 updateLastAcknowledgementRequestTime()
          Updates information on when was the last acknowledgement request for this sequence sent to current 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_EXPIRY

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

getId

@ManagedAttribute
@Description(value="Unique sequence identifier")
String getId()
Returns unique identifier of the sequence

Returns:
unique sequence identifier

getLastMessageNumber

@ManagedAttribute
@Description(value="Last message identifier register on this sequence")
long getLastMessageNumber()
Provides information on the message number of the last message registered on this sequence

Returns:
message number of the last message registered on this sequence

registerMessage

void registerMessage(@NotNull
                     ApplicationMessage message,
                     boolean storeMessageFlag)
                     throws DuplicateMessageRegistrationException,
                            AbstractSoapFaultException
Registers given message with the sequence

Parameters:
message - application message to be registered
storeMessageFlag - boolean flag indicating whether message should be stored until acknowledged or not
Throws:
DuplicateMessageNumberException - in case a message with such message number has already been registered with the sequence
AbstractSoapFaultException - in a case the sequence is closed or terminated
DuplicateMessageRegistrationException

retrieveMessage

@Nullable
ApplicationMessage retrieveMessage(@NotNull
                                            String correlationId)
Retrieves a message stored within the sequence under the provided correlationId if avalable. May return null if no stored message under given correlationId is available.

Availability of the message depends on the message identifier acknowledgement. Message, if stored (see registerMessage(com.sun.xml.ws.rx.rm.runtime.ApplicationMessage, boolean) 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 (if stored in memory) or removal.

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 - correlation identifier of the stored ApplicationMessage
Returns:
the message that is stored in the sequence if available, null otherwise.

getDeliveryQueue

DeliveryQueue getDeliveryQueue()
Updates a delivery queue for this sequence with any unacknowledged messages that should be sent and returns the delivery queue instance. Messages in the queue are the ones currently waiting for a delivery.

Returns:
delivery queue with a messages waiting for a delivery on this particular sequence

acknowledgeMessageNumbers

void acknowledgeMessageNumbers(List<Sequence.AckRange> ranges)
                               throws InvalidAcknowledgementException,
                                      AbstractSoapFaultException
Marks given message numbers with the sequence as aknowledged

Parameters:
ranges - message number ranges to be acknowledged
Throws:
InvalidAcknowledgementException - is generated when acked ranges contain a SequenceAcknowledgement covering messages that have not been sent.
AbstractSoapFaultException - in case the sequence is terminated

acknowledgeMessageNumber

void acknowledgeMessageNumber(long messageNumber)
                              throws AbstractSoapFaultException
Marks given message number with the sequence as aknowledged

Parameters:
messageNumber - message number to be acknowledged
Throws:
AbstractSoapFaultException - in case the sequence is terminated

isFailedOver

boolean isFailedOver(long messageNumber)
Determines whether a given message number is registered as received, unacknowledged and failed over.

Parameters:
messageNumber - message number to be tested
Returns:
true if the message number is registered as received, unacknowledged and failed over, false otherwise

getAcknowledgedMessageNumbers

List<Sequence.AckRange> getAcknowledgedMessageNumbers()
Provides a collection of ranges of message numbers acknowledged with the sequence

Returns:
collection of ranges of message numbers registered with the sequence

isAcknowledged

boolean isAcknowledged(long messageNumber)
Is this message number acknowledged with the sequence?

Parameters:
messageNumber - in a sequence
Returns:
true if acknowledged, otherwise false

hasUnacknowledgedMessages

@ManagedAttribute
@Description(value="True if the sequence has unacknowledged message identifiers")
boolean hasUnacknowledgedMessages()
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

getState

@ManagedAttribute
@Description(value="Runtime state of the sequence")
Sequence.State getState()
Provides information on the state of the message sequence

Returns:
current state 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

@ManagedAttribute
@Description(value="True if AckRequested flag set")
boolean isAckRequested()
Provides information on the actual AckRequested flag status

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

updateLastAcknowledgementRequestTime

void updateLastAcknowledgementRequestTime()
Updates information on when was the last acknowledgement request for this sequence sent to current time.


isStandaloneAcknowledgementRequestSchedulable

boolean isStandaloneAcknowledgementRequestSchedulable(long delayPeriod)
Determines whether a standalone acnowledgement request can be scheduled or not based on the #hasPendingAcknowledgements() value, last acknowledgement request time (see updateLastAcknowledgementRequestTime()) and delayPeriod parameter. Returns true if the sequence has any pending acknowledgements is set and last acknowledgement request time is older than delay period substracted from the current time. Returns false otherwise.

Parameters:
delayPeriod - delay period that should pass since the last acknowledgement request before an autonomous acnowledgement request is sent.
Returns:
true or false depending on whether

getBoundSecurityTokenReferenceId

@ManagedAttribute
@Description(value="The security token reference identifier to which this sequence is bound")
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

@ManagedAttribute
@Description(value="True if the sequence has been closed")
boolean isClosed()
Provides information on the sequence closed status.

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

isExpired

@ManagedAttribute
@Description(value="True if the sequence has expired")
boolean isExpired()
Provides information on the sequence expiration status.

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

getLastActivityTime

@ManagedAttribute
@Description(value="Last activity time on the sequence in milliseconds")
long getLastActivityTime()
Provides information on the last activity time of this sequence. Following is the list of operations invocation of which causes an update of last activity time:

Returns:
last activity time on the sequence in milliseconds

preDestroy

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



Copyright © 2005-2015 Oracle Corporation. All Rights Reserved.