WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Message

A Message object represents a message that an application sends or receives.

Inheritance hierarchy:
xms::PropertyContext
   |
   +----xms::Message

For a list of the JMS message header fields in a Message object, see Header fields in 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.

Methods

Summary of methods:
Method Description
~Message Delete the message.
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.
getHandle Get the handle that a C application would use to access the message.
getJMSCorrelationID Get the correlation identifier of the message.
getJMSDeliveryMode Get the delivery mode of the message.
getJMSDestination Get the destination of the message.
getJMSExpiration Get the expiration time of the message.
getJMSMessageID Get the message identifier of the message.
getJMSPriority Get the priority of the message.
getJMSRedelivered Get an indication of whether the message is being re-delivered.
getJMSReplyTo Get the destination where a reply to the message is to be sent.
getJMSTimestamp Get the time when the message was sent.
getJMSType Get the type of the message.
getProperties Get a list of the properties of the message.
isNull Determine whether the Message object is a null object.
propertyExists Check whether the message has a property with the specified name.
setJMSCorrelationID Set the correlation identifier of the message.
setJMSDeliveryMode Set the delivery mode of the message.
setJMSDestination Set the destination of the message.
setJMSExpiration Set the expiration time of the message.
setJMSMessageID Set the message identifier of the message.
setJMSPriority Set the priority of the message.
setJMSRedelivered Indicate whether the message is being re-delivered.
setJMSReplyTo Set the destination where a reply to the message is to be sent.
setJMSTimestamp Set the time when the message is sent.
setJMSType Set the type of the message.

~Message – Delete Message

Interface:
virtual ~Message();

Delete the message.

If an application tries to delete a message that is already deleted, the call is ignored.

Parameters:
None
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

acknowledge – Acknowledge

Interface:
xmsVOID acknowledge();

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

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

Messages that have been received but not acknowledged might be re-delivered.

For more information about acknowledging messages, see Message acknowledgement.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

clearBody – Clear Body

Interface:
xmsVOID 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 is left 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:
  • XMS_X_GENERAL_EXCEPTION

clearProperties – Clear Properties

Interface:
xmsVOID 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:
  • XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHMsg getHandle() const;

Get the handle that a C application would use to access the message.

Parameters:
None
Returns:
The handle for the message.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSCorrelationID – Get JMSCorrelationID

Interface:
String getJMSCorrelationID() const;

Get the correlation identifier of the message.

Parameters:
None
Returns:
A String object encapsulating the correlation identifier.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSDeliveryMode – Get JMSDeliveryMode

Interface:
xmsINT getJMSDeliveryMode() const;

Get the delivery mode of the message. The delivery mode is set by the MessageProducer.send() call when the message is sent.

Parameters:
None
Returns:
The delivery mode of the message, which is one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NOT_PERSISTENT

For a newly created message that has not been sent, the delivery mode is XMSC_DELIVERY_PERSISTENT, except for a real-time connection to a broker for which the delivery mode is XMSC_DELIVERY_NOT_PERSISTENT. For a message that has been received, the method returns the delivery mode that was set by the MessageProducer.send() call when the message was sent unless the receiving application changes the delivery mode by calling setJMSDeliveryMode().

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSDestination – Get JMSDestination

Interface:
Destination getJMSDestination() const;

Get the destination of the message. The destination is set by the MessageProducer.send() call when the message is sent.

Parameters:
None
Returns:
The Destination object.

For a newly created message that has not been sent, the method returns a null Destination object and throws an exception unless the sending application sets a destination by calling setJMSDestination(). For a message that has been received, the method returns a Destination object for the destination that was set by the MessageProducer.send() call when the message was sent unless the receiving application changes the destination by calling setJMSDestination().

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSExpiration – Get JMSExpiration

Interface:
xmsLONG getJMSExpiration() const;

Get the expiration time of the message.

The expiration time is set by the MessageProducer.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.

If the time to live is 0, the MessageProducer.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.

Parameters:
None
Returns:
The expiration time of the message.

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

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSMessageID – Get JMSMessageID

Interface:
String getJMSMessageID() const;

Get the message identifier of the message. The message identifier is set by the MessageProducer.send() call when the message is sent.

Parameters:
None
Returns:
A String object encapsulating the message identifier.

For a message that has been received, the method returns the message identifier that was set by the MessageProducer.send() call when the message was sent unless the receiving application changes the message identifier by calling setJMSMessageID().

Exceptions:
  • XMS_X_GENERAL_EXCEPTION
Notes:
  1. If a message has no message identifier, the method throws an exception.

getJMSPriority – Get JMSPriority

Interface:
xmsINT getJMSPriority() const;

Get the priority of the message. The priority is set by the MessageProducer.send() call when the message is sent.

Parameters:
None
Returns:
The priority of the message. The value is an integer in the range 0, the lowest priority, to 9, the highest priority.

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

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSRedelivered – Get JMSRedelivered

Interface:
xmsBOOL getJMSRedelivered() const;

Get an indication of whether the message is being re-delivered. The indication is set by the MessageConsumer.receive() call when the message is received.

Parameters:
None
Returns:
  • xmsTRUE, if the message is being re-delivered.
  • xmsFALSE, if the message is not being re-delivered.

For a real-time connection to a broker, the method always returns xmsFALSE.

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getJMSReplyTo – Get JMSReplyTo

Interface:
Destination getJMSReplyTo() const;

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

Parameters:
None
Returns:
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:
  • XMS_X_GENERAL_EXCEPTION

getJMSTimestamp – Get JMSTimestamp

Interface:
xmsLONG getJMSTimestamp() const;

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

Parameters:
None
Returns:
The time when the message was sent.

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

Exceptions:
  • XMS_X_GENERAL_EXCEPTION
Notes:
  1. If the time stamp is undefined, the method returns 0 but throws no exception.

getJMSType – Get JMSType

Interface:
String getJMSType() const;

Get the type of the message.

Parameters:
None
Returns:
A String encapsulating the type of the message. If data conversion is required, this is the type after conversion.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getProperties – Get Properties

Interface:
Iterator getProperties() const;

Get a list of the properties of the message.

The method returns an iterator that encapsulates a list of Property objects. The application can then use the iterator to access each property in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS method returns an enumeration of only the names of the properties of the message, not their values.
Parameters:
None
Returns:
The Iterator object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Message object is a null object.

Parameters:
None
Returns:
  • xmsTRUE, if the Message object is a null object.
  • xmsFALSE, if the Message object is not a null object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

propertyExists – Check Property Exists

Interface:
xmsBOOL propertyExists(const String & propertyName) const;

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

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
  • xmsTRUE, if the message has a property with the specified name.
  • xmsFALSE, if the message does not have a property with the specified name.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSCorrelationID – Set JMSCorrelationID

Interface:
xmsVOID setJMSCorrelationID(const String correlID);

Set the correlation identifier of the message.

Parameters:
correlID (input)
A String object encapsulating the correlation identifier.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSDeliveryMode – Set JMSDeliveryMode

Interface:
xmsVOID setJMSDeliveryMode(const xmsINT deliveryMode);

Set the delivery mode of the message.

A delivery mode set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the delivery mode of a message that has been received.

Parameters:
deliveryMode (input)
The delivery mode of the message, which must be one of the following values:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NOT_PERSISTENT
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSDestination – Set JMSDestination

Interface:
xmsVOID setJMSDestination(const Destination & destination);

Set the destination of the message.

A destination set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the destination of a message that has been received.

Parameters:
destination (input)
A Destination object representing the destination of the message.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSExpiration – Set JMSExpiration

Interface:
xmsVOID setJMSExpiration(const xmsLONG expiration);

Set the expiration time of the message.

An expiration time set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the expiration time of a message that has been received.

Parameters:
expiration (input)
The expiration time of the message expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSMessageID – Set JMSMessageID

Interface:
xmsVOID setJMSMessageID(const String & msgID);

Set the message identifier of the message.

A message identifier set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the message identifier of a message that has been received.

Parameters:
msgID (input)
A String object encapsulating the message identifier.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSPriority – Set JMSPriority

Interface:
xmsVOID setJMSPriority(const xmsINT priority);

Set the priority of the message.

A priority set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the priority of a message that has been received.

Parameters:
priority (input)
The priority of the message. The value can be an integer in the range 0, the lowest priority, to 9, the highest priority.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSRedelivered – Set JMSRedelivered

Interface:
xmsVOID setJMSRedelivered(const xmsBOOL redelivered);

Indicate whether the message is being re-delivered.

An indication of re-delivery set by this method before the message is sent is ignored by the MessageProducer.send() call when the message is sent, and is ignored and replaced by the MessageConsumer.receive() call when the message is received. However, you can use this method to change the indication for a message that has been received.

Parameters:
redelivered (input)
The value xmsTRUE means that the message is being re-delivered. The value xmsFALSE means that the message is not being re-delivered.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSReplyTo – Set JMSReplyTo

Interface:
xmsVOID setJMSReplyTo(const Destination & destination);

Set the destination where a reply to the message is to be sent.

Parameters:
destination (input)
A Destination object representing the destination where a reply to the message is to be sent. A null Destination object means that no reply is expected.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSTimestamp – Set JMSTimestamp

Interface:
xmsVOID setJMSTimestamp(const xmsLONG timeStamp);

Set the time when the message is sent.

A time stamp set by this method before the message is sent is ignored and replaced by the MessageProducer.send() call when the message is sent. However, you can use this method to change the time stamp of a message that has been received.

Parameters:
timeStamp (input)
The time when the message is sent expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

setJMSType – Set JMSType

Interface:
xmsVOID setJMSType(const String & type);

Set the type of the message.

Parameters:
type (input)
A String object encapsulating the type of the message.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.