qpid::client::SubscriptionManager Class Reference

A class to help create and manage subscriptions. More...

#include <qpid/client/SubscriptionManager.h>

List of all members.

Public Types
typedef boost::function0< void >	Functor
	Type to represent a runnable as a Functor.
Public Member Functions
	SubscriptionManager (const Session &session)
	Create a new SubscriptionManager associated with a session.
	SubscriptionManager (const SubscriptionManager &)
	~SubscriptionManager ()
SubscriptionManager &	operator= (const SubscriptionManager &)
Subscription	subscribe (MessageListener &listener, const std::string &queue, const SubscriptionSettings &settings, const std::string &name=std::string())
	Subscribe a MessagesListener to receive messages from queue.
Subscription	subscribe (LocalQueue &localQueue, const std::string &queue, const SubscriptionSettings &settings, const std::string &name=std::string())
	Subscribe a LocalQueue to receive messages from queue.
Subscription	subscribe (MessageListener &listener, const std::string &queue, const std::string &name=std::string())
	Subscribe a MessagesListener to receive messages from queue.
Subscription	subscribe (LocalQueue &localQueue, const std::string &queue, const std::string &name=std::string())
	Subscribe a LocalQueue to receive messages from queue.
bool	get (Message &result, const std::string &queue, sys::Duration timeout=0)
	Get a single message from a queue.
Message	get (const std::string &queue, sys::Duration timeout=sys::TIME_INFINITE)
	Get a single message from a queue.
Subscription	getSubscription (const std::string &name) const
	Get a subscription by name.
void	cancel (const std::string &name)
	Cancel a subscription.
void	run ()
	Deliver messages in the current thread until stop() is called.
void	start ()
	Start a new thread to deliver messages.
void	wait ()
	Wait for the thread started by a call to start() to complete.
void	setAutoStop (bool set=true)
	If set true, run() will stop when all subscriptions are cancelled.
void	stop ()
	Stop delivery.
void	setFlowControl (const std::string &name, const FlowControl &flow)
	Set the flow control for a subscription.
void	setFlowControl (const std::string &name, uint32_t messages, uint32_t bytes, bool window=true)
	Set the flow control for a subscription.
void	setDefaultSettings (const SubscriptionSettings &s)
	Set the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.
const SubscriptionSettings &	getDefaultSettings () const
	Get the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.
SubscriptionSettings &	getDefaultSettings ()
	Get the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.
void	setFlowControl (uint32_t messages, uint32_t bytes, bool window=true)
	Set the default flow control settings for subscribe() calls that don't include a SubscriptionSettings parameter.
void	setAcceptMode (AcceptMode mode)
	Set the default accept-mode for subscribe() calls that don't include a SubscriptionSettings parameter.
void	setAcquireMode (AcquireMode mode)
	Set the default acquire-mode subscribe()s that don't specify SubscriptionSettings.
void	registerFailoverHandler (boost::function< void()> fh)
Session	getSession () const
	SubscriptionManager (SubscriptionManagerImpl *)
Functor	functor ()
	Create a functor object that will call this->run().
QPID_CLIENT_INLINE_EXTERN bool	isValid () const
QPID_CLIENT_INLINE_EXTERN bool	isNull () const
QPID_CLIENT_INLINE_EXTERN	operator bool () const
	Conversion to bool supports idiom if (handle) { handle->...
QPID_CLIENT_INLINE_EXTERN bool	operator! () const
	Operator ! supports idiom if (!handle) { do_if_handle_is_null(); }.
void	swap (Handle< T > &h)
Static Public Attributes
static const uint32_t	UNLIMITED = 0xFFFFFFFF
Protected Attributes
Impl *	impl

---

Detailed Description

A class to help create and manage subscriptions.

Set up your subscriptions, then call run() to have messages delivered.

Subscribing and canceling subscriptions

• subscribe()

   SubscriptionManager subscriptions(session);
   Listener listener(subscriptions);
   subscriptions.subscribe(listener, myQueue);

   SubscriptionManager subscriptions(session);
   LocalQueue local_queue;
   subscriptions.subscribe(local_queue, string("message_queue"));

• cancel()

  subscriptions.cancel();

Waiting for messages (and returning)

• run()

   // Give up control to receive messages
   subscriptions.run();

• stop()

  .// Use this code in a listener to return from run()
   subscriptions.stop();

• setAutoStop()

  .// Return from subscriptions.run() when last subscription is cancelled
  .subscriptions.setAutoStop(true);
  .subscriptons.run();
   

• Ending a subscription in a listener

   void Listener::received(Message& message) {

    if (message.getData() == "That's all, folks!") {
         subscriptions.cancel(message.getDestination());
     }
   }
   

---

Member Typedef Documentation

typedef boost::function0<void> qpid::sys::Runnable::Functor [inherited]

Type to represent a runnable as a Functor.

Definition at line 37 of file Runnable.h.

---

Constructor & Destructor Documentation

qpid::client::SubscriptionManager::SubscriptionManager

(

const Session &

session

)

Create a new SubscriptionManager associated with a session.

qpid::client::SubscriptionManager::SubscriptionManager

(

const SubscriptionManager &

)

qpid::client::SubscriptionManager::~SubscriptionManager

(

)

qpid::client::SubscriptionManager::SubscriptionManager

(

SubscriptionManagerImpl *

)

---

Member Function Documentation

void qpid::client::SubscriptionManager::cancel

(

const std::string &

name

)

Cancel a subscription.

See also: Subscription.cancel()

Referenced by qpid::client::AutoCancel::~AutoCancel().

Functor qpid::sys::Runnable::functor

(

)

[inherited]

Create a functor object that will call this->run().

bool qpid::client::SubscriptionManager::get	(	Message &	result,
		const std::string &	queue,
		sys::Duration	timeout = 0
	)

Get a single message from a queue.

(Note: this currently uses a subscription per invocation and is thus relatively expensive. The subscription is cancelled as part of each call which can trigger auto-deletion).

Parameters:

result	is set to the message from the queue.
timeout	wait up this timeout for a message to appear.

Returns:

true if result was set, false if no message available after timeout.

Message qpid::client::SubscriptionManager::get	(	const std::string &	queue,
		sys::Duration	timeout = sys::TIME_INFINITE
	)

Get a single message from a queue.

(Note: this currently uses a subscription per invocation and is thus relatively expensive. The subscription is cancelled as part of each call which can trigger auto-deletion).

Parameters:

timeout

wait up this timeout for a message to appear.

Returns:

message from the queue.

Exceptions:

Exception

if the timeout is exceeded.

const SubscriptionSettings& qpid::client::SubscriptionManager::getDefaultSettings

(

)

const

Get the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.

SubscriptionSettings& qpid::client::SubscriptionManager::getDefaultSettings

(

)

Get the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.

Session qpid::client::SubscriptionManager::getSession

(

)

const

Subscription qpid::client::SubscriptionManager::getSubscription

(

const std::string &

name

)

const

Get a subscription by name.

Exceptions:

Exception

if not found.

QPID_CLIENT_INLINE_EXTERN bool qpid::client::Handle::isNull

(

)

const [inline, inherited]

Returns:

true if handle is null. It is an error to call any function on a null handle.

Definition at line 46 of file Handle.h.

QPID_CLIENT_INLINE_EXTERN bool qpid::client::Handle::isValid

(

)

const [inline, inherited]

Returns:

true if handle is valid, i.e. not null.

Definition at line 43 of file Handle.h.

QPID_CLIENT_INLINE_EXTERN qpid::client::Handle::operator bool

(

)

const [inline, inherited]

Conversion to bool supports idiom if (handle) { handle->...

}

Definition at line 49 of file Handle.h.

QPID_CLIENT_INLINE_EXTERN bool qpid::client::Handle::operator!

(

)

const [inline, inherited]

Operator ! supports idiom if (!handle) { do_if_handle_is_null(); }.

Definition at line 52 of file Handle.h.

SubscriptionManager& qpid::client::SubscriptionManager::operator=

(

const SubscriptionManager &

)

void qpid::client::SubscriptionManager::registerFailoverHandler

(

boost::function< void()>

fh

)

void qpid::client::SubscriptionManager::run

(

)

[virtual]

Deliver messages in the current thread until stop() is called.

Only one thread may be running in a SubscriptionManager at a time.

See also:

run

Implements qpid::sys::Runnable.

void qpid::client::SubscriptionManager::setAcceptMode

(

AcceptMode

mode

)

Set the default accept-mode for subscribe() calls that don't include a SubscriptionSettings parameter.

void qpid::client::SubscriptionManager::setAcquireMode

(

AcquireMode

mode

)

Set the default acquire-mode subscribe()s that don't specify SubscriptionSettings.

void qpid::client::SubscriptionManager::setAutoStop

(

bool

set = true

)

If set true, run() will stop when all subscriptions are cancelled.

If false, run will only stop when stop() is called. True by default.

void qpid::client::SubscriptionManager::setDefaultSettings

(

const SubscriptionSettings &

s

)

Set the default settings for subscribe() calls that don't include a SubscriptionSettings parameter.

void qpid::client::SubscriptionManager::setFlowControl	(	const std::string &	name,
		const FlowControl &	flow
	)

Set the flow control for a subscription.

void qpid::client::SubscriptionManager::setFlowControl	(	const std::string &	name,
		uint32_t	messages,
		uint32_t	bytes,
		bool	window = true
	)

Set the flow control for a subscription.

Parameters:

name,:	name of the subscription.
messages,:	message credit.
bytes,:	byte credit.
window,:	if true use window-based flow control.

void qpid::client::SubscriptionManager::setFlowControl	(	uint32_t	messages,
		uint32_t	bytes,
		bool	window = true
	)

Set the default flow control settings for subscribe() calls that don't include a SubscriptionSettings parameter.

Parameters:

messages,:	message credit.
bytes,:	byte credit.
window,:	if true use window-based flow control.

void qpid::client::SubscriptionManager::start

(

)

Start a new thread to deliver messages.

Only one thread may be running in a SubscriptionManager at a time.

See also:

start

void qpid::client::SubscriptionManager::stop

(

)

Stop delivery.

Causes run() to return, or the thread started with start() to exit.

Subscription qpid::client::SubscriptionManager::subscribe	(	MessageListener &	listener,
		const std::string &	queue,
		const SubscriptionSettings &	settings,
		const std::string &	name = std::string()
	)

Subscribe a MessagesListener to receive messages from queue.

Provide your own subclass of MessagesListener to process incoming messages. It will be called for each message received.

Parameters:

listener	Listener object to receive messages.
queue	Name of the queue to subscribe to.
settings	settings for the subscription.
name	unique destination name for the subscription, defaults to queue name.

Subscription qpid::client::SubscriptionManager::subscribe	(	LocalQueue &	localQueue,
		const std::string &	queue,
		const SubscriptionSettings &	settings,
		const std::string &	name = std::string()
	)

Subscribe a LocalQueue to receive messages from queue.

Incoming messages are stored in the queue for you to retrieve.

Parameters:

queue	Name of the queue to subscribe to.
flow	initial FlowControl for the subscription.
name	unique destination name for the subscription, defaults to queue name. If not specified, the queue name is used.

Subscription qpid::client::SubscriptionManager::subscribe	(	MessageListener &	listener,
		const std::string &	queue,
		const std::string &	name = std::string()
	)

Subscribe a MessagesListener to receive messages from queue.

Provide your own subclass of MessagesListener to process incoming messages. It will be called for each message received.

Parameters:

listener	Listener object to receive messages.
queue	Name of the queue to subscribe to.
name	unique destination name for the subscription, defaults to queue name. If not specified, the queue name is used.

Subscription qpid::client::SubscriptionManager::subscribe	(	LocalQueue &	localQueue,
		const std::string &	queue,
		const std::string &	name = std::string()
	)

Subscribe a LocalQueue to receive messages from queue.

Incoming messages are stored in the queue for you to retrieve.

Parameters:

queue	Name of the queue to subscribe to.
name	unique destination name for the subscription, defaults to queue name. If not specified, the queue name is used.

void qpid::client::Handle::swap

(

Handle< T > &

h

)

[inline, inherited]

Definition at line 54 of file Handle.h.

void qpid::client::SubscriptionManager::wait

(

)

Wait for the thread started by a call to start() to complete.

---

Member Data Documentation

Impl* qpid::client::Handle::impl [protected, inherited]

Definition at line 64 of file Handle.h.

const uint32_t qpid::client::SubscriptionManager::UNLIMITED = 0xFFFFFFFF [static]

Definition at line 220 of file SubscriptionManager.h.

---

The documentation for this class was generated from the following file:

• qpid/client/SubscriptionManager.h