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 dequeueing 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 dequeueing/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 dequeueing/locking behavior. More...

void	SetMode (DequeueMode value)
	Set the dequeueing/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 7052 of file ocilib.hpp.

Member Typedef Documentation

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

Dequeue mode.

Possible values are Dequeue::DequeueModeValues

Definition at line 7091 of file ocilib.hpp.

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

Message visibility after begin dequeued.

Possible values are Dequeue::DequeueVisibilityValues

Definition at line 7113 of file ocilib.hpp.

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

Navigation Mode.

Possible values are Dequeue::NavigationModeValues

Definition at line 7138 of file ocilib.hpp.

Member Enumeration Documentation

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 7072 of file ocilib.hpp.

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 7098 of file ocilib.hpp.

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 transactiong group.

Definition at line 7120 of file ocilib.hpp.

Constructor & Destructor Documentation

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

inline

Parametrized constructor.

Parameters

typeInfo	- Payload type info
queueName	- Queue name

Definition at line 5698 of file ocilib_impl.hpp.

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

Member Function Documentation

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 5708 of file ocilib_impl.hpp.

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

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 messsages :

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 5713 of file ocilib_impl.hpp.

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

ostring ocilib::Dequeue::GetConsumer ( ) const

inline

Get the current consumer name associated with the dequeueing process.

Note: see SetConsumer() for more details

Definition at line 5718 of file ocilib_impl.hpp.

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

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 5723 of file ocilib_impl.hpp.

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

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 5728 of file ocilib_impl.hpp.

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

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 5733 of file ocilib_impl.hpp.

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

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 5738 of file ocilib_impl.hpp.

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

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

inline

Set the message identifier of the message to be dequeued.

Parameters

value - message identitier

Definition at line 5749 of file ocilib_impl.hpp.

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

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

inline

Get the dequeueing/locking behavior.

Note: see SetVisibility() for more details

Definition at line 5754 of file ocilib_impl.hpp.

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

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

inline

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

Parameters

value - dequeueing mode

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

Note: Default value is Dequeue::OnCommit

Definition at line 5759 of file ocilib_impl.hpp.

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

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

inline

Get the dequeueing/locking behavior.

Note: see SetMode() for more details

Definition at line 5764 of file ocilib_impl.hpp.

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

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

inline

Set the dequeueing/locking behavior.

Parameters

value - dequeueing mode

Note: Default value is Dequeue::Remove

Definition at line 5769 of file ocilib_impl.hpp.

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

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 5774 of file ocilib_impl.hpp.

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

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 criterias (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 5779 of file ocilib_impl.hpp.

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

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 5784 of file ocilib_impl.hpp.

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

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 5789 of file ocilib_impl.hpp.

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

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 5794 of file ocilib_impl.hpp.

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

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 5809 of file ocilib_impl.hpp.

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

void ocilib::Dequeue::Unsubscribe ( )

inline

Unsubscribe for asynchronous messages notifications.

Note: Requires Oracle Client 10gR2 or above

Definition at line 5816 of file ocilib_impl.hpp.

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation