Skip Headers

Oracle® C++ Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10778-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Message Class

A message is the unit that is enqueued dequeued. A Message object holds both its content, or payload, and its properties. This class provides methods to get and set message properties.

Table 10-22 Constants of the Message Class

Constant Description
MSG_WAITING
The message delay time has not been reached.
MSG_READY
The message is ready to be processed.
MSG_PROCESSED
The message has been processed, and is being and is retained.
MSG_EXPIRED
The message has been moved to the exception queue.

Table 10-23 Summary of Message Methods

Method Summary
Message()
Message class constructor.
getAnyData()
Retrieves AnyData payload of the message.
getAttemptsToDequeue()
Retrieves the number of attempts made to degueue the message.
getBytes()
Retrieves Bytes payload of the message.
getCorrelationId()
Retrieves the identification string.
getDelay()
Retrieves delay with which message was enqueued.
getExceptionQueueName()
Retrieves name of queue to which Message is moved when it cannot be processed.
getExpiration()
Retrieves the expiration of the message.
getMessageEnqueuedTime()
Retrieves time at which message was enqueued.
getMessageState()
Retrieves state of the message at time of enqueuing.
getObject()
Retrieves object payload of the message.
getPriority()
Retrieves the priority of the message.
getSenderId()
Retrieves the agent who send the Message.
isNull()
Tests whether the Message object is NULL.
setAnyData()
Specifies AnyData payload of the message.
setBytes()
Specifies Bytes payload of the message.
setCorrelationId()
Specifies the identification string.
setDelay()
Specifies the number of seconds to delay the enqueued Message.
setExceptionQueueName()
Specifies the name of the queue to which the Message object will be moved if it cannot be precessed.
setExpiration()
Specifies the duration of time that Message can be dequeued before it expires.
setNull()
Sets the Message object to NULL.
setObject()
Specifies object payload of the message.
setPreviousQueueId()
Specifies id of last queue that generated the Message.
setPriority()
Specifies priority of the Message object.
setRecipientList()
Specifies the list of agents for whom the message is intended.
setSenderId()
Specifies the sender of the Message.


Message()

Message class constructor.


Syntax
Message(
   Environment *env);
Parameter Description
env
The environment of the Message.


getAnyData()

Retrieve the AnyData payload of the Message.


Syntax
AnyData getAnyData() const;


getAttemptsToDequeue()

Retrieves the number of attempts made to degueue the message. This property cannot be retrieved while enqueuing.


Syntax
int getAttemptsToDequeue();


getBytes()

Retrieve Bytes payload of the Message.


Syntax
Bytes getBytes() const;


getCorrelationId()

Retrieves the identification string.


Syntax
string getCorrelationId();


getDelay()

Retrieves the delay (in seconds) with which the Message was enqueued.


Syntax
int getDelay();


getExceptionQueueName()

Retrieves the name of the queue to which the Message is moved, in cases when the Message cannot be processed successfully.


Syntax
string getExceptionQueueName();


getExpiration()

Retrieves the expiration time of the Message (in seconds). This is the duration for which the message is available for dequeuing.


Syntax
int getExpiration();


getMessageEnqueuedTime()

Retrieves the time at which the message was enqueued, in Date format. This value is determined by the system, and cannot be set by the user.


Syntax
Date getMessageEnqueuedTime() const;


getMessageState()

Retrieves the state of the message at the time of enqueuing. This parameter cannot be set an enqueuing time. The possible states are defined as constants of the Message class in Table 10-22: MSG_WAITING, MSG_READY, MSG_PROCESSED and MSG_EXPIRED.


Syntax
MessageState getMessageState();


getObject()

Retrieve object payload of the Message.


Syntax
PObject* getObject() const;


getPreviousQueueId()

Retrieves id of the message in the last queue that generated the message.


Syntax
Bytes getPreviousQueueId();


getPriority()

Retrieves the priority of the Message.


Syntax
int getPriority();


getSenderId()

Retrieves the agent who send the Message.


Syntax
Agent getSenderId();


getType()

Retrieve the type and schema of the data in the Message.


Syntax
void getType(
   string& schema,
   string& type);
Parameter Description
schema
Schema of the data.
type
Type of the.data.


isNull()

Tests whether the Message object is NULL. If the Message object is NULL, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isNull();


setAnyData()

Specifies AnyData payload of the Message.


Syntax
void setAnyData(
   const AnyData& anydata);
Parameter Description
anydata
Data content of the Message.


setBytes()

Specifies Bytes payload of the Message.


Syntax
void setBytes(
   const Bytes& bytes);
Parameter Description
bytes
Data content of the Message.


setCorrelationId()

Specifies the identification string. This parameter is set at enqueuing time by the Producer. Messages can be dequeued with this id. The id can contain wildcard characters.


Syntax
void setCorrelationId(
   const string& id);
Parameter Description
id
The id; upper limit of 128 bytes.


setDelay()

Specifies the time (in seconds) to delay the enqueued Message. After the delay ends, the Message is available for dequeuing.


Note:

Dequeuing by msgid overrides the delay specification. A Message enqueued with delay will be in the WAITING state. Delay is set by the producer of the Message.


Syntax
void setDelay(
   int delay);
Parameter Description
delay
The delay.


setExceptionQueueName()

Specify the name of the queue to which the Message object will be moved if it cannot be processed successfully. The queue name must be valid.


Note:

  • If the exception queue does not exist at the time of the move, the Message will be moved to the default exception queue associated with the queue table; a warning will be logged in the alert file.

  • If the default exception queue is used, the parameter will return a NULL value at enqueuing time; the attribute must refer to a valid queue name.



Syntax
void setExceptionQueueName(
   const string& name);
Parameter Description
name
The name of the exception queue.


setExpiration()

Specify the duration time (in seconds) that the Message object is available for dequeuing. A Message expires after the this time.


Syntax
void setExpiration(
   int expiration);
Parameter Description
expiration
The duration of expiration.


setNull()

Sets the Message object to NULL. Before the Connection is destroyed by the terminateConnection() call of the Environment Class, all Message objects need to be set to NULL.


Syntax
void setNull();

setObject()

Specifies object payload of the Message.


Syntax
void setObject(
   const PObject& pobj);
Parameter Description
pobj
Content of the data


setPreviousQueueId()

Specify the id of the last queue that generated the Message object.


Syntax
void setPreviousQueueId(
   Bytes& id);
Parameter Description
id
The id of the queue.


setPriority()

Specifies the priority of the Message object. This property is set during enqueuing time, and can be negative. Default is 0.


Syntax
void setPriority(
   int priority);
Parameter Description
priority
The priority of the Message.


setRecipientList()

Specifies the list of Agents for whom the Message is intended. These recipients are not identical to subscribers of the queue. The property is set during enqueuing. All Agents in the list must be valid. The recipient list will override the default subscriber list.


Syntax
void setRecipientList(
   vector<Agent>& agentList);
Parameter Description
agentList
The list of Agents.


setSenderId()

Specifies the sender of the Message.


Syntax
void setSenderId(
   const Agent& id);
Parameter Description
id
Sender id.