10.26.0

IMessage Interface

The super interface of any message sent or received over this messaging API.

Client applications must dispose of messages (by calling Dispose()) as soon as they are done with them.

Note: Unless indicated otherwise, mutable IMessage's properties are accessed and assigned by value and not by reference. In other words, the property's getter returns a copy of the IMessage's mutable internal state and its setter takes a copy of the passed in mutable value.

Definition

Namespace: SolaceSystems.Solclient.Messaging
Assembly: SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 10.26.0
C#
public interface IMessage : IDisposable
Implements
IDisposable

Properties

AckImmediately When the ACKImmediately property is set to true on an outgoing Guaranteed Delivery message, it indicates that the appliance should ACK this message immediately upon receipt.

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 rely on this property being present. Setting this property on an outgoing direct message or on a received message has no effect.

Default: false
ADMessageId Applies to received messages only with DeliveryMode MessageDeliveryMode.PERSISTENT or MessageDeliveryMode.NON_PERSISTENT. Represents the message Id of a Guaranteed message. The message ID is only to be used for the purpose of acknowledgements. No other meaning should be inferred from the value of the message ID. Messages are acknowledged by calling Ack(Int64) If not available 0 is returned.
ApplicationMessageId Gets/sets the ApplicationMessageId. Returns null if not present.
ApplicationMessageType Gets/sets the ApplicationMessageType. If not present, null is returned.
BinaryAttachment The binary attachment part of the message. If not present, null is returned to the user.
CacheRequestId Returns the request ID set in the cache request. Always null if CacheStatus is MessageCacheStatus.Live If not present -1 is returned
CacheStatus Returns the MessageCacheStatus.
ConsumerIdList Applies to received messages only. Returns the Conusmer Id list, null if the received message has none. Consumer IDs are only used with XML content subscriptions, not with topic subscriptions. When XML subscriptions are applied with consumer IDs, received messages contain a list of the consumer IDs of all XML subscriptions that were a match to that received message. This allows the application to know which of its XML subscriptions were a match to the received message. If not present, null is returned.
CorrelationId Gets/sets the CorrelationId. If not present, null is returned.
CorrelationKey Applies to Guaranteed messages (where DeliveryMode is Persistent or Non-persistent). When set on a message, the correlation key is returned in a message acknowledgment event. If not present, null is returned. CorrelationKey is local to the current application, it is not transmitted on the wire.
DeliverToOne A setter/getter for the Deliver-To-One (DTO) property on a message with a Delivery mode of Direct. When a message has the DTO property set, it can to be delivered only to one client. For a Guaranteed Delivery message (see DeliveryMode), this behavior only applies to the "demoted" direct copy of this message.

This property is only supported by appliances running SolOS-TR.


Obsolete.
DeliveryCount Gives the message delivery count.

Throws OperationErrorException when delivery count is not support on the delivery of the message.

Note messages from browser flows will have the delivery of the next consumer delivery not the current message delivery count from the endpoint.

DeliveryMode A setter/getter for MessageDeliveryMode.
Destination The Destination to send to or receive on. For SolOS-Topic Routing (TR) it must be ITopic or IQueue (null is not a valid value when sending the message).
DiscardIndication Returns true if one or more messages have been discarded prior to the current message, otherwise it returns false. Indicates congestion discards only and is not affected by message eliding.
DMQEligible Expired messages with this property set to true are moved to a Dead Message Queue when one is provisioned on the appliance. Default: false
ElidingEligible Setting this property to true indicates that this message should be eligible for eliding.
Expiration The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is to expire. The expiration time is carried in the message when set to a non-zero value. Expiration time is not included when this value is set to zero.

Setting this property has no effect if the TimeToLive is set in the same message. The message expiration time is carried to clients that receive the message unmodified and does not affect the life cycle of the message. Set TimeToLive to a positive value to enforce message expiry in the network. When TimeToLive has a positive value, the Expiration is never carried in the message (defaulting to zero). However, it may be calculated and retrieved if the session property CalculateMessageExpiration is set to true.

if message Expiration time is not set in the message and the session property CalculateMessageExpiration is set to true, the Expiration time is calculated based on the message's TimeToLive. When enabled, the Expiration time retrieved will be the UTC time when the message is sent plus the message's TimeToLive. The Expiration time for received messages will be the UTC time when the message was received plus the TimeToLive of the message at the time it was received.

HttpContentEncoding The HTTP Content Encoding. If not present, null is returned.
HttpContentType The HTTP Content Type. If not present, null is returned.
IsReplyMessage Returns true if it is a reply message (reply to a request).
Priority Represents the message priority. The valid value range is 0-255 with 0 as the lowest priority and 255 as the highest. Returns null if not present.
ReceiverTimestamp Gets the receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present.
Redelivered Applies only when DeliveryMode is MessageDeliveryMode.PERSISTENT or MessageDeliveryMode.NON_PERSISTENT. Indicates if the message has been delivered by the appliance to the API before.
ReplicationGroupMessageId Represents the Replication Group Message ID (RGMID) of the message for guaranteed message set by the router can be null.
ReplyTo Represents the reply-to destination. Returns null if not present.
SenderId Gets/sets the SenderId. Returns null if not present.
SenderTimestamp Gets the sender timestamp (in milliseconds, from midnight, January 1, 1970 UTC). Returns -1 if not present or set.
SequenceNumber Gets/sets the SequenceNumber. Returns null if not present.
TimeToLive The number of milliseconds before the message is discarded or moved to a Dead Message Queue. A value of 0 means the message never expires. The default value is zero.

Note that this property is only valid for Guaranteed Delivery 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 Delivery message.

TopicSequenceNumber Represents the Topic Sequence Number assigned by the appliance or the peer. Returns null if none is present
UserCos A setter/getter for User Class of service.

The Class of Service has different semantics for direct and guaranteed messages. For direct messaging, it determines the WRR weight for the message. For guaranteed messaging, it indicates the discard eligibility of the message if the endpoint is congested (see LowPriorityMsgCongestion)

UserData The user data part of the message (maximum: 36 bytes). Returns null if not present.
UserPropertyMap Returns the user property map from the message's meta header. If no user property map is present in the message, this property is null. To create a new user property map use CreateUserPropertyMap instead.

After adding properties to this map, it must be closed; if not, it is automatically closed after the associated message is sent, or disposed IDisposable. Whether it is explicitly closed by the client application, or implicitly by the API, any attempt to use this map results in an OperationErrorException with ParamNullReference error subcode.

As a consequence to the above note, when caching the reference to this map (to avoid creating a new temporary object with each access), client applications should not use this reference after the associated message has been sent or disposed. At that point the cached user property map reference is invalid, and a new user map reference is required by calling IMessage.UserPropertyMap to access the user property map again.

XmlContent The XML content part of the message. Returns null if not present.

Methods

CreateUserPropertyMap Creates a user property map (of type IMapContainer) in the meta header of a message. Any existing user property map is overwritten. After adding user properties to this map, it must be closed; if not, it is automatically closed after the associated message is disposed IDisposable.

Whether it is explicitly closed by the client application, or implicitly by the API, any attempt to use this map results in an OperationErrorException with ParamNullReference

DisposePerforms application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from IDisposable)
Dump Returns a string representation of the contents of a message in human-readable form.
Dump(MessageDump) Returns a string representation of the contents of a message in human-readable form. Dump(MessageDump.Full) is equivalent to calling Dump().
GetBinaryAttachment Gets the binary attachment part of the message. If not present, null is returned to the user.
GetDestinationTopicSuffix A getter for the suffix of the topic string. If the received message contains a topic destination and the topic begins with the session's topic prefix, this method returns the string following the '/' delimiter that terminates the topic prefix. Returns null if not present.
GetUserData Gets the user data part of the message. Returns null if not present.
GetXmlContent Gets the XML content part of the message. Returns null if not present.
Reset Release all memory associated with this message, returning it to its original state, as if it has just been created.
SetAsReplyMessage Sets the reply attribute of the message.
SetBinaryAttachment Sets the binary attachment part of the message.
SetReplyToSuffix Appends an application-specific suffix to the default topic destination for the session. When the session is established, a unique topic destination is created for the session. This topic is generated by the appliance, and the API subscribes to a wildcard extended topic that is derived by appending './>' to the unique topic destination.
SetUserData Sets the user data part of the message.
SetXmlContent Sets the XML content part of the message.

See Also