TIBCO EMS .NET API 8.5 TIBCO EMS .NET API 8.5

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Public Attributes | Properties | List of all members
TIBCO.EMS.UFO.Message Class Reference

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

Inheritance diagram for TIBCO.EMS.UFO.Message:

## Public Member Functions
virtual object | Clone ()
| Create a copy of the message object. More...
virtual void | ClearBody ()
| Clears out the message body. Clearing a message's body does not clear its header values or property entries. 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...
void | SetBooleanProperty (string name, bool value)
| Sets a boolean property value with the specified name into the message More...
void | SetByteProperty (string name, byte value)
| Sets a byte property value with the specified name into the message More...
void | SetShortProperty (string name, short value)
| Sets a short property value with the specified name into the message More...
void | SetIntProperty (string name, int value)
| Sets a int property value with the specified name into the message More...
void | SetLongProperty (string name, long value)
| Sets a long property value with the specified name into the message More...
void | SetFloatProperty (string name, float value)
| Sets a float property value with the specified name into the message More...
void | SetDoubleProperty (string name, double value)
| Sets a double property value with the specified name into the message More...
void | SetStringProperty (string name, string value)
| Sets a string property value with the specified name into the message More...
void | SetObjectProperty (string name, object value)
| Sets an object property value with the specified name into the message More...
virtual void | Acknowledge ()
| Acknowledges all consumed messages of the session of this consumed message. More...
override string | ToString ()
| returns a string representation of the message More...

## Static Public Member Functions
static string | GetDeliveryModeName (TIBCO.EMS.MessageDeliveryMode deliveryMode)
static string | GetDeliveryModeName (int deliveryMode)

## Public Attributes
const int | DEFAULT_DELIVERY_MODE
| The message producer's default delivery mode is PERSISTENT. More...
const MessageDeliveryMode | DEFAULT_MSG_DELIVERY_MODE
| 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...

## Properties
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...
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...
TIBCO.EMS.MessageDeliveryMode | MsgDeliveryMode`[get, set]`
| Get and set the message's delivery mode as enum value of type MessageDeliveryMode More...
Destination | Destination`[get, set]`
| Gets and Sets the Destination object for this message. More...
long | Expiration`[get, set]`
| Gets and Sets the message's expiration value. More...
string | MessageID`[get, set]`
| Gets and Sets the message ID for the message. More...
string | MsgType`[get, set]`
| Gets and Sets the message's type value. More...
int | Priority`[get, set]`
| Gets and Sets the message's priority value. More...
bool | Redelivered`[get, set]`
| Gets and Sets the message's redelivered value. More...
Destination | ReplyTo`[get, set]`
| Gets and Sets the message's replyto value. More...
long | Timestamp`[get, set]`
| Gets and Sets the timestamp for the message. More...
long | DeliveryTime`[get]`
| Gets the message's delivery time value. More...
System.Collections.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.UFO.Message.Acknowledge | ( |  | ) |
| inline virtual

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

  TIBCO.EMS.IllegalStateException | if this method is called on a closed session

See Also
  TIBCO.EMS.UFO.MessageConsumer.Receive(long)

MessageConsumer.Receive

methods

See Also
  TIBCO.EMS.UFO.Session

Session

class

See Also
  TIBCO.EMS.UFO.Session.AcknowledgeMode

Session.AcknowledgeMode

See Also
  TIBCO.EMS.UFO.Session.SessionAcknowledgeMode

Session.SessionAcknowledgeMode

See Also
  TIBCO.EMS.UFO.QueueSession

QueueSession

class

virtual void TIBCO.EMS.UFO.Message.ClearBody | ( |  | ) |
| inline virtual

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.UFO.MapMessage, TIBCO.EMS.UFO.StreamMessage, TIBCO.EMS.UFO.BytesMessage, TIBCO.EMS.UFO.ObjectMessage, and TIBCO.EMS.UFO.TextMessage.

virtual void TIBCO.EMS.UFO.Message.ClearProperties | ( |  | ) |
| inline virtual

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.UFO.Message.Clone | ( |  | ) |
| inline virtual

Create a copy of the message object.

Implements ICloneable.Clone.

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

bool TIBCO.EMS.UFO.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.UFO.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.UFO.Message.GetDeliveryModeName | ( | TIBCO.EMS.MessageDeliveryMode | deliveryMode | ) |
| inline static

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.UFO.Message.GetDeliveryModeName | ( | int | deliveryMode | ) |
| inline static

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.UFO.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.UFO.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.UFO.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.UFO.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.UFO.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.

short TIBCO.EMS.UFO.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.UFO.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.

virtual bool TIBCO.EMS.UFO.Message.PropertyExists | ( | string | name | ) |
| inline virtual

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.UFO.Message.SetBooleanProperty | ( | string | name,
|  | bool | value
| ) |  |
| 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
  value | the boolean property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetByteProperty | ( | string | name,
|  | byte | value
| ) |  |
| 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
  value | the byte property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetDoubleProperty | ( | string | name,
|  | double | value
| ) |  |
| 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
  value | the double property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetFloatProperty | ( | string | name,
|  | float | value
| ) |  |
| 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
  value | the float property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetIntProperty | ( | string | name,
|  | int | value
| ) |  |
| 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
  value | the int property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetLongProperty | ( | string | name,
|  | long | value
| ) |  |
| 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
  value | the long property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetObjectProperty | ( | string | name,
|  | object | value
| ) |  |
| 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
  value | the object property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetShortProperty | ( | string | name,
|  | short | value
| ) |  |
| 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.
  value | the short property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.Message.SetStringProperty | ( | string | name,
|  | string | value
| ) |  |
| 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
  value | the string property value to set

Exceptions

  TIBCO.EMS.MessageNotWriteableException | An TIBCO.EMS.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.UFO.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.UFO.Message.DEFAULT_DELIVERY_MODE

Initial value:
=
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.UFO.Message.DEFAULT_MSG_DELIVERY_MODE

Initial value:
=
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.UFO.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.UFO.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.

## Property Documentation

string TIBCO.EMS.UFO.Message.CorrelationID
| get set

Gets and Sets the correlation ID for the message.

byte [] TIBCO.EMS.UFO.Message.CorrelationIDAsBytes
| get set

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.UFO.Message.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.

long TIBCO.EMS.UFO.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.UFO.Message.Destination
| get set

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.UFO.Message.Expiration
| get set

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

string TIBCO.EMS.UFO.Message.MessageID
| get set

Gets and Sets the message ID for the message.

TIBCO.EMS.MessageDeliveryMode TIBCO.EMS.UFO.Message.MsgDeliveryMode
| get set

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.UFO.Message.MsgType
| get set

Gets and Sets the message's type value.

int TIBCO.EMS.UFO.Message.Priority
| get set

Gets and Sets the message's priority value.

System.Collections.IEnumerator TIBCO.EMS.UFO.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.UFO.Message.Redelivered
| get set

Gets and Sets the message's redelivered value.

Destination TIBCO.EMS.UFO.Message.ReplyTo
| get set

Gets and Sets the message's replyto value.

long TIBCO.EMS.UFO.Message.Timestamp
| get set

Gets and Sets the timestamp for the message.