ocilib::Dequeue Class Reference

Dequeue object for dequeuing messages into an Oracle Queue. More...

`#include <ocilib.hpp>`

Inherits ocilib::HandleHolder< OCI_Dequeue *>.

## Public Types

enum | DequeueModeValues { Browse = OCI_ADM_BROWSE, Locked = OCI_ADM_LOCKED, Remove = OCI_ADM_REMOVE, Confirm = OCI_ADM_REMOVE_NODATA }
| Dequeue mode enumerated values. More...
enum | DequeueVisibilityValues { Immediate = OCI_AMV_IMMEDIATE, OnCommit = OCI_AMV_ON_COMMIT }
| Message visibility enumerated values. More...
enum | NavigationModeValues { FirstMessage = OCI_ADN_FIRST_MSG, NextMessage = OCI_ADN_NEXT_MSG, NextTransaction = OCI_ADN_NEXT_TRANSACTION }
| Navigation Mode enumerated values. More...
typedef void(* | NotifyAQHandlerProc) (Dequeue &dequeue)
| User callback for dequeue event notifications.
typedef Enum< DequeueModeValues > | DequeueMode
| Dequeue mode. More...
typedef Enum< DequeueVisibilityValues > | DequeueVisibility
| Message visibility after begin dequeued. More...
typedef Enum< NavigationModeValues > | NavigationMode
| Navigation Mode. More...

## Public Member Functions

| Dequeue (const TypeInfo &typeInfo, const ostring &queueName)
| Parametrized constructor. More...
Message | Get ()
| Dequeue messages from the given queue. More...
Agent | Listen (int timeout)
| Listen for messages that match any recipient of the associated Agent list. More...
ostring | GetConsumer () const
| Get the current consumer name associated with the dequeuing process. More...
void | SetConsumer (const ostring &value)
| Set the current consumer name to retrieve message for. More...
ostring | GetCorrelation () const
| Get the correlation identifier of the message to be dequeued. More...
void | SetCorrelation (const ostring &value)
| set the correlation identifier of the message to be dequeued More...
Raw | GetRelativeMsgID () const
| Get the message identifier of the message to be dequeued. More...
void | SetRelativeMsgID (const Raw &value)
| Set the message identifier of the message to be dequeued. More...
DequeueVisibility | GetVisibility () const
| Get the dequeuing/locking behavior. More...
void | SetVisibility (DequeueVisibility value)
| Set whether the new message is dequeued as part of the current transaction. More...
DequeueMode | GetMode () const
| Get the dequeuing/locking behavior. More...
void | SetMode (DequeueMode value)
| Set the dequeuing/locking behavior. More...
NavigationMode | GetNavigation () const
| Return the navigation position of messages to retrieve from the queue. More...
void | SetNavigation (NavigationMode value)
| Set the position of messages to be retrieved. More...
int | GetWaitTime () const
| Return the time that Get() waits for messages if no messages are currently available. More...
void | SetWaitTime (int value)
| Set the time that Get() waits for messages if no messages are currently available. More...
void | SetAgents (std::vector< Agent > &agents)
| Set the Agent list to listen to message for. More...
void | Subscribe (unsigned int port, unsigned int timeout, NotifyAQHandlerProc handler)
| Subscribe for asynchronous messages notifications. More...
void | Unsubscribe ()
| Unsubscribe for asynchronous messages notifications. More...

## Detailed Description

Dequeue object for dequeuing messages into an Oracle Queue.

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

Definition at line 7826 of file ocilib.hpp.

## Member Typedef Documentation

## DequeueMode

typedef Enum<DequeueModeValues> ocilib::Dequeue::DequeueMode

Dequeue mode.

Possible values are Dequeue::DequeueModeValues

Definition at line 7865 of file ocilib.hpp.

## DequeueVisibility

typedef Enum<DequeueVisibilityValues> ocilib::Dequeue::DequeueVisibility

Message visibility after begin dequeued.

Possible values are Dequeue::DequeueVisibilityValues

Definition at line 7887 of file ocilib.hpp.

## NavigationMode

typedef Enum<NavigationModeValues> ocilib::Dequeue::NavigationMode

Navigation Mode.

Possible values are Dequeue::NavigationModeValues

Definition at line 7912 of file ocilib.hpp.

## Member Enumeration Documentation

## DequeueModeValues

enum ocilib::Dequeue::DequeueModeValues

Dequeue mode enumerated values.

Enumerator
Browse | Read message without acquiring a lock
Locked | Read and obtain write lock on message
Remove | Read the message and delete it
Confirm | Confirm receipt of the message, but do not deliver the actual message content

Definition at line 7846 of file ocilib.hpp.

## DequeueVisibilityValues

enum ocilib::Dequeue::DequeueVisibilityValues

Message visibility enumerated values.

Enumerator
Immediate | Dequeue is an independent transaction
OnCommit | Dequeue is part of current transaction

Definition at line 7872 of file ocilib.hpp.

## NavigationModeValues

enum ocilib::Dequeue::NavigationModeValues

Navigation Mode enumerated values.

Enumerator
FirstMessage | Retrieves the first message which is available
NextMessage | Retrieves the next message which is available
NextTransaction | Skips the remainder of the current transaction group (if any) and retrieves the first message of the next transaction group.

Definition at line 7894 of file ocilib.hpp.

## Constructor & Destructor Documentation

## Dequeue()

ocilib::Dequeue::Dequeue | ( | const TypeInfo & | typeInfo,
|  | const ostring & | queueName
| ) |  |

inline

Parametrized constructor.

Parameters

  typeInfo | - Payload type info
  queueName | - Queue name

Definition at line 6837 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_DequeueCreate(), and OCI_DequeueFree().

## Member Function Documentation

## Get()

Message ocilib::Dequeue::Get | ( |  | ) |

inline

Dequeue messages from the given queue.

Warning
  When dequeuing from a multiple consumer queue, you need to set the navigation mode to NavigationMode::FirstMessage using SetNavigation()

Returns
  A valid Message handle on success otherwise a null Message on timeout

Definition at line 6847 of file ocilib_impl.hpp.

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

## Listen()

Agent ocilib::Dequeue::Listen | ( | int | timeout | ) |

inline

Listen for messages that match any recipient of the associated Agent list.

Parameters

  timeout | - Timeout in second

Note
  If an Agent handle is returned, messages are available for this agent. In order to retrieve its messages :
  - call SetConsumer() with the name of agent using Agent::GetName()
  - call Get() to dequeue it's pending messages

Returns
  An Agent handle for who messages are available on success otherwise an null agent object

Definition at line 6852 of file ocilib_impl.hpp.

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

## GetConsumer()

ostring ocilib::Dequeue::GetConsumer | ( |  | ) | const

inline

Get the current consumer name associated with the dequeuing process.

Note
  see SetConsumer() for more details

Definition at line 6857 of file ocilib_impl.hpp.

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

## SetConsumer()

void ocilib::Dequeue::SetConsumer | ( | const ostring & | value | ) |

inline

Set the current consumer name to retrieve message for.

Parameters

  value | - consumer name

Warning
  If a queue is not set up for multiple consumers, SetConsumer() should not be called or called with an empty value

Definition at line 6862 of file ocilib_impl.hpp.

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

## GetCorrelation()

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

inline

Get the correlation identifier of the message to be dequeued.

Note
  see SetCorrelation() for more details

Definition at line 6867 of file ocilib_impl.hpp.

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

## SetCorrelation()

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

inline

set the correlation identifier of the message to be dequeued

Parameters

  value | - correlation identifier

Note
  Special pattern matching characters, such as "%" or "_" can be used. If more than one message satisfies the pattern, the order of dequeuing is undetermined.

Definition at line 6872 of file ocilib_impl.hpp.

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

## GetRelativeMsgID()

Raw ocilib::Dequeue::GetRelativeMsgID | ( |  | ) | const

inline

Get the message identifier of the message to be dequeued.

Note
  see SetRelativeMsgID() for more details

Definition at line 6877 of file ocilib_impl.hpp.

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

## SetRelativeMsgID()

void ocilib::Dequeue::SetRelativeMsgID | ( | const Raw & | value | ) |

inline

Set the message identifier of the message to be dequeued.

Parameters

  value | - message identifier

Definition at line 6888 of file ocilib_impl.hpp.

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

## GetVisibility()

Dequeue::DequeueVisibility ocilib::Dequeue::GetVisibility | ( |  | ) | const

inline

Get the dequeuing/locking behavior.

Note
  see SetVisibility() for more details

Definition at line 6900 of file ocilib_impl.hpp.

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

## SetVisibility()

void ocilib::Dequeue::SetVisibility | ( | DequeueVisibility | value | ) |

inline

Set whether the new message is dequeued as part of the current transaction.

Parameters

  value | - dequeuing mode

Warning
  The visibility parameter is ignored when using the dequeuing mode is Dequeue::Browse

Note
  Default value is Dequeue::OnCommit

Definition at line 6905 of file ocilib_impl.hpp.

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

## GetMode()

Dequeue::DequeueMode ocilib::Dequeue::GetMode | ( |  | ) | const

inline

Get the dequeuing/locking behavior.

Note
  see SetMode() for more details

Definition at line 6910 of file ocilib_impl.hpp.

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

## SetMode()

void ocilib::Dequeue::SetMode | ( | DequeueMode | value | ) |

inline

Set the dequeuing/locking behavior.

Parameters

  value | - dequeuing mode

Note
  Default value is Dequeue::Remove

Definition at line 6915 of file ocilib_impl.hpp.

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

## GetNavigation()

Dequeue::NavigationMode ocilib::Dequeue::GetNavigation | ( |  | ) | const

inline

Return the navigation position of messages to retrieve from the queue.

Note
  see SetNavigation() for more details

Definition at line 6920 of file ocilib_impl.hpp.

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

## SetNavigation()

void ocilib::Dequeue::SetNavigation | ( | NavigationMode | value | ) |

inline

Set the position of messages to be retrieved.

Parameters

  value | - navigation position

Note
  The dequeuing uses the following sequence :
  - find messages using the navigation position
  - apply search criteria (message correlation)
  - get message
  Default value is Dequeue::NextMessage

Warning
  Dequeue::NextTransaction can only be used if message grouping is enabled for the given queue.

Definition at line 6925 of file ocilib_impl.hpp.

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

## GetWaitTime()

int ocilib::Dequeue::GetWaitTime | ( |  | ) | const

inline

Return the time that Get() waits for messages if no messages are currently available.

Note
  see SetWaitTime() for more details

Definition at line 6930 of file ocilib_impl.hpp.

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

## SetWaitTime()

void ocilib::Dequeue::SetWaitTime | ( | int | value | ) |

inline

Set the time that Get() waits for messages if no messages are currently available.

Parameters

  value | - timeout in seconds

Note
  - Any positive values in seconds are valid.
  - The value 0 is accepted and means Get() does not wait for messages and returns immediately if no messages are available
  - The value -1 is accepted and means Get() waits for ever (until a message is available in the queue)
  Default value is -1 (wait for ever)

Definition at line 6935 of file ocilib_impl.hpp.

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

## SetAgents()

void ocilib::Dequeue::SetAgents | ( | std::vector< Agent > & | agents | ) |

inline

Set the Agent list to listen to message for.

Parameters

  agents | - vector of agents

Definition at line 6940 of file ocilib_impl.hpp.

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

## Subscribe()

void ocilib::Dequeue::Subscribe | ( | unsigned int | port,
|  | unsigned int | timeout,
|  | NotifyAQHandlerProc | handler
| ) |  |

inline

Subscribe for asynchronous messages notifications.

Parameters

  port | - Port to use for notifications
  timeout | - notification timeout
  handler | - User handler callback fired when messages are ready to be dequeued

Note
  Environment::Events flag must be passed to Environment::Initialize() to be able to use asynchronous messages notifications
  Requires Oracle Client 10gR2 or above

Definition at line 6955 of file ocilib_impl.hpp.

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

## Unsubscribe()

void ocilib::Dequeue::Unsubscribe | ( |  | ) |

inline

Unsubscribe for asynchronous messages notifications.

Note
  Requires Oracle Client 10gR2 or above

Definition at line 6962 of file ocilib_impl.hpp.

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