IMessage

A Message object represents a message that an application sends or receives. IMessage is a superclass for the message classes such as IMapMessage.

For a list of the JMS message header fields in a Message object, see Header fields of an XMS message. For a list of the JMS defined properties of a Message object, see JMS-defined properties of a message. For a list of the IBM defined properties of a Message object, see IBM-defined properties of a message. For a list of JMS_IBM_MQMD* properties for the Message object, see JMS_IBM_MQMD* properties

Messages are deleted by the garbage collector. When a message is deleted, this frees the resources it was using.

Parent topic: .NET interfaces


.NET properties

    Summary of .NET properties:

    .NET property Description
    JMSCorrelationID Get and set the correlation identifier of the message as a String object.
    JMSDeliveryMode Get and set the delivery mode of the message.
    JMSDestination Get and set the destination of the message.
    JMSExpiration Get and set the expiration time of the message.
    JMSMessageID Get and set the message identifier of the message as a string object encapsulating the message identifier.
    JMSPriority Get and set the priority of the message.
    JMSRedelivered Get an indication of whether the message is being redelivered, and indicate whether the message is being redelivered.
    JMSReplyTo Get and set the destination where a reply to the message is to be sent.
    JMSTimestamp Get and set the time when the message was sent.
    JMSType Get and set the type of the message.
    PropertyNames Get an enumeration of the names properties of the message.


GetJMSCorrelationID - Get and Set JMSCorrelationID

    Interface:
    String JMSCorrelationID
{
  get;
  set;
}

Get and set the correlation identifier of the message as a String object.

    Exceptions:

    • XMSException


JMSDeliveryMode - Get and Set JMSDeliveryMode

    Interface:
    DeliveryMode JMSDeliveryMode
{
  get;
  set;
}

Get and set the delivery mode of the message.

The delivery mode of the message is one of the following values:

  • DeliveryMode.Persistent
  • DeliveryMode.NonPersistent

For a newly created message that was not sent, the delivery mode is DeliveryMode.Persistent, except for a real-time connection to a broker for which the delivery mode is DeliveryMode.NonPersistent. For a message that is received, the method returns the delivery mode that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the delivery mode by setting JMSDeliveryMode.

    Exceptions:

    • XMSException


JMSDestination - Get and Set JMSDestination

    Interface:
    IDestination JMSDestination
{
  get;
  set;
}

Get and set the destination of the message.

The destination is set by the IMessageProducer.send() call when the message is sent. The value of JMSDestination is ignored. However, we can use JMSDestination to change the destination of a message that was received.

For a newly created message that was not sent, the method returns a null Destination object, unless the sending application sets a destination by setting JMSDestination. For a message that was received, the method returns a Destination object for the destination that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the destination by setting JMSDestination.

    Exceptions:

    • XMSException


JMSExpiration - Get and Set JMSExpiration

    Interface:
    Int64 JMSExpiration
{
  get;
  set;
}

Get and set the expiration time of the message.

The expiration time is set by the IMessageProducer.send() call when the message is sent. Its value is calculated by adding the time to live, as specified by the sending application, to the time when the message is sent. The expiration time is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.

For a newly created message that was not sent, the expiration time is 0 unless the sending application sets a different expiration time by setting JMSExpiration. For a message that was received, the method returns the expiration time that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the expiration time by setting JMSExpiration.

If the time to live is 0, the IMessageProducer.send() call sets the expiration time to 0 to indicate that the message does not expire.

XMS discards expired messages and does not deliver them to applications.

    Exceptions:

    • XMSException


JMSMessageID - Get and Set JMSMessageID

    Interface:
    String JMSMessageID
{
  get;
  set;
}

Get and set the message identifier of the message as a string object encapsulating the message identifier.

The message identifier is set by the IMessageProducer.send() call when the message is sent. For a message that was received, the method returns the message identifier that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the message identifier by setting JMSMessageID.

If the message has no message identifier, the method returns a null.

    Exceptions:

    • XMSException


JMSPriority - Get and Set JMSPriority

    Interface:
    Int32 JMSPriority
{
  get;
  set;
}

Get and set the priority of the message.

The priority is set by the IMessageProducer.send() call when the message is sent. The value is an integer in the range 0, the lowest priority, to 9, the highest priority.

For a newly created message that was not sent, the priority is 4 unless the sending application sets a different priority by setting JMSPriority. For a message that was received, the method returns the priority that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the priority by setting JMSPriority.

    Exceptions:

    • XMSException


JMSRedelivered - Get and Set JMSRedelivered

    Interface:
    Boolean JMSRedelivered
{
  get;
  set;
}

Get an indication of whether the message is being redelivered, and indicate whether the message is being redelivered. The indication is set by the IMessageConsumer.receive() call when the message is received.

This property has the following values:

  • True, if the message is being redelivered.
  • False, if the message is not being redelivered.

For a real-time connection to a broker, the value is always False.

An indication of redelivery set by JMSRedelivered before the message is sent is ignored by the IMessageProducer.send() call when the message is sent, and is ignored and replaced by the IMessageConsumer.receive() call when the message is received. However, we can use JMSRedelivered to change the indication for a message that was received.

    Exceptions:

    • XMSException


JMSReplyTo - Get and Set JMSReplyTo

    Interface:
    IDestination JMSReplyTo
{
  get;
  set;
}

Get and set the destination where a reply to the message is to be sent.

The value of this property is a Destination object for the destination where a reply to the message is to be sent. A null Destination object means that no reply is expected.

    Exceptions:

    • XMSException


JMSTimestamp - Get and Set JMSTimestamp

    Interface:
    Int64 JMSTimestamp
{
  get;
  set;
}

Get and set the time when the message was sent.

The time stamp is set by the IMessageProducer.send() call when the message is sent and is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.

For a newly created message that was not sent, the time stamp is 0 unless the sending application sets a different time stamp by setting JMSTimestamp. For a message that was received, the method returns the time stamp that was set by the IMessageProducer.send() call when the message was sent unless the receiving application changes the time stamp by setting JMSTimestamp.

    Exceptions:

    • XMSException

Notes:

  1. If the time stamp is undefined, the method returns 0 but throws no exception.


JMSType - Get and Set JMSType

    Interface:
    String JMSType
{
  get;
  set;
}

Get and set the type of the message.

The value of JMSType is a string encapsulating the type of the message. If data conversion is required, this value is the type after conversion.

    Exceptions:

    • XMSException


PropertyNames - Get Properties

    Interface:
    System.Collections.IEnumerator PropertyNames
{
  get;
}

Get an enumeration of the names properties of the message.

    Exceptions:

    • XMSException


Methods

    Summary of methods:

    Method Description
    Acknowledge Acknowledge this message and all previously unacknowledged messages received by the session.
    ClearBody Clear the body of the message.
    ClearProperties Clear the properties of the message.
    PropertyExists Check whether the message has a property with the specified name.


Acknowledge - Acknowledge

    Interface:
    void  Acknowledge();

Acknowledge this message and all previously unacknowledged messages received by the session.

An application can call this method if the acknowledgment mode of the session is AcknowledgeMode.ClientAcknowledge. Calls to the method are ignored if the session has any other acknowledgment mode or is transacted.

Messages that were received but not acknowledged might be redelivered.

For more information about acknowledging messages, see ../dev/xms_cmesack.htm#xms_cmesack.

    Parameters:
    None

    Returns:
    Void

    Exceptions:

    • XMSException
    • IllegalStateException


ClearBody - Clear Body

    Interface:
    void  ClearBody();

Clear the body of the message. The header fields and message properties are not cleared.

If an application clears a message body, the body remains in the same state as an empty body in a newly created message. The state of an empty body in a newly created message depends on the type of message body. For more information, see The body of an XMS message.

An application can clear a message body at any time, no matter what state the body is in. If a message body is read-only, the only way that an application can write to the body is for the application to clear the body first.

    Parameters:
    None

    Returns:
    Void

    Exceptions:

    • XMSException


ClearProperties - Clear Properties

    Interface:
    void  ClearProperties();

Clear the properties of the message. The header fields and the message body are not cleared.

If an application clears the properties of a message, the properties become readable and writable.

An application can clear the properties of a message at any time, no matter what state the properties are in. If the properties of a message are read-only, the only way that the properties can become writable is for the application to clear the properties first.

    Parameters:
    None

    Returns:
    Void

    Exceptions:

    • XMSException


PropertyExists - Check Property Exists

    Interface:
    Boolean PropertyExists(String propertyName);

Check whether the message has a property with the specified name.

    Parameters:

      propertyName (input)
      A String object encapsulating the name of the property.

    Returns:

    • True, if the message has a property with the specified name.
    • False, if the message does not have a property with the specified name.

    Exceptions:

    • XMSException


Inherited properties and methods

The following methods are inherited from the IPropertyContext interface: