qpid::client::SubscriptionManager Class Reference

Apache Qpid - AMQP Messaging for Java JMS, C++, Python, Ruby, and .NET | Apache Qpid Documentation

- Main Page
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Attributes | Protected Attributes
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