UM Java API 6.17.1

- Main Page
- Related Pages
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | List of all members
com.latencybusters.lbm.LBMMessage Class Reference

## Public Member Functions
LBMMessage | promote ()
ByteBuffer | getMessagesBuffer ()
void | dispose ()
LBMApplicationHeaderChain | applicationHeaderChain () throws LBMException
boolean | hasApplicationHeaderChain ()
int | type ()
int | flags ()
long | sequenceNumber ()
LBMMessageProperties | properties ()
byte[] | data ()
long | dataLength ()
ByteBuffer | dataBuffer ()
String | dataString ()
String | source ()
char[] | sourceAsCharArray ()
String | proxySource ()
char[] | proxySourceAsCharArray ()
String | topicName ()
char[] | topicNameAsCharArray ()
LBMMessageChannelInfo | channelInfo ()
long | firstFragmentSequenceNumber ()
long | fragmentOffset ()
long | totalMessageLength ()
boolean | isFragment ()
void | respond (byte[] data, int dataLength, int flags) throws LBMException
long | sourceRegistrationId ()
long | receiverRegistrationId ()
UMQMessageId | queueMessageId ()
long | timestampSeconds ()
long | timestampMicroseconds ()
long | hrTimestampSeconds ()
long | hrTimestampNanoseconds ()
long | deliveryLatencyNanos () throws LBMException
boolean | isFromGateway ()
long | originalSequenceNumber ()
String | originalSource ()
char[] | originalSourceAsCharArray ()
long | hfSequenceNumber ()
BigInteger | hfSequenceNumberBigInt ()
UMERegistrationSuccessInfo | registrationSuccessInfo ()
UMERegistrationCompleteInfo | registrationCompleteInfo ()
UMEDeregistrationSuccessInfo | deregistrationSuccessInfo ()
UMEDeregistrationCompleteInfo | deregistrationCompleteInfo ()
UMQRegistrationCompleteInfo | queueRegistrationCompleteInfo ()
UMQDeregistrationCompleteInfo | queueDeregistrationCompleteInfo ()
UMQIndexAssignedInfo | queueIndexAssignedInfo ()
UMQIndexReleasedInfo | queueIndexReleasedInfo ()
UMQIndexAssignmentEligibilityStartCompleteInfo | queueIndexAssignmentEligibilityStartCompleteInfo ()
UMQIndexAssignmentEligibilityStopCompleteInfo | queueIndexAssignmentEligibilityStopCompleteInfo ()
UMQIndexInfo | queueIndexInfo () throws LBMException
boolean | canSendExplicitAck ()
void | sendExplicitAck () throws LBMException
void | reassign (int flags) throws LBMException
long | osqn ()
Object | sourceClientObject ()
UMEMessageAck | extractUMEAck () throws LBMException
byte[] | serializedResponse () throws LBMException
void | getSerializedResponse (LBMSerializedResponse serializedResponse) throws LBMException

## Detailed Description

Encapsulates all LBM messages.

Messages are delivered via the receiver callback. It is possible to retain a message for further processing after the receiver callback returns by calling promote() and saving the message. The application must call dispose() for each and every message when processing is completed. See Java Message Reception.

Access message data via dataBuffer() and dataLength() to preserve "Zero Object Delivery" (ZOD). See Zero Object Delivery.

For older, object-based delivery (non-ZOD), you may access message data via data(), which creates a byte array object that contains the message data. This method has lower performance.

## Member Function Documentation

LBMApplicationHeaderChain com.latencybusters.lbm.LBMMessage.applicationHeaderChain | ( |  | ) | throws LBMException

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

Returns
  Application header chain.

Exceptions

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

LBMMessageChannelInfo com.latencybusters.lbm.LBMMessage.channelInfo | ( |  | ) |

Object containing channel information included with the message.

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

byte [] com.latencybusters.lbm.LBMMessage.data | ( |  | ) |

Message data.

Returns
  byte array containing message data

Referenced by com.latencybusters.lbm.LBMMessage.dataString().

ByteBuffer com.latencybusters.lbm.LBMMessage.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. Message data starts at position 0.

If this message has been promoted, the returned byte buffer will have a backing array (non-direct).

If this message was delivered via SMX, this method will copy the message data from the transport into a ByteBuffer allocated with a backing array (non-direct). For more information on getting SMX message data, see getMessagesBuffer().

Returns
  ByteBuffer containing message data

References com.latencybusters.lbm.LBM.MSG_DATA.

Referenced by com.latencybusters.lbm.LBMContext.allocTopic(), com.latencybusters.lbm.LBMMessage.getMessagesBuffer(), and com.latencybusters.lbm.LBMRequest.removeResponseCallback().

long com.latencybusters.lbm.LBMMessage.dataLength | ( |  | ) |

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

Returns
  Message data length, in bytes.

String com.latencybusters.lbm.LBMMessage.dataString | ( |  | ) |

Message string data.

Returns
  Message data converted to String

References com.latencybusters.lbm.LBMMessage.data().

UMEDeregistrationCompleteInfo com.latencybusters.lbm.LBMMessage.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

UMEDeregistrationSuccessInfo com.latencybusters.lbm.LBMMessage.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

void com.latencybusters.lbm.LBMMessage.dispose | ( |  | ) |

Dispose of memory associated with this message. Every received message must be disposed after processing is complete. See Java Message Reception.

If this message is delivered from a persistent receiver, deleting the message might signal consumption of the message, depending on the use case. See Persistence Message Consumption for a full explanation of consumption acknowledgements.

See also
  LBMContext::close
  LBMReceiver::close
  LBMWildcardReceiver::close

UMEMessageAck com.latencybusters.lbm.LBMMessage.extractUMEAck | ( |  | ) | throws LBMException

Retrieves the ack structure from a UME message.

Exceptions

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

Returns
  UMEMessageAck object

References com.latencybusters.lbm.LBM.EINVAL.

long com.latencybusters.lbm.LBMMessage.firstFragmentSequenceNumber | ( |  | ) |

LBM sequence number of the first fragment of the current message

Returns
  Sequence number of the first message fragment

int com.latencybusters.lbm.LBMMessage.flags | ( |  | ) |

LBM message flags.

Returns
  LBM message flags.

See also
  LBM

long com.latencybusters.lbm.LBMMessage.fragmentOffset | ( |  | ) |

Byte offset of the current fragment within the associated message.

Returns
  Byte offset of the current fragment

ByteBuffer com.latencybusters.lbm.LBMMessage.getMessagesBuffer | ( |  | ) |

Return a DirectByteBuffer view of the entire transport if this message has not been promoted. The buffer has its position and limit values set to where the message data begins and ends. Only this portion of the buffer is valid for this message. The purpose is to provide zero copy access to the message data. This is different than dataBuffer() which has message data always starting at position 0. If dataBuffer() is called on an smx transport message, the message data is copied from the transport into another buffer to preserve these semantics.

If the application has called promote() on this message, the view of the transport is no longer valid and the data has been copied. In this case, this method will return the same thing as dataBuffer().

Only LBT-SMX transports currently support this method. The return value will be null If this message did not come from an LBT-SMX transport or has no message data.

Returns
  View of messages buffer with position and limit set to where message data is stored or null

References com.latencybusters.lbm.LBMMessage.dataBuffer(), com.latencybusters.lbm.LBM.MSG_DATA, and com.latencybusters.lbm.LBMMessage.source().

void com.latencybusters.lbm.LBMMessage.getSerializedResponse | ( | LBMSerializedResponse | serializedResponse | ) | throws LBMException

Gets the serialized response information from a message so it can be sent to and used by another application to respond.

Exceptions

  LBMException | if there were problems getting the serialized response information or there was no response information in the message.

See also
  LBMContext::respond

References com.latencybusters.lbm.LBM.EINVAL.

boolean com.latencybusters.lbm.LBMMessage.hasApplicationHeaderChain | ( |  | ) |

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

See also
  LBMMessage::applicationHeaderChain()

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

long com.latencybusters.lbm.LBMMessage.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.

See also
  LBMSourceSendExInfo::getHfSequenceNumberBigInt

Returns
  Hot-failover sequence number

References com.latencybusters.lbm.LBM.MSG_FLAG_HF_32, and com.latencybusters.lbm.LBM.MSG_FLAG_HF_64.

Referenced by com.latencybusters.lbm.LBMMessage.hfSequenceNumberBigInt().

BigInteger com.latencybusters.lbm.LBMMessage.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.

See also
  LBMSourceSendExInfo::getHfSequenceNumber

Returns
  Hot-failover sequence number

References com.latencybusters.lbm.LBMMessage.hfSequenceNumber().

long com.latencybusters.lbm.LBMMessage.hrTimestampNanoseconds | ( |  | ) |

Nanoseconds portion of the high resolution timestamp indicating when the message was received.

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

References com.latencybusters.lbm.LBM.EINVAL.

long com.latencybusters.lbm.LBMMessage.hrTimestampSeconds | ( |  | ) |

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

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

boolean com.latencybusters.lbm.LBMMessage.isFragment | ( |  | ) |

Determine if the current message is a single fragment of a larger, multi-fragment message.

Note that this method will not return true unless:

- ordered_delivery (receiver) is set to "0" (zero), and
- the application message required UM fragmentation.

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

boolean com.latencybusters.lbm.LBMMessage.isFromGateway | ( |  | ) |

Whether or not the message arrived via a gateway.

Returns
  boolean indicating if it arrived via a gateway.

Deprecated:
  No replacement

long com.latencybusters.lbm.LBMMessage.originalSequenceNumber | ( |  | ) |

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

Returns
  Original sequence number.

Deprecated:
  No replacement

String com.latencybusters.lbm.LBMMessage.originalSource | ( |  | ) |

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

Returns
  Original message source.

Deprecated:
  No replacement

char [] com.latencybusters.lbm.LBMMessage.originalSourceAsCharArray | ( |  | ) |

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

Returns
  Original message source as character array.

Deprecated:
  No replacement

long com.latencybusters.lbm.LBMMessage.osqn | ( |  | ) |

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

Returns
  Message original sequence number

LBMMessage com.latencybusters.lbm.LBMMessage.promote | ( |  | ) |

Inform UM that the application is going to retain ownership of a UM message object after the receiver callback returns.

This function should be called from inside a receiver callback function to prevent UM from automatically deleting the message when the callback function returns. This allows the message to be passed to a different part of the application, perhaps a different thread, for processing after the receiver callback returns.

Once promoted, the application has the responsibility to dispose of the message when it is finished with it by calling dispose(). See Java Message Reception.

Note that this creates a new object, so delivery is no longer "zero object".

Note
  the message must be promoted before being made available to the other parts of the application. For example, it would not be legal for a separate thread to start processing the message before the receiver callback called promote.

Warning
  promote() is NOT thread safe; do not call it on the same message from multiple threads at the same time.

Returns
  The promoted message. This will be a new message object, not the message object passed into the receiver callback.

Referenced by com.latencybusters.lbm.UMQQueueMessageStatus.flags().

String com.latencybusters.lbm.LBMMessage.proxySource | ( |  | ) |

Message proxySource

Returns
  Message proxy source string. Only valid for hotlinked receiver BOS/EOS events. See Hotlink Source Strings.

char [] com.latencybusters.lbm.LBMMessage.proxySourceAsCharArray | ( |  | ) |

Message proxySourceAsCharArray

Returns
  Message proxy source as character array

UMQDeregistrationCompleteInfo com.latencybusters.lbm.LBMMessage.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

UMQIndexAssignedInfo com.latencybusters.lbm.LBMMessage.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

UMQIndexAssignmentEligibilityStartCompleteInfo com.latencybusters.lbm.LBMMessage.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

UMQIndexAssignmentEligibilityStopCompleteInfo com.latencybusters.lbm.LBMMessage.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

UMQIndexInfo com.latencybusters.lbm.LBMMessage.queueIndexInfo | ( |  | ) | throws LBMException

Retrieve UMQ index information for this message.

Returns
  UMQIndexInfo object holding index information, or null if no index information is present.

Exceptions

  LBMException | if an internal error occurs

Since
  UMQ 1.2

References com.latencybusters.lbm.UMQIndexInfo.setIndex(), com.latencybusters.lbm.UMQIndexInfo.setNumericIndex(), and com.latencybusters.lbm.LBM.UMQ_INDEX_FLAG_NUMERIC.

UMQIndexReleasedInfo com.latencybusters.lbm.LBMMessage.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

UMQMessageId com.latencybusters.lbm.LBMMessage.queueMessageId | ( |  | ) |

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

Returns
  The message ID assigned by the queue.

UMQRegistrationCompleteInfo com.latencybusters.lbm.LBMMessage.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

void com.latencybusters.lbm.LBMMessage.reassign | ( | int | flags | ) | throws LBMException

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

Exceptions

  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

Parameters

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

long com.latencybusters.lbm.LBMMessage.receiverRegistrationId | ( |  | ) |

The registration ID for the receiver (UME only).

Returns
  The registration ID for the receiver.

References com.latencybusters.lbm.LBM.MSG_UME_REGISTRATION_SUCCESS.

UMERegistrationCompleteInfo com.latencybusters.lbm.LBMMessage.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

UMERegistrationSuccessInfo com.latencybusters.lbm.LBMMessage.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

void com.latencybusters.lbm.LBMMessage.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.

Exceptions

  LBMException | if any error occurs sending the response.

See also
  LBM::SRC_NONBLOCK
  LBM::SRC_BLOCK

References com.latencybusters.lbm.LBM.EINVAL, and com.latencybusters.lbm.LBM.MSG_REQUEST.

void com.latencybusters.lbm.LBMMessage.sendExplicitAck | ( |  | ) | throws LBMException

Send a consumption acknowledgement to the persistent Store.

This function is used in the Explicit Acknowledgments use case to signal consumption of the supplied message, and all unacknowledged messages sent before it. ume_explicit_ack_only (receiver) must be set to 1.

Warning
  If explicit ACKs are used, the application must ensure that messages are ACKed in the order received. See ACK Ordering.

See Persistence Message Consumption for a full explanation of consumption acknowledgements.

Exceptions

  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

long com.latencybusters.lbm.LBMMessage.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.

See also
  osqn
  hfSequenceNumber

Returns
  LBM message (or message fragment) sequence number

String com.latencybusters.lbm.LBMMessage.source | ( |  | ) |

Message source

Returns
  Message source string

Referenced by com.latencybusters.lbm.LBMMessage.getMessagesBuffer().

char [] com.latencybusters.lbm.LBMMessage.sourceAsCharArray | ( |  | ) |

Message sourceAsCharArray

Returns
  Message source as character array

Object com.latencybusters.lbm.LBMMessage.sourceClientObject | ( |  | ) |

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

Returns
  Source client object.

Since
  LBM 3.3, UME 2.0

long com.latencybusters.lbm.LBMMessage.sourceRegistrationId | ( |  | ) |

The registration ID for the source (UME only).

Returns
  The registration ID for the source.

References com.latencybusters.lbm.LBM.MSG_UME_REGISTRATION_SUCCESS.

long com.latencybusters.lbm.LBMMessage.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.

long com.latencybusters.lbm.LBMMessage.timestampSeconds | ( |  | ) |

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

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

String com.latencybusters.lbm.LBMMessage.topicName | ( |  | ) |

Topic on which the current message has been delivered.

Returns
  Topic name string

char [] com.latencybusters.lbm.LBMMessage.topicNameAsCharArray | ( |  | ) |

Message topicNameAsCharArray

Returns
  Topic name as character array

long com.latencybusters.lbm.LBMMessage.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.

int com.latencybusters.lbm.LBMMessage.type | ( |  | ) |

LBM message type.

Returns
  LBM message type

See also
  LBM

The documentation for this class was generated from the following file:

- LBMMessage.java