org.exolab.jms.messagemgr
Interface ConsumerManager

All Known Implementing Classes:

ConsumerManagerImpl

public interface ConsumerManager

ConsumerManager is responsible for creating and managing the lifecycle of consumers.

Version:

$Revision: 1.4 $ $Date: 2005/11/12 12:42:54 $

Author:

Tim Anderson

Method Summary

void	closeConsumer(ConsumerEndpoint consumer) Close a consumer.
ConsumerEndpoint	createConsumer(JmsDestination destination, long connectionId, java.lang.String selector, boolean noLocal) Create a transient consumer for the specified destination.
DurableConsumerEndpoint	createDurableConsumer(JmsTopic topic, java.lang.String name, java.lang.String clientID, long connectionId, boolean noLocal, java.lang.String selector) Create a durable consumer.
ConsumerEndpoint	createQueueBrowser(JmsQueue queue, java.lang.String selector) Create a new queue browser.
ConsumerEndpoint	getConsumerEndpoint(long consumerId) Return the consumer with the specified identity.
ConsumerEndpoint	getConsumerEndpoint(java.lang.String persistentId) Return the consumer with the specified persistent identity.
boolean	hasActiveConsumers(JmsDestination destination) Determines if there are any active consumers for a destination.
void	subscribe(JmsTopic topic, java.lang.String name, java.lang.String clientID) Create a new durable subscription.
void	unsubscribe(JmsTopic topic) Remove all durable subscriptions for a destination.
void	unsubscribe(java.lang.String name, java.lang.String clientID) Remove a durable subscription.

Method Detail

subscribe

public void subscribe(JmsTopic topic,
                      java.lang.String name,
                      java.lang.String clientID)
               throws javax.jms.JMSException

Create a new durable subscription.

A client can change an existing durable subscription by creating a new subscription with the same name and a new topic. Changing a durable subscriber is equivalent to unsubscribing the old one and creating a new one.

Parameters:

topic - the topic to subscribe to

name - the subscription name

clientID - the client identifier. May be null

Throws:

javax.jms.InvalidDestinationException - if topic is not a persistent destination, or name is an invalid subscription name

javax.jms.JMSException - if the durable consumer can't be created

unsubscribe

public void unsubscribe(java.lang.String name,
                        java.lang.String clientID)
                 throws javax.jms.JMSException

Remove a durable subscription.

A subscription may only be removed if the associated DurableConsumerEndpoint is inactive.

Parameters:

name - the subscription name

clientID - the client identifier. May be null

Throws:

javax.jms.InvalidDestinationException - if an invalid subscription name is specified.

javax.jms.JMSException - if the durable consumer is active, or cannot be removed

unsubscribe

public void unsubscribe(JmsTopic topic)
                 throws javax.jms.JMSException

Remove all durable subscriptions for a destination.

Subscriptions may only be removed if the associated ConsumerEndpoints are inactive.

Parameters:

topic - the topic to remove consumers for

Throws:

javax.jms.JMSException - if the subscriptions can't be removed

createConsumer

public ConsumerEndpoint createConsumer(JmsDestination destination,
                                       long connectionId,
                                       java.lang.String selector,
                                       boolean noLocal)
                                throws javax.jms.JMSException

Create a transient consumer for the specified destination.

Parameters:

destination - the destination to consume messages from

connectionId - the identity of the connection that owns this consumer

selector - the message selector. May be null

noLocal - if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for noLocal is not specified if the destination is a queue.

Returns:

a new transient consumer

Throws:

javax.jms.InvalidSelectorException - if the selector is not well formed

javax.jms.JMSException - if the consumer can't be created

createDurableConsumer

public DurableConsumerEndpoint createDurableConsumer(JmsTopic topic,
                                                     java.lang.String name,
                                                     java.lang.String clientID,
                                                     long connectionId,
                                                     boolean noLocal,
                                                     java.lang.String selector)
                                              throws javax.jms.JMSException

Create a durable consumer.

Parameters:

topic - the topic to subscribe to

name - the subscription name

clientID - the client identifier. May be null.

connectionId - the identity of the connection that owns this consumer

noLocal - if true, and the destination is a topic, inhibits the delivery of messages published by its own connection.

selector - the message selector. May be null

Returns:

the durable consumer endpoint

Throws:

javax.jms.InvalidDestinationException - if topic is not a persistent destination

javax.jms.InvalidSelectorException - if the selector is not well formed

javax.jms.JMSException - if a durable consumer is already active with the same name

createQueueBrowser

public ConsumerEndpoint createQueueBrowser(JmsQueue queue,
                                           java.lang.String selector)
                                    throws javax.jms.JMSException

Create a new queue browser.

Parameters:

queue - the queue to browse

selector - the message selector. May be null

Returns:

the queue browser endpoint

Throws:

javax.jms.InvalidSelectorException - if the selector is not well formed

javax.jms.JMSException - if the browser can't be created

closeConsumer

public void closeConsumer(ConsumerEndpoint consumer)

Close a consumer.

Parameters:

consumer - the consumer to close

getConsumerEndpoint

public ConsumerEndpoint getConsumerEndpoint(long consumerId)

Return the consumer with the specified identity.

Parameters:

consumerId - the identity of the consumer

Returns:

the associated consumer, or null if none exists

getConsumerEndpoint

public ConsumerEndpoint getConsumerEndpoint(java.lang.String persistentId)

Return the consumer with the specified persistent identity.

Parameters:

persistentId - the persistent identity of the consumer

Returns:

the associated consumer, or null if none exists

hasActiveConsumers

public boolean hasActiveConsumers(JmsDestination destination)

Determines if there are any active consumers for a destination.

Parameters:

destination - the destination

Returns:

true if there is at least one consumer