ocilib::Message Class Reference

AQ message. More...

`#include <ocilib.hpp>`

Inherits ocilib::HandleHolder< OCI_Msg *>.

## Public Types

enum | MessageStateValues { Ready = OCI_AMS_READY, Waiting = OCI_AMS_WAITING, Processed = OCI_AMS_PROCESSED, Expired = OCI_AMS_EXPIRED }
| Message state enumerated values. More...
typedef Enum< MessageStateValues > | MessageState
| Message state. More...

## Public Member Functions

| Message (const TypeInfo &typeInfo)
| Create a message object based on the given payload type. More...
void | Reset ()
| Reset all attributes of the message. More...
template<class T >
T | GetPayload ()
| Get the object payload of the message.
template<class T >
void | SetPayload (const T &value)
| Set the object payload of the message. More...
Date | GetEnqueueTime () const
| return the time the message was enqueued More...
int | GetAttemptCount () const
| Return the number of attempts that have been made to dequeue the message.
MessageState | GetState () const
| Return the state of the message at the time of the dequeue.
Raw | GetID () const
| Return the ID of the message. More...
int | GetExpiration () const
| Return the duration that the message is available for dequeuing. More...
void | SetExpiration (int value)
| set the duration that the message is available for dequeuing More...
int | GetEnqueueDelay () const
| Return the number of seconds that a message is delayed for dequeuing. More...
void | SetEnqueueDelay (int value)
| set the number of seconds to delay the enqueued message More...
int | GetPriority () const
| Return the priority of the message. More...
void | SetPriority (int value)
| Set the priority of the message. More...
Raw | GetOriginalID () const
| Return the original ID of the message in the last queue that generated this message. More...
void | SetOriginalID (const Raw &value)
| Set the original ID of the message in the last queue that generated this message. More...
ostring | GetCorrelation () const
| Get the correlation identifier of the message. More...
void | SetCorrelation (const ostring &value)
| Set the correlation identifier of the message. More...
ostring | GetExceptionQueue () const
| Get the Exception queue name of the message. More...
void | SetExceptionQueue (const ostring &value)
| Set the name of the queue to which the message is moved to if it cannot be processed successfully. More...
Agent | GetSender () const
| Return the original sender of the message. More...
void | SetSender (const Agent &agent)
| Set the original sender of the message. More...
void | SetConsumers (std::vector< Agent > &agents)
| Set the recipient list of a message to enqueue. More...

## Detailed Description

AQ message.

This class wraps the OCILIB object handle OCI_Msg and its related methods

Definition at line 7310 of file ocilib.hpp.

## Member Typedef Documentation

## MessageState

typedef Enum<MessageStateValues> ocilib::Message::MessageState

Message state.

Possible values are Message::MessageStateValues

Definition at line 7340 of file ocilib.hpp.

## Member Enumeration Documentation

## MessageStateValues

enum ocilib::Message::MessageStateValues

Message state enumerated values.

Enumerator
Ready | The message is ready to be processed
Waiting | The message delay has not yet completed
Processed | The message has been processed
Expired | The message has moved to exception queue

Definition at line 7321 of file ocilib.hpp.

## Constructor & Destructor Documentation

## Message()

ocilib::Message::Message | ( | const TypeInfo & | typeInfo | ) |

inline

Create a message object based on the given payload type.

Parameters

  typeInfo | - Type info object

Note
  OCILIB supports 2 type of message payload :
  - Oracle types (UDT)
  - RAW data
  Oracle Type AnyData is not supported in the current version of OCILIB
  the parameter 'typinf' indicates the type of payload :
  - For object payload, retrieve the object type information object from the given type name
  - For RAW payload, you MUST pass the object type information object from the type name "SYS.RAW" as object type name

Warning
  Newly created Message handles have NULL payloads. For Message handling Objects payloads, Get() returns a null Object until an object is assigned to the message.

Note
  When a local Message object handle is enqueued, it keeps its attributes. If it's enqueued again, another identical message is posted into the queue. To reset a message and empty all its properties, call Reset()

Definition at line 6600 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_MsgCreate(), and OCI_MsgFree().

## Member Function Documentation

## Reset()

void ocilib::Message::Reset | ( |  | ) |

inline

Reset all attributes of the message.

Warning
  Reset() clears the message payload and set it to NULL

Definition at line 6610 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeRaw(), OCI_MsgGetObject(), OCI_MsgGetRaw(), OCI_MsgReset(), OCI_MsgSetObject(), and OCI_MsgSetRaw().

## SetPayload()

template<class T >

void ocilib::Message::SetPayload | ( | const T & | value | ) |

Set the object payload of the message.

Parameters

  value | - Object payload

## GetEnqueueTime()

Date ocilib::Message::GetEnqueueTime | ( |  | ) | const

inline

return the time the message was enqueued

Note
  Only use this function for message dequeued from queues

Definition at line 6652 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgGetEnqueueTime().

## GetID()

Raw ocilib::Message::GetID | ( |  | ) | const

inline

Return the ID of the message.

Note
  The message ID is :
  - generated when the message is enqueued in the queue
  - retrieved when the message is dequeued from the queue

Definition at line 6667 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeRaw(), and OCI_MsgGetID().

## GetExpiration()

int ocilib::Message::GetExpiration | ( |  | ) | const

inline

Return the duration that the message is available for dequeuing.

Note
  see SetExpiration() for more details

Definition at line 6678 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgGetExpiration().

## SetExpiration()

void ocilib::Message::SetExpiration | ( | int | value | ) |

inline

set the duration that the message is available for dequeuing

Parameters

  value | - duration in seconds

Note
  This parameter is an offset from the delay (see SetEnqueueDelay()) While waiting for expiration, the message state is set to Message::Ready. If the message is not dequeued before it expires, it will be moved to the exception queue with the state Message::Expired.
  If parameter 'value' is set to -1 (default value), the message will not expire

Warning
  Expiration processing requires the queue monitor to be started.

Definition at line 6683 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetExpiration().

## GetEnqueueDelay()

int ocilib::Message::GetEnqueueDelay | ( |  | ) | const

inline

Return the number of seconds that a message is delayed for dequeuing.

Note
  see SetEnqueueDelay() for more details

Definition at line 6688 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgGetEnqueueDelay().

## SetEnqueueDelay()

void ocilib::Message::SetEnqueueDelay | ( | int | value | ) |

inline

set the number of seconds to delay the enqueued message

Parameters

  value | - Delay in seconds

Note
  The delay represents the number of seconds after which a message is available for dequeuing. When the message is enqueued, its state is set to Message::Waiting. When the delay expires, its state is set to Message::Ready.
  If parameter 'value' is set to zero (default value), the message will be immediately available for dequeuing

Warning
  Dequeuing by Message ID overrides the delay specification.
  Delaying processing requires the queue monitor to be started.

Definition at line 6693 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetEnqueueDelay().

## GetPriority()

int ocilib::Message::GetPriority | ( |  | ) | const

inline

Return the priority of the message.

Note
  see SetPriority() for more details

Definition at line 6698 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgGetPriority().

## SetPriority()

void ocilib::Message::SetPriority | ( | int | value | ) |

inline

Set the priority of the message.

Parameters

  value | - Message priority

Note
  - The priority can be any number, including negative numbers.
  - A smaller number indicates higher priority.
  - Default value is zero.

Definition at line 6703 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetPriority().

## GetOriginalID()

Raw ocilib::Message::GetOriginalID | ( |  | ) | const

inline

Return the original ID of the message in the last queue that generated this message.

Warning
  When a message is propagated from/to different queues, this ID is the one generated for the message in the previous queue.

Definition at line 6708 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeRaw(), and OCI_MsgGetOriginalID().

## SetOriginalID()

void ocilib::Message::SetOriginalID | ( | const Raw & | value | ) |

inline

Set the original ID of the message in the last queue that generated this message.

Parameters

  value | - Message ID

Warning
  When a message is propagated from/to different queues, this ID is the one generated for the message in the previous queue.

Definition at line 6719 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetOriginalID().

## GetCorrelation()

ostring ocilib::Message::GetCorrelation | ( |  | ) | const

inline

Get the correlation identifier of the message.

Note
  see SetCorrelation() for more details

Definition at line 6731 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeString(), and OCI_MsgGetCorrelation().

## SetCorrelation()

void ocilib::Message::SetCorrelation | ( | const ostring & | value | ) |

inline

Set the correlation identifier of the message.

Parameters

  value | - Message correlation text

Note
  see Dequeue::SetCorrelation() for more details

Definition at line 6736 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetCorrelation().

## GetExceptionQueue()

ostring ocilib::Message::GetExceptionQueue | ( |  | ) | const

inline

Get the Exception queue name of the message.

Warning
  When calling this function on a message retrieved with Dequeue::Get(), the returned value is empty if the default exception queue associated with the current queue is used (e.g. no user defined specified at enqueue time for the message)

Note
  see SetExceptionQueue() for more details

Definition at line 6741 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::MakeString(), and OCI_MsgGetExceptionQueue().

## SetExceptionQueue()

void ocilib::Message::SetExceptionQueue | ( | const ostring & | value | ) |

inline

Set the name of the queue to which the message is moved to if it cannot be processed successfully.

Parameters

  value | - Exception queue name

Warning
  From Oracle Documentation :

"Messages are moved into exception queues in two cases :

- If the number of unsuccessful dequeue attempts has exceeded the attribute 'max_retries' of given queue
- if the message has expired.

All messages in the exception queue are in the EXPIRED state.

The default is the exception queue associated with the queue table.

If the exception queue specified does not exist at the time of the move the message will be moved to the default exception queue associated with the queue table and a warning will be logged in the alert file.

This attribute must refer to a valid queue name."

Definition at line 6746 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetExceptionQueue().

## GetSender()

Agent ocilib::Message::GetSender | ( |  | ) | const

inline

Return the original sender of the message.

Returns
  Valid agent object if set at enqueue time otherwise a null agent object

Definition at line 6751 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgGetSender().

## SetSender()

void ocilib::Message::SetSender | ( | const Agent & | agent | ) |

inline

Set the original sender of the message.

Parameters

  agent | - Message sender

Definition at line 6756 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetSender().

## SetConsumers()

void ocilib::Message::SetConsumers | ( | std::vector< Agent > & | agents | ) |

inline

Set the recipient list of a message to enqueue.

Parameters

  agents | - Recipients list

Warning
  This function should only be used for queues which allow multiple consumers. The default recipients are the queue subscribers.

Definition at line 6761 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_MsgSetConsumers().