com.latencybusters.lbm
Class LBMMessage

java.lang.Object
  com.latencybusters.lbm.LBMMessage

public class LBMMessage
extends java.lang.Object

Encapsulates all LBM messages.

Call dispose() to utilize Zero Object Delivery (ZOD), or promote() to retain message object after callback. You must call either one or the other.

When using ZOD, access message data via dataPointer() and length().

For object-based delivery (non-ZOD), access message data with data(), which creates a byte array object that contains the message data.

Constructor Summary

LBMMessage()

Method Summary

LBMApplicationHeaderChain	applicationHeaderChain() Get the application header chain, if any, associated with this message.
boolean	canSendExplicitAck()
LBMMessageChannelInfo	channelInfo() Object containing channel information included with the message.
byte[]	data() Message data.
java.nio.ByteBuffer	dataBuffer() Message data as a direct ByteBuffer.
long	dataLength() Message data length.
java.lang.String	dataString() Message string data.
long	deliveryLatencyNanos()
UMEDeregistrationCompleteInfo	deregistrationCompleteInfo() Get an extended registration complete info object from the message (only for LBM.MSG_UME_DEREGISTRATION_COMPLETE_EX messages).
UMEDeregistrationSuccessInfo	deregistrationSuccessInfo() Get an extended deregistration success info object from the message (only for LBM.MSG_UME_DEREGISTRATION_SUCCESS_EX messages).
void	dispose() Dispose of memory associated with this message, and send UME implicit ACK for UME receivers.
UMEMessageAck	extractUMEAck() Retrieves the ack structure from a UME message.
long	firstFragmentSequenceNumber() LBM sequence number of the first fragment of the current message
int	flags() LBM message flags.
long	fragmentOffset() Byte offset of the current fragment within the associated message.
boolean	hasApplicationHeaderChain() Check to see if this message contains any application header chain data.
long	hfSequenceNumber() Get the hot failover sequence number as a long.
java.math.BigInteger	hfSequenceNumberBigInt() Get the hot failover sequence number as a BigInteger.
boolean	isFragment() Returns true if the current object is actually a message fragment.
boolean	isFromGateway() Deprecated. No replacement
long	originalSequenceNumber() Deprecated. No replacement
java.lang.String	originalSource() Deprecated. No replacement
char[]	originalSourceAsCharArray() Deprecated. No replacement
long	osqn() Retrieve the message original sequence number set by the UM library.
LBMMessage	promote() Promotes the current LBMMessage to a full-fledged LBMMessage object that can be referenced and used past the end of the receiver callback.
LBMMessageProperties	properties()
UMQDeregistrationCompleteInfo	queueDeregistrationCompleteInfo() Get an extended queue deregistration complete info object from the message (only for LBM.MSG_UMQ_DEREGISTRATION_COMPLETE_EX messages).
UMQIndexAssignedInfo	queueIndexAssignedInfo() Get a queue index assigned info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNED_EX messages).
UMQIndexAssignmentEligibilityStartCompleteInfo	queueIndexAssignmentEligibilityStartCompleteInfo() Get a queue index assignment eligibility start complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX messages).
UMQIndexAssignmentEligibilityStopCompleteInfo	queueIndexAssignmentEligibilityStopCompleteInfo() Get a queue index assignment eligibility stop complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX messages).
UMQIndexInfo	queueIndexInfo() Retrieve UMQ index information for this message.
UMQIndexReleasedInfo	queueIndexReleasedInfo() Get a queue index released info object from the message (only for LBM.MSG_UMQ_INDEX_RELEASED_EX messages).
UMQMessageId	queueMessageId() The message ID assigned by the queue (UMQ only).
UMQRegistrationCompleteInfo	queueRegistrationCompleteInfo() Get an extended queue registration complete info object from the message (only for LBM.MSG_UMQ_REGISTRATION_COMPLETE_EX messages).
void	reassign(int flags) Do not acknowledge the given message and instead request that the message be reassigned.
long	receiverRegistrationId() The registration ID for the receiver (UME only).
UMERegistrationCompleteInfo	registrationCompleteInfo() Get an extended registration complete info object from the message (only for LBM.MSG_UME_REGISTRATION_COMPLETE_EX messages).
UMERegistrationSuccessInfo	registrationSuccessInfo() Get an extended registration success info object from the message (only for LBM.MSG_UME_REGISTRATION_SUCCESS_EX messages).
void	respond(byte[] data, int dataLength, int flags) Send a response for this request message.
void	sendExplicitAck() Send an explicit ACK for this message (UME only).
long	sequenceNumber() LBM message (or message fragment) sequence number.
java.lang.String	source() Message source
char[]	sourceAsCharArray() Message sourceAsCharArray
java.lang.Object	sourceClientObject() Get the source client object, set by an LBMSourceCreationCallback callback.
long	sourceRegistrationId() The registration ID for the source (UME only).
long	timestampMicroseconds() Microseconds portion of the timestamp indicating when the message was received.
long	timestampSeconds() Seconds portion of the timestamp indicating when the message was received.
java.lang.String	topicName() Topic on which the current message has been delivered.
char[]	topicNameAsCharArray() Message topicNameAsCharArray
long	totalMessageLength() Total message size.
int	type() LBM message type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LBMMessage

public LBMMessage()

Method Detail

promote

public LBMMessage promote()

Promotes the current LBMMessage to a full-fledged LBMMessage object that can be referenced and used past the end of the receiver callback. Note that this creates a new object, so delivery is no longer "zero object". Calling promote() multiple times beyond the first call has no effect. The LBMMessage object must be promoted (or disposed) prior to closing the receiver or context object.

CAUTION: promote() is NOT thread safe; do not call it on the same message from multiple threads at the same time. Note that there should never be any reason to do so.

dispose

public void dispose()

Dispose of memory associated with this message, and send UME implicit ACK for UME receivers. The LBMMessage object must be disposed (or promoted) prior to closing the receiver or context object.

Note: dispose MUST be called on messages that contain application header chains. To check if a message contains an application header chain, use hasApplicationHeaderChain(). Note: UME receivers MUST call dispose() on each LBMMessage object when and only when the application is completely finished with the LBMMessage.

See Also:

LBMContext.close(), LBMReceiverBase.close(), LBMReceiverBase.close()

applicationHeaderChain

public LBMApplicationHeaderChain applicationHeaderChain()
                                                 throws LBMException

Get the application header chain, if any, associated with this message.

Returns:

Application header chain.

Throws:

LBMEInvalException - if the message contains no application header data, LBMException if another error occurs.

LBMException

hasApplicationHeaderChain

public boolean hasApplicationHeaderChain()

Check to see if this message contains any application header chain data.

Returns:

True if the message has an application header chain, false otherwise.

See Also:

applicationHeaderChain()

type

public int type()

LBM message type.

Returns:

LBM message type

See Also:

LBM

flags

public int flags()

LBM message flags.

Returns:

LBM message flags.

See Also:

LBM

sequenceNumber

public long sequenceNumber()

LBM message (or message fragment) sequence number. When the message is 32 bit hot-failover, this will be the hot-failover sequence number. When 64 bit hot failover, this will always be 0.

Returns:

LBM message (or message fragment) sequence number

See Also:

osqn, hfSequenceNumber

properties

public LBMMessageProperties properties()

data

public byte[] data()

Message data.

Returns:

byte array containing message data

dataLength

public long dataLength()

Message data length. For ZOD, use this in conjunction with dataBuffer().

Returns:

Message data length, in bytes.

dataBuffer

public java.nio.ByteBuffer dataBuffer()

Message data as a direct ByteBuffer. For ZOD, use in conjunction with dataLength() to determine how many bytes in the buffer are actually valid, since buffers are generally larger than actual message data.

dataString

public java.lang.String dataString()

Message string data.

Returns:

Message data converted to String

source

public java.lang.String source()

Message source

Returns:

Message source string

sourceAsCharArray

public char[] sourceAsCharArray()

Message sourceAsCharArray

Returns:

Message source as character array

topicName

public java.lang.String topicName()

Topic on which the current message has been delivered.

Returns:

Topic name string

topicNameAsCharArray

public char[] topicNameAsCharArray()

Message topicNameAsCharArray

Returns:

Topic name as character array

channelInfo

public LBMMessageChannelInfo channelInfo()

Object containing channel information included with the message.

Returns:

Channel info object, or null if no channel information is present.

firstFragmentSequenceNumber

public long firstFragmentSequenceNumber()

LBM sequence number of the first fragment of the current message

Returns:

Sequence number of the first message fragment

fragmentOffset

public long fragmentOffset()

Byte offset of the current fragment within the associated message.

Returns:

Byte offset of the current fragment

totalMessageLength

public long totalMessageLength()

Total message size. This value may be larger than the length of the data byte array, if the current object represents a message fragment.

Returns:

Total size (in bytes) of the current message.

isFragment

public boolean isFragment()

Returns true if the current object is actually a message fragment.

Returns:

true if the current object is a message fragment; otherwise, false.

respond

public void respond(byte[] data,
                    int dataLength,
                    int flags)
             throws LBMException

Send a response for this request message.

Warning: It is not safe to call this method from a context thread callback.

Parameters:

data - Data to send in this response

dataLength - Number of bytes of data to send in this response

flags - Flags indicating various conditions. See next section for possible OR'd set of values.

Throws:

LBMException - if any error occurs sending the response.

See Also:

LBM.SRC_NONBLOCK, LBM.SRC_BLOCK

sourceRegistrationId

public long sourceRegistrationId()

The registration ID for the source (UME only).

Returns:

The registration ID for the source.

receiverRegistrationId

public long receiverRegistrationId()

The registration ID for the receiver (UME only).

Returns:

The registration ID for the receiver.

queueMessageId

public UMQMessageId queueMessageId()

The message ID assigned by the queue (UMQ only).

Returns:

The message ID assigned by the queue.

timestampSeconds

public long timestampSeconds()

Seconds portion of the timestamp indicating when the message was received.

Returns:

Number of whole seconds since Midnight, January 1st 1970 UTC.

timestampMicroseconds

public long timestampMicroseconds()

Microseconds portion of the timestamp indicating when the message was received.

Returns:

Number of fractional seconds since Midnight, January 1st 1970 UTC, represented as an integer number of microseconds.

deliveryLatencyNanos

public long deliveryLatencyNanos()
                          throws LBMException

Throws:

LBMException

isFromGateway

public boolean isFromGateway()

Deprecated. No replacement

Whether or not the message arrived via a gateway.

Returns:

boolean indicating if it arrived via a gateway.

originalSequenceNumber

public long originalSequenceNumber()

Deprecated. No replacement

Original sequence number (if the message arrived via a gateway).

Returns:

Original sequence number.

originalSource

public java.lang.String originalSource()

Deprecated. No replacement

Original message source (if the message arrived via a gateway).

Returns:

Original message source.

originalSourceAsCharArray

public char[] originalSourceAsCharArray()

Deprecated. No replacement

Original message source (if the message arrived via a gateway) as char array.

Returns:

Original message source as character array.

hfSequenceNumber

public long hfSequenceNumber()

Get the hot failover sequence number as a long. Since Java does not have unsigned integers this will return the signed long value of either the 32 or 64 bit hot-failover sequence number as specified by LBMMessage.flags(). 64 bit sequence numbers can appear negative and should be handled accordingly.

Returns:

Hot-failover sequence number

See Also:

#getHfSequenceNumberBigInt

hfSequenceNumberBigInt

public java.math.BigInteger hfSequenceNumberBigInt()

Get the hot failover sequence number as a BigInteger. Since Java does not have unsigned integers, this is provided to ensure all possible hot failover sequence numbers are given with a positive value. This method is a convenience when using 64 bit sequence numbers, and simply interprets the long value as if it were unsigned.

Returns:

Hot-failover sequence number

See Also:

#getHfSequenceNumber

registrationSuccessInfo

public UMERegistrationSuccessInfo registrationSuccessInfo()

Get an extended registration success info object from the message (only for LBM.MSG_UME_REGISTRATION_SUCCESS_EX messages).

Returns:

UMERegistrationSuccessInfo object holding extended registration success info.

Since:

UME 2.0

See Also:

#storeRegistrationSuccessInfo

registrationCompleteInfo

public UMERegistrationCompleteInfo registrationCompleteInfo()

Get an extended registration complete info object from the message (only for LBM.MSG_UME_REGISTRATION_COMPLETE_EX messages).

Returns:

UMERegistrationCompleteInfo object holding extended registration complete info.

Since:

UME 2.0

deregistrationSuccessInfo

public UMEDeregistrationSuccessInfo deregistrationSuccessInfo()

Get an extended deregistration success info object from the message (only for LBM.MSG_UME_DEREGISTRATION_SUCCESS_EX messages).

Returns:

UMEDeregistrationSuccessInfo object holding extended deregistration success info.

Since:

UME 5.3

See Also:

#storeDeregistrationSuccessInfo

deregistrationCompleteInfo

public UMEDeregistrationCompleteInfo deregistrationCompleteInfo()

Get an extended registration complete info object from the message (only for LBM.MSG_UME_DEREGISTRATION_COMPLETE_EX messages).

Returns:

UMEDeregistrationCompleteInfo object holding extended deregistration complete info.

Since:

UME 5.3

queueRegistrationCompleteInfo

public UMQRegistrationCompleteInfo queueRegistrationCompleteInfo()

Get an extended queue registration complete info object from the message (only for LBM.MSG_UMQ_REGISTRATION_COMPLETE_EX messages).

Returns:

UMQRegistrationCompleteInfo object holding extended registration complete info.

Since:

UME 3.0

queueDeregistrationCompleteInfo

public UMQDeregistrationCompleteInfo queueDeregistrationCompleteInfo()

Get an extended queue deregistration complete info object from the message (only for LBM.MSG_UMQ_DEREGISTRATION_COMPLETE_EX messages).

Returns:

UMQDrregistrationCompleteInfo object holding extended deregistration complete info.

Since:

UME 3.0

queueIndexAssignedInfo

public UMQIndexAssignedInfo queueIndexAssignedInfo()

Get a queue index assigned info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNED_EX messages).

Returns:

UMQIndexAssignedInfo object holding extended index assignment info.

Since:

UMQ 1.2

queueIndexReleasedInfo

public UMQIndexReleasedInfo queueIndexReleasedInfo()

Get a queue index released info object from the message (only for LBM.MSG_UMQ_INDEX_RELEASED_EX messages).

Returns:

UMQIndexReleasedInfo object holding extended index release info.

Since:

UMQ 1.2

queueIndexAssignmentEligibilityStartCompleteInfo

public UMQIndexAssignmentEligibilityStartCompleteInfo queueIndexAssignmentEligibilityStartCompleteInfo()

Get a queue index assignment eligibility start complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX messages).

Returns:

UMQIndexAssignmentEligibilityStartCompleteInfo object holding extended index assignment eligibility start complete info.

Since:

UMQ 1.2

queueIndexAssignmentEligibilityStopCompleteInfo

public UMQIndexAssignmentEligibilityStopCompleteInfo queueIndexAssignmentEligibilityStopCompleteInfo()

Get a queue index assignment eligibility stop complete info object from the message (only for LBM.MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX messages).

Returns:

UMQIndexAssignmentEligibilityStopCompleteInfo object holding extended index assignment eligibility stop complete info.

Since:

UMQ 1.2

queueIndexInfo

public UMQIndexInfo queueIndexInfo()
                            throws LBMException

Retrieve UMQ index information for this message.

Returns:

UMQIndexInfo object holding index information

Throws:

LBMException

Since:

UMQ 1.2

canSendExplicitAck

public boolean canSendExplicitAck()

sendExplicitAck

public void sendExplicitAck()
                     throws LBMException

Send an explicit ACK for this message (UME only).

Throws:

LBMException - if any error occurs or the message object is not valid, or if dispose() has already been called on this LBMMessage.

Since:

UME 2.0

reassign

public void reassign(int flags)
              throws LBMException

Do not acknowledge the given message and instead request that the message be reassigned.

Parameters:

flags - Flags indicating various conditions. ORed set of values: LBM.MSG_UMQ_REASSIGN_FLAG_DISCARD

Throws:

LBMException - if any error occurs or the message object is not valid, or if dispose() has already been called on this LBMMessage.

Since:

UMQ 2.2

osqn

public long osqn()

Retrieve the message original sequence number set by the UM library.

Returns:

Message original sequence number

sourceClientObject

public java.lang.Object sourceClientObject()

Get the source client object, set by an LBMSourceCreationCallback callback.

Returns:

Source client object.

Since:

LBM 3.3, UME 2.0

extractUMEAck

public UMEMessageAck extractUMEAck()
                            throws LBMException

Retrieves the ack structure from a UME message.

Returns:

UMEMessageAck object

Throws:

LBMException - if the message has already been disposed, ACK'd, or was not a UME message