TIBCO.EMS.Message Class Reference

Messages carry information among EMS client programs. More...

Inheritance diagram for TIBCO.EMS.Message:

Classes
class	EmptyEnum
	Represents an empty enumerator More...

Public Member Functions
virtual Object	Clone ()
	Create a copy of the message object. More...
virtual void	ClearProperties ()
	Clears a message's properties. More...
virtual bool	PropertyExists (string name)
	Test whether a named property has been set on a message. More...
bool	GetBooleanProperty (string name)
	Returns the value of the boolean property with the specified name. More...
byte	GetByteProperty (string name)
	Returns the value of the byte property with the specified name. More...
short	GetShortProperty (string name)
	Returns the value of the short property with the specified name. More...
int	GetIntProperty (string name)
	Returns the value of the int property with the specified name. More...
long	GetLongProperty (string name)
	Returns the value of the long property with the specified name. More...
float	GetFloatProperty (string name)
	Returns the value of the float property with the specified name. More...
double	GetDoubleProperty (string name)
	Returns the value of the double property with the specified name. More...
string	GetStringProperty (string name)
	Returns the value of the string property with the specified name. More...
Object	GetObjectProperty (string name)
	Returns the value of the object property with the specified name. More...
virtual object	GetProperty (string name, Type type)
	THIS IS FOR INTERNAL USE ONLY More...
void	SetBooleanProperty (string name, bool val)
	Sets a boolean property value with the specified name into the message More...
void	SetByteProperty (string name, byte val)
	Sets a byte property value with the specified name into the message More...
void	SetShortProperty (string name, short val)
	Sets a short property value with the specified name into the message More...
void	SetIntProperty (string name, int val)
	Sets a int property value with the specified name into the message More...
void	SetLongProperty (string name, long val)
	Sets a long property value with the specified name into the message More...
void	SetFloatProperty (string name, float val)
	Sets a float property value with the specified name into the message More...
void	SetDoubleProperty (string name, double val)
	Sets a double property value with the specified name into the message More...
void	SetStringProperty (string name, string val)
	Sets a string property value with the specified name into the message More...
void	SetObjectProperty (string name, Object val)
	Sets an object property value with the specified name into the message More...
void	SetBytesProperty (string name, byte[] val)
	FOR INTERNAL USE ONLY More...
virtual void	Acknowledge ()
	Acknowledges all consumed messages of the session of this consumed message. More...
virtual void	ClearBody ()
	Clears out the message body. Clearing a message's body does not clear its header values or property entries. More...
override string	ToString ()
	returns a string representation of the message More...

Static Public Member Functions
static string	GetDeliveryModeName (MessageDeliveryMode deliveryMode)
static string	GetDeliveryModeName (int deliveryMode)
static string	GetTimeName (long timestamp)

Public Attributes
const int	DEFAULT_DELIVERY_MODE = TIBCO.EMS.DeliveryMode.PERSISTENT
	The message producer's default delivery mode is PERSISTENT. More...
const MessageDeliveryMode	DEFAULT_MSG_DELIVERY_MODE = TIBCO.EMS.MessageDeliveryMode.Persistent
	The message producer's default delivery mode is PERSISTENT. More...
const int	DEFAULT_PRIORITY = 4
	The message producer's default priority is 4. More...
const long	DEFAULT_TIME_TO_LIVE = 0
	The message producer's default time to live is unlimited; the message never expires. More...

Static Public Attributes
static EmptyEnum	emptyEnum = new EmptyEnum()
	empty enum object for internal use More...

Properties
bool	IsCompressed [set]
	THIS IS FOR INTERNAL USE ONLY More...
string	MessageID [get, set]
	Gets and Sets the message ID for the message. More...
long	Timestamp [get, set]
	Gets and Sets the timestamp for the message. More...
string	CorrelationID [get, set]
	Gets and Sets the correlation ID for the message. More...
byte[]	CorrelationIDAsBytes [get, set]
	Gets and Sets the correlation ID as an array of bytes for the message. More...
Destination	Destination [get, set]
	Gets and Sets the Destination object for this message. More...
Destination	ReplyTo [get, set]
	Gets and Sets the message's replyto value. More...
int	DeliveryMode [get, set]
	Get and set the message's delivery mode as an integer constant as defined in the DeliveryMode class. Users are recommended to use the MessageDeliveryMode enum instead. More...
MessageDeliveryMode	MsgDeliveryMode [get, set]
	Get and set the message's delivery mode as enum value of type MessageDeliveryMode More...
bool	Redelivered [get, set]
	Gets and Sets the message's redelivered value. More...
string	MsgType [get, set]
	Gets and Sets the message's type value. More...
long	Expiration [get, set]
	Gets and Sets the message's expiration value. More...
int	Priority [get, set]
	Gets and Sets the message's priority value. More...
long	DeliveryTime [get]
	Gets the message's delivery time value. More...
IEnumerator	PropertyNames [get]
	Returns an Enumeration of all the property names. More...

Detailed Description

Messages carry information among EMS client programs.

The Message interface is the root interface of all TIBCO Enterprise Message Service .NET messages. It defines the message header and the acknowledge method used for all messages. All other message types extend this root interface.

The TIBCO Enterprise Message Service .NET Client API messages are composed of the following parts:

• Header - Headers associate a fixed set of header field names with values. Clients and providers use headers to identify and route messages. All messages support the same set of header fields.
• Properties - Each message contains a built-in facility for supporting application-defined property values. Properties associate an extensible set of property names with values. The EMS server uses properties to attach ancillary information to messages. Client applications can also use properties - for example, to customize message filtering.
• Body - The body of a message bears the information content of an application. Several types of message body organize that information in different ways.

Message Bodies

The TIBCO EMS .NET API defines five types of message body:

• Stream - A StreamMessage object's message body contains a stream of primitive values in the .NET programming language (".NET primitives"). It is filled and read sequentially.
• Map - A MapMessage object's message body contains a set of name-value pairs, where names are String objects, and values are .NET primitives. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined.
• Text - A TextMessage object's message body contains a .NET String object. This message type can be used to transport plain-text messages, and XML messages.
• Object - An ObjectMessage object's message body contains a Serializable .NET object.
• Bytes - A BytesMessage object's message body contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format. In many cases, it is possible to use one of the other body types, which are easier to use. Although the TIBCO EMS .NET API allows the use of message properties with byte messages, they are typically not used, since the inclusion of properties may affect the format.

JMS Headers as .NET Properties

These JMS headers are available as .NET properties of message objects:

• CorrelationID
• CorrelationIDAsBytes
• DeliveryMode
• MsgDeliveryMode
• Destination
• Expiration
• MessageID
• MsgType
• Priority
• Redelivered
• ReplyTo
• Timestamp
• DeliveryTime

Member Function Documentation

virtual void TIBCO.EMS.Message.Acknowledge ( )

inlinevirtual

Acknowledges all consumed messages of the session of this consumed message.

The behavior of this call depends on the acknowledgement mode of the Session.

All consumed messages support the acknowledge method for use when a client has specified that its session's consumed messages are to be explicitly acknowledged. By invoking acknowledge on a consumed message, a client acknowledges all messages consumed by the session to which the message was delivered.

Calls to acknowledge are ignored for both transacted sessions and sessions specified to use implicit acknowledgement modes.

A client may individually acknowledge each message as it is consumed, or it may choose to acknowledge messages as an application-defined group (which is done by calling acknowledge on the last received message of the group, thereby acknowledging all messages consumed by the session.)

Specifically:

• In ClientAcknowledge mode, this call acknowledges all messages that the program has consumed within the session. (This behavior complies with the JMS specification.)
• In ExplicitClientAcknowledge mode, this call acknowledges only the individual message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)
• In ExplicitClientDupsOkAcknowledge mode, this call lazily acknowledges only the individual message. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)
• In all other modes, this call has no effect. In particular, modes that specify transactions or implicit acknowledgement do not require the consuming program to call this method. However, calling it does not produce an exception. (This behavior complies with the JMS specification.)

Consumed

Three events mark a message as consumed - that is, eligible for acknowledgment using this method:

• Just before the provider raises an EMSMessageHandler event, it marks the message argument as consumed.
• Just before the provider calls an IMessageListener.OnMessage callback, it marks the message argument as consumed.
• Just before a receive call returns a message, it marks that message as consumed.

Redelivery

Messages that have been received but not acknowledged may be redelivered.

Exceptions

IllegalStateException

if this method is called on a closed session

See also

TIBCO.EMS.MessageConsumer.Receive(long)

MessageConsumer.Receive

methods

See also

TIBCO.EMS.Session

Session

class

See also

TIBCO.EMS.Session.AcknowledgeMode

Session.AcknowledgeMode

See also

TIBCO.EMS.Session.SessionAcknowledgeMode

Session.SessionAcknowledgeMode

See also

TIBCO.EMS.QueueSession

QueueSession

class

virtual void TIBCO.EMS.Message.ClearBody ( )

inlinevirtual

Clears out the message body. Clearing a message's body does not clear its header values or property entries.

If this message body was read-only, calling this method leaves the message body in the same state as an empty body in a newly created message.

Reimplemented in TIBCO.EMS.StreamMessage, TIBCO.EMS.BytesMessage, TIBCO.EMS.MapMessage, TIBCO.EMS.ObjectMessage, and TIBCO.EMS.TextMessage.

virtual void TIBCO.EMS.Message.ClearProperties ( )

inlinevirtual

Clears a message's properties.

The message's header fields and body are not cleared. The message header values and body are unchanged.

virtual Object TIBCO.EMS.Message.Clone ( )

inlinevirtual

Create a copy of the message object.

Implements ICloneable.Clone.

Reimplemented in TIBCO.EMS.StreamMessage, TIBCO.EMS.MapMessage, TIBCO.EMS.BytesMessage, TIBCO.EMS.TextMessage, and TIBCO.EMS.ObjectMessage.

bool TIBCO.EMS.Message.GetBooleanProperty ( string  name )

inline

Returns the value of the boolean property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the boolean property with this name.

Returns

The boolean property value for the specified name. When the message does not have a property set for the name, this method returns false.

byte TIBCO.EMS.Message.GetByteProperty ( string  name )

inline

Returns the value of the byte property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the byte property with this name.

Returns

The byte property value for the specified name. When the message does not have a property set for the name, this method returns false.

static string TIBCO.EMS.Message.GetDeliveryModeName ( MessageDeliveryMode  deliveryMode )

inlinestatic

Convert a delivery mode constant to a string.

This method is an extension to the JMS specification.

Parameters

deliveryMode

the DeliveryMode header property of the message object.

static string TIBCO.EMS.Message.GetDeliveryModeName ( int  deliveryMode )

inlinestatic

Convert a delivery mode constant to a string.

Programs can obtain the delivery mode of a message by accessing the DeliveryMode header property of the message object.

This method is an extension to the JMS specification.

Parameters

deliveryMode

the DeliveryMode header property of the message object.

double TIBCO.EMS.Message.GetDoubleProperty ( string  name )

inline

Returns the value of the double property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the double property with this name.

Returns

The double property value for the specified name. When the message does not have a property set for the name, this method returns false.

float TIBCO.EMS.Message.GetFloatProperty ( string  name )

inline

Returns the value of the float property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the float property with this name.

Returns

The float property value for the specified name. When the message does not have a property set for the name, this method returns false.

int TIBCO.EMS.Message.GetIntProperty ( string  name )

inline

Returns the value of the int property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the int property with this name.

Returns

The int property value for the specified name. When the message does not have a property set for the name, this method returns false.

long TIBCO.EMS.Message.GetLongProperty ( string  name )

inline

Returns the value of the long property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the long property with this name.

Returns

The long property value for the specified name. When the message does not have a property set for the name, this method returns false.

Object TIBCO.EMS.Message.GetObjectProperty ( string  name )

inline

Returns the value of the object property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the object property with this name.

Returns

The object property value for the specified name. When the message does not have a property set for the name, this method returns null.

virtual object TIBCO.EMS.Message.GetProperty ( string  name, Type  type  )

inlinevirtual

THIS IS FOR INTERNAL USE ONLY

Deprecated:

Use type-specific Get methods, e.g. GetIntProperty(), GetObjectProperty(), etc., instead.

short TIBCO.EMS.Message.GetShortProperty ( string  name )

inline

Returns the value of the short property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the short property with this name.

Returns

The short property value for the specified name. When the message does not have a property set for the name, this method returns false.

string TIBCO.EMS.Message.GetStringProperty ( string  name )

inline

Returns the value of the string property with the specified name.

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Get the string property with this name.

Returns

The string property value for the specified name. When the message does not have a property set for the name, this method returns null.

static string TIBCO.EMS.Message.GetTimeName ( long  timestamp )

inlinestatic

Time expressed in UTC

Deprecated:

Please write your own helper function to perform this task.

virtual bool TIBCO.EMS.Message.PropertyExists ( string  name )

inlinevirtual

Test whether a named property has been set on a message.

Parameters

name	the name of the property to test

Returns

true if the property has a value on the message; otherwise returns false.

void TIBCO.EMS.Message.SetBooleanProperty ( string  name, bool  val  )

inline

Sets a boolean property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the boolean property
val	the boolean property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetByteProperty ( string  name, byte  val  )

inline

Sets a byte property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the byte property
val	the byte property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetBytesProperty ( string  name, byte[]  val  )

inline

FOR INTERNAL USE ONLY

void TIBCO.EMS.Message.SetDoubleProperty ( string  name, double  val  )

inline

Sets a double property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the double property
val	the double property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetFloatProperty ( string  name, float  val  )

inline

Sets a float property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the float property
val	the float property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetIntProperty ( string  name, int  val  )

inline

Sets a int property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the int property
val	the int property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetLongProperty ( string  name, long  val  )

inline

Sets a long property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the long property
val	the long property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetObjectProperty ( string  name, Object  val  )

inline

Sets an object property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the object property
val	the object property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetShortProperty ( string  name, short  val  )

inline

Sets a short property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	Set the short property with this name.
val	the short property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

void TIBCO.EMS.Message.SetStringProperty ( string  name, string  val  )

inline

Sets a string property value with the specified name into the message

Property names must obey the JMS rules for a message selector identifier. Property names must not be null, and must not be empty strings.

Parameters

name	the name of the string property
val	the string property value to set

Exceptions

MessageNotWriteableException	An MessageNotWriteableException may be thrown if properties are read-only
ArgumentException	An ArgumentException may be thrown if the name is null or if the name is an empty string

override string TIBCO.EMS.Message.ToString ( )

inline

returns a string representation of the message

The string includes the body type, headers (name-value pairs), properties (name-value pairs), and body content.

Returns

a string representation of the message

Member Data Documentation

const int TIBCO.EMS.Message.DEFAULT_DELIVERY_MODE = TIBCO.EMS.DeliveryMode.PERSISTENT

The message producer's default delivery mode is PERSISTENT.

When neither the sending call nor the producer supplies a delivery mode, this default applies.

const MessageDeliveryMode TIBCO.EMS.Message.DEFAULT_MSG_DELIVERY_MODE = TIBCO.EMS.MessageDeliveryMode.Persistent

The message producer's default delivery mode is PERSISTENT.

When neither the sending call nor the producer supplies a delivery mode, this default applies.

const int TIBCO.EMS.Message.DEFAULT_PRIORITY = 4

The message producer's default priority is 4.

When neither the sending call nor the producer supplies a priority, this default applies.

const long TIBCO.EMS.Message.DEFAULT_TIME_TO_LIVE = 0

The message producer's default time to live is unlimited; the message never expires.

When neither the sending call nor the producer supplies a priority, this default applies. The default value, zero, indicates that messages do not expire.

EmptyEnum TIBCO.EMS.Message.emptyEnum = new EmptyEnum()

static

empty enum object for internal use

Property Documentation

string TIBCO.EMS.Message.CorrelationID

getset

Gets and Sets the correlation ID for the message.

byte [] TIBCO.EMS.Message.CorrelationIDAsBytes

getset

Gets and Sets the correlation ID as an array of bytes for the message.

The use of a byte[] value for CorrelationID is non-portable

int TIBCO.EMS.Message.DeliveryMode

getset

Get and set the message's delivery mode as an integer constant as defined in the DeliveryMode class. Users are recommended to use the MessageDeliveryMode enum instead.

long TIBCO.EMS.Message.DeliveryTime

get

Gets the message's delivery time value.

Gets the message's delivery time value.

When a message is sent, the JMSDeliveryTime header field is left unassigned. After completion of the send or publish method, it holds the delivery time of the message. This is the the difference, measured in milliseconds, between the delivery time and midnight, January 1, 1970 UTC.

A message's delivery time is the earliest time when a JMS provider may deliver the message to a consumer. The provider must not deliver messages before the delivery time has been reached.

Destination TIBCO.EMS.Message.Destination

getset

Gets and Sets the Destination object for this message.

The Destination header field contains the destination to which the message is being sent.

When a message is sent, this field is ignored. After completion of the send or publish method, the field holds the destination specified by the method.

When a message is received, its Destination value must be equivalent to the value assigned when it was sent.

long TIBCO.EMS.Message.Expiration

getset

Gets and Sets the message's expiration value.

When a message is sent, the Expiration header field is left unassigned. After completion of the send or publish method, it holds the expiration time of the message. This is the sum of the time-to-live value specified by the client and the GMT at the time of the send or publish.

If the time-to-live is specified as zero, Expiration is set to zero to indicate that the message does not expire.

When a message's expiration time is reached, the system will the message. The .NET API does not define any form of notification of message expiration.

Clients should not receive messages that have expired; however, the .NET API does not guarantee that this will not happen

bool TIBCO.EMS.Message.IsCompressed

set

THIS IS FOR INTERNAL USE ONLY

Deprecated:

Use SetBooleanProperty("JMS_TIBCO_COMPRESS",true) on the Message object instead

string TIBCO.EMS.Message.MessageID

getset

Gets and Sets the message ID for the message.

MessageDeliveryMode TIBCO.EMS.Message.MsgDeliveryMode

getset

Get and set the message's delivery mode as enum value of type MessageDeliveryMode

Valid values are:

• MessageDeliveryMode.Persistent: persistent delivery
• MessageDeliveryMode.NonPersistent: non persistent delivery
• MessageDeliveryMode.ReliableDelivery: proprietary extension and when used offers increased performance of the message producers using this mode

string TIBCO.EMS.Message.MsgType

getset

Gets and Sets the message's type value.

int TIBCO.EMS.Message.Priority

getset

Gets and Sets the message's priority value.

IEnumerator TIBCO.EMS.Message.PropertyNames

get

Returns an Enumeration of all the property names.

Note that standard header fields are not considered properties and are not returned in this enumeration

bool TIBCO.EMS.Message.Redelivered

getset

Gets and Sets the message's redelivered value.

Destination TIBCO.EMS.Message.ReplyTo

getset

Gets and Sets the message's replyto value.

long TIBCO.EMS.Message.Timestamp

getset

Gets and Sets the timestamp for the message.