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

#include <types.hpp>

Inherits ocilib::core::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 core::Enum< DequeueModeValues >	DequeueMode
	Dequeue mode.

typedef core::Enum< DequeueVisibilityValues >	DequeueVisibility
	Message visibility after begin dequeued.

typedef core::Enum< NavigationModeValues >	NavigationMode
	Navigation Mode.

Public Member Functions
	Dequeue (const TypeInfo &typeInfo, const ostring &queueName)
	Parametrized constructor.

Message	Get ()
	Dequeue messages from the given queue.

Agent	Listen (int timeout)
	Listen for messages that match any recipient of the associated Agent list.

ostring	GetConsumer () const
	Get the current consumer name associated with the dequeuing process.

void	SetConsumer (const ostring &value)
	Set the current consumer name to retrieve message for.

ostring	GetCorrelation () const
	Get the correlation identifier of the message to be dequeued.

void	SetCorrelation (const ostring &value)
	set the correlation identifier of the message to be dequeued

Raw	GetRelativeMsgID () const
	Get the message identifier of the message to be dequeued.

void	SetRelativeMsgID (const Raw &value)
	Set the message identifier of the message to be dequeued.

DequeueVisibility	GetVisibility () const
	Get the dequeuing/locking behavior.

void	SetVisibility (DequeueVisibility value)
	Set whether the new message is dequeued as part of the current transaction.

DequeueMode	GetMode () const
	Get the dequeuing/locking behavior.

void	SetMode (DequeueMode value)
	Set the dequeuing/locking behavior.

NavigationMode	GetNavigation () const
	Return the navigation position of messages to retrieve from the queue.

void	SetNavigation (NavigationMode value)
	Set the position of messages to be retrieved.

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

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

void	SetAgents (std::vector< Agent > &agents)
	Set the Agent list to listen to message for.

void	Subscribe (unsigned int port, unsigned int timeout, NotifyAQHandlerProc handler)
	Subscribe for asynchronous messages notifications.

void	Unsubscribe ()
	Unsubscribe for asynchronous messages notifications.

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 7934 of file types.hpp.

Member Typedef Documentation

◆ NotifyAQHandlerProc

ocilib::Dequeue::NotifyAQHandlerProc

User callback for dequeue event notifications.

Definition at line 7947 of file types.hpp.

◆ DequeueMode

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

Dequeue mode.

Possible values are Dequeue::DequeueModeValues

Definition at line 7973 of file types.hpp.

◆ DequeueVisibility

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

Message visibility after begin dequeued.

Possible values are Dequeue::DequeueVisibilityValues

Definition at line 7995 of file types.hpp.

◆ NavigationMode

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

Navigation Mode.

Possible values are Dequeue::NavigationModeValues

Definition at line 8020 of file types.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 7954 of file types.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 7980 of file types.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 8002 of file types.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 32 of file Dequeue.hpp.

References ocilib::core::Check(), ocilib::TypeInfo::GetConnection(), and OCI_DequeueCreate().

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 48 of file Dequeue.hpp.

References ocilib::core::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 53 of file Dequeue.hpp.

References ocilib::core::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 58 of file Dequeue.hpp.

References ocilib::core::Check(), ocilib::core::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 63 of file Dequeue.hpp.

References ocilib::core::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 68 of file Dequeue.hpp.

References ocilib::core::Check(), ocilib::core::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 73 of file Dequeue.hpp.

References ocilib::core::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 78 of file Dequeue.hpp.

References ocilib::core::Check(), ocilib::core::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 89 of file Dequeue.hpp.

References ocilib::core::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 96 of file Dequeue.hpp.

References ocilib::core::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 101 of file Dequeue.hpp.

References ocilib::core::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 106 of file Dequeue.hpp.

References ocilib::core::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 111 of file Dequeue.hpp.

References ocilib::core::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 116 of file Dequeue.hpp.

References ocilib::core::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 121 of file Dequeue.hpp.

References ocilib::core::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 126 of file Dequeue.hpp.

References ocilib::core::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 131 of file Dequeue.hpp.

References ocilib::core::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 136 of file Dequeue.hpp.

References ocilib::core::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 151 of file Dequeue.hpp.

References ocilib::core::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 158 of file Dequeue.hpp.

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ NotifyAQHandlerProc

◆ DequeueMode

◆ DequeueVisibility

◆ NavigationMode

Member Enumeration Documentation

◆ DequeueModeValues

◆ DequeueVisibilityValues

◆ NavigationModeValues

Constructor & Destructor Documentation

◆ Dequeue()

Member Function Documentation

◆ Get()

◆ Listen()

◆ GetConsumer()

◆ SetConsumer()

◆ GetCorrelation()

◆ SetCorrelation()

◆ GetRelativeMsgID()

◆ SetRelativeMsgID()

◆ GetVisibility()

◆ SetVisibility()

◆ GetMode()

◆ SetMode()

◆ GetNavigation()

◆ SetNavigation()

◆ GetWaitTime()

◆ SetWaitTime()

◆ SetAgents()

◆ Subscribe()

◆ Unsubscribe()