public interface MessageHandle extends Handle
Solclient.Allocator.newMessageHandle(). The MessageHandle object so created
must be associated with a Solace Messsage Buffer by calling
Solclient.createMessageForHandle(). Both these operations are provided by
the convenience method,
Solclient.createNewMessageAndHandle().
Solclient.createMessageForHandle(). This binds the MessageHandle to a Solace
message buffer that must be released by the application when it is finished
with the message. Message buffers are released by calling
MessageHandle.destroy().
Applications are responsible for releasing all message buffers they allocate.
Message buffers received by callback are owned by the API and must
not be released. However the application may also take ownership of
these message buffers by invoking
MessageSupport.takeRxMessage() using the Handle received in the
onMessage() method. If the application takes ownership of the
Message Buffer in this way, it must call
MessageHandle.destroy() to release the message when it
is finished with the message buffer.
MessageHandle.setReplyTo(com.solacesystems.solclientj.core.resource.Destination)).
MessageHandle.setSenderId(java.lang.String)). This field can
be automatically generated when the session property
SessionHandle.PROPERTIES.GENERATE_SENDER_ID is enabled. When this
property is enabled, and the SenderId is not explicitly set, the session
ClientName is used as the SenderId.The SenderID is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.
MessageHandle.setApplicationMessageType(java.lang.String)). The ApplicationMessageType is user-defined,
carried end-to-end, and can also be matched in a selector, but otherwise is not relevant
to the event broker.In JMS applications this fields is carried as the JMSType Message Header Field.
MessageHandle.setApplicationMessageId(java.lang.String)). The ApplicationMessageId is user-defined,
carried end-to-end, and can also be matched in a selector, but otherwise is not relevant
to the event broker.In JMS applications this fields is carried as the JMSMessageID Message Header Field.
MessageHandle.setSequenceNumber(long)), set by Publisher. This field may be
automatically generated when the session property
SessionHandle.PROPERTIES.GENERATE_SEQUENCE_NUMBER is enabled. When
this property is enabled, and the Sequence Number is not explicitly set, a
unique and increasing sequence number is generated for each sent message.The SequenceNo is user-defined, carried end-to-end, and can also be matched in a selector, but otherwise is not relevant to the event broker.
MessageHandle.setCorrelationId(java.lang.String)). The CorrelationId is user-defined,
carried end-to-end, and can also be matched in a selector, but otherwise is not relevant
to the event broker. The CorrelationId may be used for peer-to-peer message synchronization.In JMS applications this fields is carried as the JMSCorrelationID Message Header Field.
MessageHandle.setSenderTimestamp(long)). This field may be automatically generated when
the session property
SessionHandle.PROPERTIES.GENERATE_SEND_TIMESTAMPS is enabled in the
sending API.
SessionHandle.PROPERTIES.GENERATE_RCV_TIMESTAMPS
is enabled in the receiving API.
MessageHandle.setMessageDeliveryMode(int) to set one of the following delivery
modes:
SolEnum.MessageDeliveryMode.DIRECT
SolEnum.MessageDeliveryMode.PERSISTENT
SolEnum.MessageDeliveryMode.NONPERSISTENT
SolEnum.MessageDeliveryMode.DIRECT for the fast reliable delivery (not
Guaranteed), known as Direct Delivery.
To provide the best possible latency and throughput, the C API does
NOT copy the contents of the message. The message contents
are maintained internally, exactly as presented to SessionHandle.send(com.solacesystems.solclientj.core.handle.MessageHandle),
until the message is acknowledged by the Solace Messaging Appliance. In the
event that a message needs to be recovered by retransmission, the contents
are seamlessly redelivered.
The message correlation key is provided as a convenient location for an
application to store stateful information. The correlation key is returned to
the application with the
SolEnum.SessionEventCode.ACKNOWLEDGEMENT event.
MessageHandle.setQueuePartitionKey(java.lang.String)).| Modifier and Type | Method and Description |
|---|---|
void |
deleteApplicationMessageId()
Deletes the previously set Application Message Id
|
void |
deleteApplicationMessageType()
Deletes the previously set Application Message Type
|
void |
deleteCorrelationId()
Deletes the previously set Correlation Id
|
void |
deleteHttpContentEncoding()
Deletes the previously set HTTP Content Encoding
|
void |
deleteHttpContentType()
Deletes the previously set HTTP Content Type
|
void |
deleteQueuePartitionKey()
This method allows the application to delete the queue partition key for the message.
|
void |
deleteSenderId()
Deletes the previously set senderId
|
void |
deleteSenderTimestamp()
Deletes a previously set Sender Timestamp
|
void |
deleteSequenceNumber()
Deletes a previously set Sequence Number
|
java.lang.String |
dump(int dumpMode)
Display the contents of a message in human-readable form.
|
java.lang.String |
dump(int dumpMode,
int maxStrLen)
Display the contents of a message in human-readable form.
|
boolean |
getAckImmediately()
Returns the ACK Immediately message property.
|
java.lang.String |
getApplicationMessageId()
This method allows the application to retrieve the string that
is the ApplicationMessageId.
|
java.lang.String |
getApplicationMessageType()
This method allows the application to retrieve the String that is
the ApplicationMessageType.
|
int |
getBinaryAttachment(java.nio.ByteBuffer content)
Retrieve the contents of the binary attachment part into a given
ByteBuffer. |
int |
getBinaryAttachmentSize()
Retrieve the size of the Binary Attachment
|
int |
getCacheRequestId(MutableLong cacheRequestId)
If a received message contains a message returned from SolCache due to a
previously issued cache request (
CacheSessionHandle.sendCacheRequest), then the received message will
also contain the cache requestId set by the application in the cache
request. |
int |
getCacheStatus() |
java.lang.String |
getCorrelationId()
This method allows the application to retrieve the string that
is the CorrelationId.
|
int |
getCorrelationKey(MutableLong correlationKey)
Fetch the CorrelationKey into a MutableLong if available.
|
boolean |
getDeliverToOne()
Deprecated.
New applications should use shared subscriptions instead.
|
int |
getDeliveryCount()
Get message delivery count
|
Destination |
getDestination()
Get the
Destination field (queue or topic), which is the
destination this message was published to. |
MutableTopic |
getDestination(MutableTopic mutableTopic)
Get the
Destination field (mutable topic), which is the
destination this message was published to. |
java.lang.String |
getDestinationTopicSuffix(SessionHandle in_sessionHandle)
This method returns the suffix of the topic string.
|
boolean |
getDiscardIndication()
Test the discard indication status.
|
boolean |
getDMQEligible()
Test the Dead Message Queue (DMQ) eligible property.
|
boolean |
getElidingEligible()
Test the ElidingEligible attribute.
|
long |
getExpiration()
Return the Message Expiration timestamp.
|
long |
getGuaranteedMessageId()
The Guaranteed MessageId is a identifier in each received message on a
FlowHanlde. |
java.lang.String |
getHttpContentEncoding() |
java.lang.String |
getHttpContentType() |
int |
getMessageDeliveryMode() |
int |
getPriority()
Get message priority.
|
java.lang.String |
getQueuePartitionKey()
This method allows the application to retrieve the queue partition key for the message.
|
long |
getReceiveTimestamp()
Gets the receive timestamp (in milliseconds, from midnight, January 1,
1970 UTC).
|
int |
getReplicationGroupMessageIdForHandle(ReplicationGroupMessageIdHandle replicationGroupMessageIdHandle)
Sets the Replication Group Message Id (ReplicationGroupMessageId) of the message into the passed in ReplicationGroupMessageIdHandle.
|
Destination |
getReplyTo() |
MutableTopic |
getReplyTo(MutableTopic mutableTopic) |
java.lang.String |
getSenderId()
This method allows the application to retrieve the string that
is the SenderID.
|
int |
getSenderTimestamp(MutableLong senderTimerstamp) |
int |
getSequenceNumber(MutableLong sequenceNumber)
Get message sequence number into the MutableLong parameter.
|
long |
getTimeToLive()
get the Time To Live (TTL) from a message.
|
int |
getUserCos()
Get the Class of Service from a message.
|
int |
getUserData(java.nio.ByteBuffer userDataBuffer)
Copies the User Data header bytes into the userDataBuffer.
|
boolean |
isRedelivered()
Applies only when
SolEnum.MessageDeliveryMode is
SolEnum.MessageDeliveryMode.PERSISTENT or
SolEnum.MessageDeliveryMode.NONPERSISTENT. |
boolean |
isReplyMessage() |
void |
setAckImmediately(boolean ackImmediately)
Set the optional ACK Immediately message property.
|
void |
setApplicationMessageId(java.lang.String appMsgId) |
void |
setApplicationMessageType(java.lang.String appMsgType)
This method allows the application to set
the ApplicationMessageType.
|
void |
setAsReplyMessage(boolean asReplyMessage)
Set the reply attribute of the message.
|
void |
setBinaryAttachment(byte[] content)
Set the contents of the binary attachment part by copying in from the
given
byte[] array. |
void |
setBinaryAttachment(byte[] content,
int offset,
int length)
Set the contents of the binary attachment part by copying in a range of
data from the given
byte[] array. |
void |
setBinaryAttachment(java.nio.ByteBuffer binaryAttachment)
Set the contents of the binary attachment part by copying in from the
given
ByteBuffer. |
void |
setCorrelationId(java.lang.String correlationId)
Set the Correlation Id in the binary meta data header.
|
void |
setCorrelationIdFromMessage(MessageHandle respondToMessageHandle)
This convenience method is a shortcut that allows an application to populate
the CorrelationId of an
MessageHandler by copying the CorrelationId of
the given MessageHandle. |
void |
setCorrelationKey(long tag)
Sets the correlation key on the given message.
|
void |
setDeliverToOne(boolean dto)
Deprecated.
New applications should use shared subscriptions instead.
|
void |
setDestination(Destination destination)
|
void |
setDestinationFromMessageReplyTo(MessageHandle messageHandle)
This convenience method is a shortcut that allows an application to set
the Destination of an
MessageHandler by copying the Reply-To of
the given MessageHandle. |
void |
setDMQEligible(boolean dmqEligible)
Set the Dead Message Queue (DMQ) eligible property on a message.
|
void |
setElidingEligible(boolean eld)
Set the ElidingEligible property on a message.
|
void |
setExpiration(long exp)
Set the expiration time field.
|
void |
setHttpContentEncoding(java.lang.String contentEncoding)
Set the HTTP Content Encoding in the binary meta data header.
|
void |
setHttpContentType(java.lang.String contentType)
Set the HTTP Content Type in the binary meta data header.
|
void |
setMessageDeliveryMode(int mode) |
void |
setPriority(int priority)
Set message priority.
|
void |
setQueuePartitionKey(java.lang.String queuePartitionKey)
This method allows the application to set the queue partition key for the message.
|
void |
setReplyTo(Destination destination)
* Performance Tip: If your application is setting the
ReplyTo address on many messages to the same destination or set of
destinations consider using
NativeDestinationHandle to create a
set of NativeDestination objects that can be re-used. |
void |
setReplyToSuffix(SessionHandle in_sessionHandle,
java.lang.String replyToSuffix)
Append an application-specified suffix to the default topic destination
for the Session.
|
void |
setSenderId(java.lang.String senderId)
Set the SenderId.
|
void |
setSenderTimestamp(long ts)
Set the Sender Timestamp field.
|
void |
setSequenceNumber(long sequenceNumber)
Set the Sequence Number in the message.
|
void |
setTimeToLive(long ttl)
Set the Time To Live (TTL) for a message.
|
void |
setUserCos(int userCos)
Set the Class of Service to use for transmission.
|
void |
setUserData(byte[] userData)
Set the contents of the User Data header by copying in from the given
byte[] array. |
void |
setUserData(byte[] userData,
int offset,
int length)
Set the contents of the User Data header by copying in a range of data
from the given
byte[] array. |
void |
setUserData(java.nio.ByteBuffer userDataBuffer)
Set the contents of the message User Data header by copying in from the
given
ByteBuffer. |
int getBinaryAttachment(java.nio.ByteBuffer content)
throws SolclientException
ByteBuffer. The message binary attachment is copied into the
byteBuffer at the Buffer.position() and the
Buffer.position() is updated before return. If the
Buffer.limit() is not sufficient to copy out all the binary
attachment, no data is copied and a SolclientException is thrown.
As described above, this operations effectively 'puts' the binary attachment
into the given ByteBuffer. Programmers should treat this operation just as they would
any other ByteBuffer.put(byte) operation. As the ByteBuffer#position() has been moved,
it is necessary to Buffer.flip() the ByteBuffer to read all the data out of
it. Alternatively, if a Buffer.mark() is set before the call to getBinaryAttachment(),
then the application may use Buffer.reset() to set position to just the binary attachment data.
content - (direct ByteBuffer is recommended)SolclientExceptionMessageHandle.setBinaryAttachment(ByteBuffer)int getBinaryAttachmentSize()
throws SolclientException
SolclientExceptionvoid setBinaryAttachment(java.nio.ByteBuffer binaryAttachment)
throws SolclientException
ByteBuffer. This causes memory to be allocated from API
internal or heap storage. If any binary attachment previously existed it
will be first removed before the new data is copied in. The data from the
Buffer.position() to the Buffer.limit() is copied to
the messagge binary attachment. The Buffer.position()
is updated before return.
Passing in a NULL reference removes any existing binary attachment from the message.
As described above, this operations effectively 'gets' the binary attachment
from the given ByteBuffer. Programmers should treat this operation just as they would
any other ByteBuffer.get() operation. As the ByteBuffer#position() has been moved,
it is necessary to Buffer.flip() the ByteBuffer to use the data again, for instance to
setBinaryAttachment in another message.
Alternatively, if a Buffer.mark() is set before the call to setBinaryAttachment(),
then the application may use Buffer.reset() to set position back to the binary attachment data.
binaryAttachment - A ByteBuffer containing data to copy to the Solace
Message. The Buffer.position() and
Buffer.limit() determine the contents copied.SolclientExceptionMessageHandle.getBinaryAttachment(ByteBuffer)void setBinaryAttachment(byte[] content)
throws SolclientException
byte[] array. This causes memory to be allocated from API
internal or heap storage. If any binary attachment previously existed it
will be first removed before the new data is copied in.content - A byte[] array containing data to copy to the Solace
Message. The entire byte array is copied.SolclientExceptionvoid setBinaryAttachment(byte[] content,
int offset,
int length)
throws SolclientException
byte[] array. This causes memory to be
allocated from API internal or heap storage. If any binary attachment
previously existed it will be first removed before the new data is copied
in.content - A byte[] array containing data to copy to the Solace
Message.offset - The start index of valid data in the arraylength - The amount of data to copy from the start index.SolclientExceptionvoid setDestination(Destination destination) throws SolclientException
Queue,
Topic or
MutableTopic) on the
given message. A destination can be removed from the message by passing
NULL as an argument.
Performance Tip: If your application is sending messages
to the same destination or set of destinations consider using
NativeDestinationHandle to create a set of NativeDestination
objects that can be re-used. NativeDestinations are saved in the
underlying C-SDK and avoid conversion from Java String to Ascii string on
every call to setDestination().
destination - DestinationSolclientExceptionvoid setDestinationFromMessageReplyTo(MessageHandle messageHandle) throws SolclientException
MessageHandler by copying the Reply-To of
the given MessageHandle. This is a common operation in applications that are
building a response to a received message.
Performance Tip: This method avoids constructing
java object instances when you need to copy the Reply-To Destination from a received
MessageHandle to a message built in response. If your application is sensitive
to garbage collection, setDestinationFromMessageReplyTo() is preferable to
MessageHandle.getReplyTo() followed by setDestination().
messageHandle - MessageHandle - if null, nothing will be copied.SolclientExceptionMessageHandle.setDestination(com.solacesystems.solclientj.core.resource.Destination),
MessageHandle.getReplyTo()int getCorrelationKey(MutableLong correlationKey) throws SolclientException
MessageHandle.setCorrelationKey(long)) by an application
when sending Guaranteed messages. The CorrelationKey is available in the
SessionEvent
when the
SolEnum.SessionEventCode.ACKNOWLEDGEMENT or
SolEnum.SessionEventCode.REJECTED_MSG_ERROR is received.
The CorrelationKey has local significance only.. This
method will alway return
SolEnum.ReturnCode.NOT_FOUND on received Messages. The CorrelationKey
can only be retrieved from Message Buffers after the application has
called (MessageHandle.setCorrelationKey(long)).
correlationKey - A non NULL MutableLong, on method return it will contain the
CorrelationKey if available.SolEnum.ReturnCodeSolclientExceptionvoid setCorrelationKey(long tag)
throws SolclientException
SolEnum.MessageDeliveryMode.PERSISTENT or
SolEnum.MessageDeliveryMode.NONPERSISTENT mode may set the Correlation
Tag. If this method is used, the CorrelationKey is available when the
SolEnum.SessionEventCode.ACKNOWLEDGEMENT or
SolEnum.SessionEventCode.REJECTED_MSG_ERROR event is later received. The
SessionEvent
returned with the event contains the CorrelationKey. Important:
The CorrelationKey is not included in the transmitted message and
is only used with the local API.
This causes memory to be allocated from internal or heap storage.
tag - A 64-bit CorrelationKey.SolclientExceptionvoid setQueuePartitionKey(java.lang.String queuePartitionKey)
throws SolclientException
queuePartitionKey - A String to set as the queuePartitionKey.SolclientExceptionMessageHandle.getQueuePartitionKey()java.lang.String getQueuePartitionKey()
throws SolclientException
SolclientExceptionMessageHandle.setQueuePartitionKey(java.lang.String)void deleteQueuePartitionKey()
throws SolclientException
SolclientExceptionMessageHandle.deleteQueuePartitionKey()long getGuaranteedMessageId()
throws SolclientException
FlowHanlde.
This MessageId is unique only for the flow and it can only be used to
acknowledge the message which will remove the message
from the message spool on the Solace Appliance. No other meaning should
be inferred from the the value of the message ID.
Messages are acknowledged by calling
FlowHandle.ack(msgId).
Note: Typically applications will simply acknowldedge the received
message by MessageHandle (
FlowHandle.ack(rxMsgHandle). Therefore this method will be rarely
required.
SolclientExceptionint getCacheRequestId(MutableLong cacheRequestId) throws SolclientException
CacheSessionHandle.sendCacheRequest), then the received message will
also contain the cache requestId set by the application in the cache
request. This method retrieves the cache requestId.cacheRequestId - A non NULL MutableLong, on method return it will contain the
cache request id if one is available.SolEnum.ReturnCode.OK or
SolEnum.ReturnCode.NOT_FOUND if the MessageHandle does not
contain a received cached message.SolclientExceptionint getCacheStatus()
throws SolclientException
@Deprecated
void setDeliverToOne(boolean dto)
throws SolclientException
When a direct message has the Deliver-To-One property set, it can be delivered only to one client. For a Guaranteed Delivery message, this behavior only applies to the "demoted" direct copy of this message.
dto - false - clear, true - set.SolclientException@Deprecated
boolean getDeliverToOne()
throws SolclientException
SolclientExceptionvoid setMessageDeliveryMode(int mode)
throws SolclientException
mode - The delivery mode to use for this message. It can be one of
the following:
SolclientExceptionint getMessageDeliveryMode()
throws SolclientException
boolean getDiscardIndication()
throws SolclientException
SolclientExceptionvoid setDMQEligible(boolean dmqEligible)
throws SolclientException
dmqEligible - false - clear, true - set.SolclientExceptionMessageHandle.setTimeToLive(long)boolean getDMQEligible()
throws SolclientException
SolclientExceptionMessageHandle.setDMQEligible(boolean)void setElidingEligible(boolean eld)
throws SolclientException
Time-based eliding ensures that subscriber applications always receive only the most current update of a published topic at a rate that they can manage. By limiting the incoming message rate, a subscriber application is able to avoid a message backlog filled with outdated messages.
This property does not indicate whether the message was elided or even provide information about the subscriber's configuration (with regards to Message Eliding).
eld - A Boolean that indicates whether to set or reset the Eliding
Eligible attribute.SolclientExceptionboolean getElidingEligible()
throws SolclientException
SolclientExceptionvoid setExpiration(long exp)
throws SolclientException
MessageHandle.setTimeToLive(long) to enforce message expiry in the network. In
fact when MessageHandle.setTimeToLive(long) is used, setting this property has
no effect. When MessageHandle.setTimeToLive(long) is called, The expiration
time is never carried in the message, however it may be calculated and
retrieved by the sender if the session property
SessionHandle.PROPERTIES.CALCULATE_MESSAGE_EXPIRATION is enabled.
Thus if MessageHandle.getExpiration() is called after the message is sent, a
calculated expiration time is returned based on the Time To Live.
Note: When MessageHandle.setTimeToLive(long) is set on a
message, the receiving client may also calculate the expiration time if
it has enabled the session property
SessionHandle.PROPERTIES.CALCULATE_MESSAGE_EXPIRATION.
exp - The sender timestamp value to set. The value is in
milliseconds.SolclientExceptionMessageHandle.getExpiration()long getExpiration()
throws SolclientException
SessionHandle.PROPERTIES.CALCULATE_MESSAGE_EXPIRATION is enabled,
the expiration time is calculated based on the message Time To Live. When
enabled, the expiration time for sent messages will be the UTC time when
the message is sent plus the Time To Live. The expiration time for
received messages is the UTC time when the message was received plus the
Time To Live in the message at the time it was received.
* If the expiration time is not set in the message, and it cannot be calculated, this method returns zero.
SolclientExceptionMessageHandle.setExpiration(long)boolean isReplyMessage()
throws SolclientException
SessionHandle.sendRequest(com.solacesystems.solclientj.core.handle.MessageHandle, com.solacesystems.solclientj.core.handle.MessageHandle, int).SolclientExceptionMessageHandle.setAsReplyMessage(boolean),
SessionHandle.sendReply(MessageHandle, MessageHandle)void setAsReplyMessage(boolean asReplyMessage)
throws SolclientException
SessionHandle.send(com.solacesystems.solclientj.core.handle.MessageHandle) is
used instead of SessionHandle.sendReply(com.solacesystems.solclientj.core.handle.MessageHandle, com.solacesystems.solclientj.core.handle.MessageHandle)asReplyMessage - A Boolean that indicates whether to set or reset the reply
attribute.SolclientExceptionlong getReceiveTimestamp()
throws SolclientException
SolclientExceptionboolean isRedelivered()
throws SolclientException
SolEnum.MessageDeliveryMode is
SolEnum.MessageDeliveryMode.PERSISTENT or
SolEnum.MessageDeliveryMode.NONPERSISTENT. Indicates if the message has
been delivered by the Appliance to the API before.SolclientExceptionvoid setSenderTimestamp(long ts)
throws SolclientException
SessionHandle.PROPERTIES.GENERATE_SEND_TIMESTAMPS session property and
sets the specified Sender Timestamp value in the message binary meta data
header.ts - The sender timestamp value to set. The value is in
milliseconds.SolclientExceptionint getSenderTimestamp(MutableLong senderTimerstamp) throws SolclientException
senderTimerstamp - A non NULL MutableLong, on method return it will contain the
SenderTimestamp if available.SolEnum.ReturnCode.OK or
SolEnum.ReturnCode.NOT_FOUND if the Sender Timestamp is not
present in the message binary meta data header.SolclientExceptionMessageHandle.setSenderTimestamp(long)void deleteSenderTimestamp()
throws SolclientException
SolclientExceptionMessageHandle.setSenderTimestamp(long)int getSequenceNumber(MutableLong sequenceNumber) throws SolclientException
SessionHandle.PROPERTIES.GENERATE_SEQUENCE_NUMBER is enabled.
This method allows the application to retrieve the value that
is the SequenceNo. The SequenceNo is user-defined,
carried end-to-end, and can also be matched in a selector, but otherwise is not relevant
to the event broker.sequenceNumber - A non NULL MutableLong, on method return it will contain the
message sequence number if available.SolEnum.ReturnCode.OK or
SolEnum.ReturnCode.NOT_FOUND if the Sequence Number is not
present in the message binary meta data header.SolclientExceptionvoid setSequenceNumber(long sequenceNumber)
throws SolclientException
SessionHandle.PROPERTIES.GENERATE_SEQUENCE_NUMBER session property and
forces the specified Sequence Number into the message binary meta data
header. This does not change the internal sequence
numbering and the next generated sequence number will still be one more
than the last generated sequence number.
A sequence number is automatically included (if not already present) in
the Solace-defined fields for each message sent if the session property
SessionHandle.PROPERTIES.GENERATE_SEQUENCE_NUMBER is enabled.
The SequenceNo is user-defined,
carried end-to-end, and can also be matched in a selector, but otherwise is not relevant
to the event broker.sequenceNumber - SolclientExceptionvoid deleteSequenceNumber()
throws SolclientException
SolclientExceptionMessageHandle.setSequenceNumber(long)void setTimeToLive(long ttl)
throws SolclientException
This property is only valid for Guaranteed messages (Persistent and Non-Persistent). It has no effect when used in conjunction with other message types unless the message is promoted by the appliance to a Guaranteed message.
ttl - value in milliseconds to use for message time to live.SolclientExceptionMessageHandle.setDMQEligible(boolean),
MessageHandle.setExpiration(long)long getTimeToLive()
throws SolclientException
SolclientExceptionMessageHandle.setTimeToLive(long)void setUserCos(int userCos)
throws SolclientException
userCos - SolEnum.UserCosSolclientExceptionint getUserCos()
throws SolclientException
SolEnum.UserCos, one of:
SolclientExceptionvoid setReplyToSuffix(SessionHandle in_sessionHandle, java.lang.String replyToSuffix) throws SolclientException
SessionHandle.sendRequest() automatically adds a replyTo destination
derived by appending './#' to the unique topic destination.
When this function is used, a delimiter ('/') and the supplied string are appended instead.
in_sessionHandle - - SessionHandle used to derive the base destination address.replyToSuffix - - The String to append to the base destination address.SolclientExceptionMessageHandle.getDestinationTopicSuffix(com.solacesystems.solclientj.core.handle.SessionHandle)java.lang.String getDestinationTopicSuffix(SessionHandle in_sessionHandle) throws SolclientException
in_sessionHandle - The SessionHandle for the session on which the message was
received.SolclientExceptionMessageHandle.setReplyToSuffix(com.solacesystems.solclientj.core.handle.SessionHandle, java.lang.String)void setUserData(java.nio.ByteBuffer userDataBuffer)
throws SolclientException
ByteBuffer. This causes memory to be allocated from API
internal or heap storage. If any User Data header previously existed it
will be first removed before the new data is copied in. The data from the
Buffer.position() to the Buffer.limit() is copied to
the message User Data header. The Buffer.position()
is updated before return.
Passing in a NULL reference removes any existing User data header from the message.
The maximum size allowed for the user data part is 36 bytes.
As described above, this operations effectively 'gets' the user data
from the given ByteBuffer. Programmers should treat this operation just as they would
any other ByteBuffer.get() operation. As the ByteBuffer#position() has been moved,
it is necessary to Buffer.flip() the ByteBuffer to use the data again, for instance to
setUserData in another message.
Alternatively, if a Buffer.mark() is set before the call to setUserData(),
then the application may use Buffer.reset() to set position back to the user data.
userDataBuffer - A ByteBuffer containing data to copy to the Solace
Message. The Buffer.position() and
Buffer.limit() determine the contents copied.SolclientExceptionMessageHandle.getUserData(ByteBuffer)int getUserData(java.nio.ByteBuffer userDataBuffer)
throws SolclientException
ByteBuffer with room for 36 bytes or more. The message
User Data header is copied into the userDataBuffer at the
Buffer.position() and the Buffer.position() is
updated before return. If the Buffer.limit() is not
sufficient to copy out all the User Data header, no data is copied and a
SolclientException is thrown.
As described above, this operations effectively 'puts' the User Data header
into the given ByteBuffer. Programmers should treat this operation just as they would
any other ByteBuffer.put(byte) operation. As the ByteBuffer#position() has been moved,
it is necessary to Buffer.flip() the ByteBuffer to read all the data out of
it. Alternatively, if a Buffer.mark() is set before the call to getUserData(),
then the application may use Buffer.reset() to set position to just the User Data.
userDataBuffer - (direct ByteBuffer is recommended)SolclientExceptionMessageHandle.setUserData(ByteBuffer)void setUserData(byte[] userData)
throws SolclientException
byte[] array. This causes memory to be allocated from API
internal or heap storage. If any User Data header previously existed it
will be first removed before the new data is copied in.
The maximum length of the User Data header is 36 bytes. If the given
byte[] array is larger than 36 bytes a SolclientException
is thrown.
userData - A byte[] array containing data to copy to the Solace
Message. The entire byte array is copied.SolclientExceptionvoid setUserData(byte[] userData,
int offset,
int length)
throws SolclientException
byte[] array. This causes memory to be allocated
from API internal or heap storage. If any User Data header previously
existed it will be first removed before the new data is copied in.userData - A byte[] array containing data to copy to the Solace
Message.offset - The start index of valid data in the arraylength - The amount of data to copy from the start index. If the
length is greater than 36 a SolclientException is
thrown.SolclientExceptionvoid setSenderId(java.lang.String senderId)
throws SolclientException
SessionHandle.PROPERTIES.GENERATE_SENDER_ID session property and forces
the specified SenderId into the binary meta data header.
This method allows the application to set the contents of the
SenderID. The SenderID is user-defined, carried end-to-end, and
can also be matched in a selector but otherwise is not relevant
to the event broker.senderId - The String to set as SenderId.SolclientExceptionMessageHandle.getSenderId()void deleteSenderId()
throws SolclientException
SolclientExceptionMessageHandle.setSenderId(java.lang.String)java.lang.String getSenderId()
throws SolclientException
SolclientExceptionMessageHandle.setSenderId(java.lang.String)java.lang.String getApplicationMessageId()
throws SolclientException
SolclientExceptionMessageHandle.setApplicationMessageId(java.lang.String)void setApplicationMessageId(java.lang.String appMsgId)
throws SolclientException
appMsgId - A String to set as the ApplicationMessageId.SolclientExceptionMessageHandle.getApplicationMessageId()void deleteApplicationMessageId()
throws SolclientException
SolclientExceptionMessageHandle.setApplicationMessageId(java.lang.String)java.lang.String getApplicationMessageType()
throws SolclientException
SolclientExceptionMessageHandle.setApplicationMessageType(java.lang.String)void setApplicationMessageType(java.lang.String appMsgType)
throws SolclientException
appMsgType - A String to set as the ApplicationMessageTypeSolclientExceptionMessageHandle.getApplicationMessageType()void deleteApplicationMessageType()
throws SolclientException
SolclientExceptionMessageHandle.setApplicationMessageType(java.lang.String)Destination getReplyTo() throws SolclientException
Destination instance
Note: The returned Destination object is
allocated from the heap and could cause garbage collection
interruptions when it is no longer referenced. Applications
sensitive to garbage collection should avoid using this method.
Consider if MessageHandle.setDestinationFromMessageReplyTo(MessageHandle) is more suitable.
SolclientExceptionMessageHandle.setDestinationFromMessageReplyTo(MessageHandle),
MessageHandle.setReplyTo(com.solacesystems.solclientj.core.resource.Destination)MutableTopic getReplyTo(MutableTopic mutableTopic) throws SolclientException
mutableTopic - the MutableTopicMutableTopic instance
Note: The returned MutableTopic object is
allocated from the heap and could cause garbage collection
interruptions when it is no longer referenced. Applications
sensitive to garbage collection should avoid using this method.
Consider if MessageHandle.setDestinationFromMessageReplyTo(MessageHandle) is more suitable.
SolclientExceptionMessageHandle.setDestinationFromMessageReplyTo(MessageHandle),
MessageHandle.setReplyTo(com.solacesystems.solclientj.core.resource.Destination)void setReplyTo(Destination destination) throws SolclientException
NativeDestinationHandle to create a
set of NativeDestination objects that can be re-used. NativeDestinations
are saved in the underlying C-SDK and avoid conversion from Java String
to Ascii string on every call to setDestination().destination - A destination object that will be set as the ReplyTo address
on the message. The destination may be NULL to remove the
ReplyTo header from the message.SolclientExceptionMessageHandle.getReplyTo()java.lang.String getCorrelationId()
throws SolclientException
MessageHandle.setCorrelationIdFromMessage(MessageHandle) is more suitable.SolclientExceptionMessageHandle.setCorrelationIdFromMessage(MessageHandle),
MessageHandle.setCorrelationId(java.lang.String)void setCorrelationId(java.lang.String correlationId)
throws SolclientException
correlationId - the String to set as the CorrelationIdSolclientExceptionMessageHandle.getCorrelationId()void setCorrelationIdFromMessage(MessageHandle respondToMessageHandle) throws SolclientException
MessageHandler by copying the CorrelationId of
the given MessageHandle. This is a common operation in applications that are
building a response to a received message.
Performance Tip: This method avoids constructing
java object instances when you need to copy the CorrelationId from a received
MessageHandle to a message built in response. If your application is sensitive
to garbage collection, setCorrelationIdFromMessage() is preferable to
MessageHandle.getCorrelationId().
respondToMessageHandle - MessageHandle - if null, nothing will be copied.SolclientExceptionMessageHandle.getCorrelationId()void deleteCorrelationId()
throws SolclientException
SolclientExceptionMessageHandle.setCorrelationId(java.lang.String)void setAckImmediately(boolean ackImmediately)
throws SolclientException
When the ACK Immediately property is set to true on an outgoing Guaranteed Delivery message, it indicates that the appliance should ACK this message immediately upon receipt. By default the property is set to false on newly created messages.
This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not expect the property value indicates how the message was originally published. Therefore if a received message is forwarded by the application, the ACK immediately property should be explicitly set to the desired value (true or false).
Setting this property on an outgoing
SolEnum.MessageDeliveryMode.DIRECT message has no effect.
ackImmediately - A Boolean that indicates whether to set or clear the ACK
Immediately message property.SolclientExceptionboolean getAckImmediately()
throws SolclientException
This property, when set by a publisher, may or may not be removed by the appliance prior to delivery to a consumer, so message consumers must not expect the property value indicates how the message was originally published
SolclientExceptionDestination getDestination() throws SolclientException
Destination field (queue or topic), which is the
destination this message was published to.SolclientExceptionMutableTopic getDestination(MutableTopic mutableTopic) throws SolclientException
Destination field (mutable topic), which is the
destination this message was published to. The MutableTopic object provided
as an argument contains the Destination on return. For convenience this
method also returns a reference to the MutableTopic passed as an argument.
No objects are allocated by using this method.mutableTopic - the MutableTopicSolclientExceptionjava.lang.String dump(int dumpMode)
throws SolclientException
dumpMode - SolEnum.MessageDumpMode. Possible values are:
SolEnum.MessageDumpMode.BRIEF. Display only the length of the
binary attachment, xml attachment, and user property map.
SolEnum.MessageDumpMode.FULL. Display the entire message.
SolclientExceptionMessageHandle.dump(int, int)java.lang.String dump(int dumpMode,
int maxStrLen)
throws SolclientException
dumpMode - SolEnum.MessageDumpMode. Possible values are:
SolEnum.MessageDumpMode.BRIEF. Display only the length of the
binary attachment, xml attachment, and user property map.
SolEnum.MessageDumpMode.FULL. Display the entire message.
maxStrLen - Maximum size of the String returned.SolclientExceptionMessageHandle.dump(int)java.lang.String getHttpContentType()
throws SolclientException
SolclientExceptionMessageHandle.setHttpContentType(java.lang.String)void setHttpContentType(java.lang.String contentType)
throws SolclientException
contentType - the String to set as the HTTP Content Type.SolclientExceptionMessageHandle.getHttpContentType()void deleteHttpContentType()
throws SolclientException
SolclientExceptionMessageHandle.setHttpContentType(java.lang.String)java.lang.String getHttpContentEncoding()
throws SolclientException
SolclientExceptionMessageHandle.setHttpContentEncoding(java.lang.String)void setHttpContentEncoding(java.lang.String contentEncoding)
throws SolclientException
contentEncoding - the String to set as the HTTP Content EncodingSolclientExceptionMessageHandle.getHttpContentEncoding()void deleteHttpContentEncoding()
throws SolclientException
SolclientExceptionMessageHandle.setHttpContentEncoding(java.lang.String)void setPriority(int priority)
throws SolclientException
priority - Priority value. The valid value range is 0-255 with 0 as the lowest priority and 255 as the highest, or -1 to delete priority.SolclientExceptionint getPriority()
throws SolclientException
SolclientExceptionint getDeliveryCount()
throws SolclientException
SolclientExceptionint getReplicationGroupMessageIdForHandle(ReplicationGroupMessageIdHandle replicationGroupMessageIdHandle)
Copyright 2004-2025 Solace Corporation. All rights reserved.