org.exolab.jms.messagemgr
Class ConsumerManager

java.lang.Object
  |
  +--org.exolab.jms.messagemgr.ConsumerManager

All Implemented Interfaces:

DestinationCacheEventListener, GarbageCollectable

public class ConsumerManager

extends java.lang.Object

implements DestinationCacheEventListener, GarbageCollectable

The consumer manager is responsible for creating and managing the lifecycle of Consumer. The consumer manager maintains a list of all active consumers.

The consumer manager, in an attempt to make better utilization of resource will also act as a proxy for all inactive durable subscribers So it will act as a DestinationCacheEventListener and process the message on behalf of the inactive consumer.

Version:

$Revision: 1.33 $ $Date: 2003/09/25 11:24:16 $

Author:

Jim Alateras

Method Summary

void	cleanUnreferencedEndpoints(JmsDestination dest) Clean all the unreferenced endpoints for a specified destination.
void	collectGarbage(boolean aggressive) Perform any garbage collection on this resource.
java.util.Iterator	consumerEndpoints() Return a list of ConsumerEndpoint objects, both transient and durable that are currently active.
java.util.Iterator	consumerIds() Return a list of consumer names id's currently active in the consumer manager.
ConsumerEndpoint	createConsumerEndpoint(JmsServerSession session, long clientId, JmsDestination destination, java.lang.String selector) Create a transient consumer for the specified destination.
void	createDurableConsumer(JmsTopic topic, java.lang.String name) This method creates an actual durable consumer for the specified and caches it.
DurableConsumerEndpoint	createDurableConsumerEndpoint(JmsServerSession session, JmsTopic topic, java.lang.String name, long clientId, java.lang.String selector) Create a durable consumer with the specified well-known name.
static ConsumerManager	createInstance() Create the singleton instance of the consumer manager
ConsumerEndpoint	createQueueBrowserEndpoint(JmsServerSession session, long clientId, JmsQueue queue, java.lang.String selector) Create a browser for the specified destination and the selector.
void	deleteConsumerEndpoint(ConsumerEndpoint consumer) Destroy the specified consumer
void	deleteDurableConsumerEndpoint(java.lang.String name) Destroy the endpoint associated with the specified durable consumer
void	destroy() Destroy this manager.
boolean	durableConsumerExists(java.lang.String name) Check if the specified durable consumer exists
boolean	exists(java.lang.String id) Check whether a consumer, with the specified identity actually exists.
ConsumerEndpoint	getConsumerEndpoint(java.lang.String id) Return the consumer with the specified identity
JmsDestination	getDestinationForConsumerName(java.lang.String name) Return the destination assoicated with the specified durable consumer.
java.util.Vector	getDurableConsumersForDest(JmsTopic dest) Return a list of durable subscribers for the specified destination
java.util.LinkedList	getEndpointsForDest(JmsDestination dest) Return a list of ConsumerEndpoint objects attached to the specified destination
boolean	hasActiveConsumers(JmsDestination destination) Check whether there is an active consumer for the specified destination
boolean	hasActiveDurableConsumers(JmsDestination topic) Check whether there are active durable consumers for the specified destination.
static ConsumerManager	instance() Return the singleton instance of the ConsumerManager
boolean	isDurableConsumerActive(java.lang.String name) Check whether a particular durable consumer is active
boolean	messageAdded(MessageImpl message) This event is called when a non-persistent message is added to the DestinationCache.
boolean	messageRemoved(MessageImpl message) This event is called when a message is removed from the DestinationCache.
boolean	persistentMessageAdded(java.sql.Connection connection, MessageImpl message) This event is called when a persistent message is added to the DestinationCache.
boolean	persistentMessageRemoved(java.sql.Connection connection, MessageImpl message) This event is called when a message is removed from the DestinationCache.
void	removeDurableConsumer(java.lang.String name) This method will remove the durable consumer from the database and from transient memory only if it exists and is inactive.
void	removeDurableConsumers(JmsDestination topic) This method will remove all the durable consumers from the database and from transient memory whether they are active or not.
boolean	validSubscription(java.lang.String topic, java.lang.String name) This method will check that the name-destination pair actually are valid and exist as a DurableConsumer entity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createInstance

public static ConsumerManager createInstance()
                                      throws org.exolab.core.service.ServiceException

Create the singleton instance of the consumer manager

Returns:

the singleton instance

Throws:

org.exolab.core.service.ServiceException - if the service cannot be initialised

instance

public static ConsumerManager instance()

Return the singleton instance of the ConsumerManager

Returns:

ConsumerManager

createDurableConsumer

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

This method creates an actual durable consumer for the specified and caches it. It does not create and endpoint. To create the endpoint the client should call createDurableConsumerEndpoint.

Parameters:

topic - - the topic destination

name - - the consumer name

Throws:

javax.jms.JMSException - - if it cannot be created

removeDurableConsumer

public void removeDurableConsumer(java.lang.String name)
                           throws javax.jms.JMSException

This method will remove the durable consumer from the database and from transient memory only if it exists and is inactive. If there is an active endpoint then it cannot be deleted and an exception will be raise.

If the durable consumer does not exist then an exception is also raised.

Parameters:

name - - the consumer name

Throws:

javax.jms.JMSException - - if it cannot be removed

removeDurableConsumers

public void removeDurableConsumers(JmsDestination topic)
                            throws javax.jms.JMSException

This method will remove all the durable consumers from the database and from transient memory whether they are active or not.

If we have problems removing the durable consumers then throw the JMSException.

Parameters:

topic - the topic to remove consumers for

createConsumerEndpoint

public ConsumerEndpoint createConsumerEndpoint(JmsServerSession session,
                                               long clientId,
                                               JmsDestination destination,
                                               java.lang.String selector)
                                        throws javax.jms.JMSException,
                                               javax.jms.InvalidSelectorException

Create a transient consumer for the specified destination. The client can optionally specify a selector to filter messages.

The clientId parameter is used to indirectly reference the remote client which is uniquely identifiable within a session and is used during asynchronous message delivery.

Parameters:

clientId - - indirect reference to the remote client

destination - - consumer for this destination

selector - - the consumer's selector if specified.

Returns:

transient consumer

createDurableConsumerEndpoint

public DurableConsumerEndpoint createDurableConsumerEndpoint(JmsServerSession session,
                                                             JmsTopic topic,
                                                             java.lang.String name,
                                                             long clientId,
                                                             java.lang.String selector)
                                                      throws javax.jms.JMSException

Create a durable consumer with the specified well-known name.

Parameters:

session - the owning session

topic - consumer for this topic

name - the unique subscriber name

clientId - the remote client identity

selector - the message selector. May be null

Returns:

the durable consumer endpoint

Throws:

javax.jms.JMSException - if a durable consumer is already active with the same name, or the topic doesn't exist, or selector is an invalid selector

hasActiveDurableConsumers

public boolean hasActiveDurableConsumers(JmsDestination topic)

Check whether there are active durable consumers for the specified destination.

Parameters:

topic - the destination to check

true - if there is at least one active consumer

createQueueBrowserEndpoint

public ConsumerEndpoint createQueueBrowserEndpoint(JmsServerSession session,
                                                   long clientId,
                                                   JmsQueue queue,
                                                   java.lang.String selector)
                                            throws javax.jms.JMSException

Create a browser for the specified destination and the selector. A browser is responsible for passing all messages back to the client that reside on the queue

Parameters:

session - the owning session

clientId - the remote client identity, which is session scoped

queue - the queue destination cache

selector - optional filter

Returns:

the queue browser endpoint

deleteDurableConsumerEndpoint

public void deleteDurableConsumerEndpoint(java.lang.String name)
                                   throws javax.jms.JMSException

Destroy the endpoint associated with the specified durable consumer

Parameters:

name - - name of the durable consumer

Throws:

javax.jms.JMSException - - if itt cannot complete the request

deleteConsumerEndpoint

public void deleteConsumerEndpoint(ConsumerEndpoint consumer)

Destroy the specified consumer

Parameters:

consumer - the consumer to destroy

getConsumerEndpoint

public ConsumerEndpoint getConsumerEndpoint(java.lang.String id)

Return the consumer with the specified identity

Parameters:

id - - identity of the consumer

Returns:

Consumer - associated consumer object or null

consumerEndpoints

public java.util.Iterator consumerEndpoints()

Return a list of ConsumerEndpoint objects, both transient and durable that are currently active.

Returns:

Iterator - iterator of ConsumerEndpoint objects

consumerIds

public java.util.Iterator consumerIds()

Return a list of consumer names id's currently active in the consumer manager.

Returns:

Iterator - iterator of {#link String} ids

exists

public boolean exists(java.lang.String id)

Check whether a consumer, with the specified identity actually exists.

Parameters:

id - - identity of the consumer

Returns:

boolean - true if one exists

hasActiveConsumers

public boolean hasActiveConsumers(JmsDestination destination)
                           throws javax.jms.JMSException

Check whether there is an active consumer for the specified destination

Parameters:

destination - - the destination to check

Returns:

boolean - true if it exists

isDurableConsumerActive

public boolean isDurableConsumerActive(java.lang.String name)

Check whether a particular durable consumer is active

Parameters:

name - - the consumer name

Returns:

boolean - true if active

getDestinationForConsumerName

public JmsDestination getDestinationForConsumerName(java.lang.String name)

Return the destination assoicated with the specified durable consumer.

Parameters:

name - - consumer name

Returns:

JmsDestination - the destination is it registered under or null

durableConsumerExists

public boolean durableConsumerExists(java.lang.String name)

Check if the specified durable consumer exists

Parameters:

name - - the name of the durable consumer

Returns:

boolean - true if successful

validSubscription

public boolean validSubscription(java.lang.String topic,
                                 java.lang.String name)

This method will check that the name-destination pair actually are valid and exist as a DurableConsumer entity

Parameters:

topic - - the name of the topic

name - - the name of the durable consumer

Returns:

boolean - true if valid and false otherwise

messageAdded

public boolean messageAdded(MessageImpl message)

Description copied from interface: DestinationCacheEventListener

This event is called when a non-persistent message is added to the DestinationCache.

Specified by:

messageAdded in interface DestinationCacheEventListener

Following copied from interface: org.exolab.jms.messagemgr.DestinationCacheEventListener

Parameters:

message - - message added to cache

messageRemoved

public boolean messageRemoved(MessageImpl message)

Description copied from interface: DestinationCacheEventListener

This event is called when a message is removed from the DestinationCache.

Specified by:

messageRemoved in interface DestinationCacheEventListener

Following copied from interface: org.exolab.jms.messagemgr.DestinationCacheEventListener

Parameters:

message - - message removed from cache

persistentMessageAdded

public boolean persistentMessageAdded(java.sql.Connection connection,
                                      MessageImpl message)
                               throws PersistenceException

Description copied from interface: DestinationCacheEventListener

This event is called when a persistent message is added to the DestinationCache.

Specified by:

persistentMessageAdded in interface DestinationCacheEventListener

Following copied from interface: org.exolab.jms.messagemgr.DestinationCacheEventListener

Parameters:

connection - - the database connection

message - - message added to cache

Throws:

PersistenceException - - if there is a persistence related problem

persistentMessageRemoved

public boolean persistentMessageRemoved(java.sql.Connection connection,
                                        MessageImpl message)
                                 throws PersistenceException

Description copied from interface: DestinationCacheEventListener

This event is called when a message is removed from the DestinationCache.

Specified by:

persistentMessageRemoved in interface DestinationCacheEventListener

Following copied from interface: org.exolab.jms.messagemgr.DestinationCacheEventListener

Parameters:

connection - - the database connection

message - - message to remove from cache

Throws:

PersistenceException - - if there is a persistence related problem

destroy

public void destroy()

Destroy this manager. This is brutal and final

getDurableConsumersForDest

public java.util.Vector getDurableConsumersForDest(JmsTopic dest)

Return a list of durable subscribers for the specified destination

Returns:

Vector - a vector of strings, which denote the name

cleanUnreferencedEndpoints

public void cleanUnreferencedEndpoints(JmsDestination dest)

Clean all the unreferenced endpoints for a specified destination. Unreference endpoints usually occur when the client abnormally terminates leaving some dangling endpoints on the server.

Parameters:

dest- - the destination to query

getEndpointsForDest

public java.util.LinkedList getEndpointsForDest(JmsDestination dest)

Return a list of ConsumerEndpoint objects attached to the specified destination

Parameters:

dest - the destination to query

Returns:

list of endpoints

collectGarbage

public void collectGarbage(boolean aggressive)

Description copied from interface: GarbageCollectable

Perform any garbage collection on this resource. This will have the effect of releasing system resources. If the 'aggressive' flag is set to true then the garbage collection should do more to release memory related resources since it is called when the application memory is low.

Specified by:

collectGarbage in interface GarbageCollectable

Following copied from interface: org.exolab.jms.gc.GarbageCollectable

Parameters:

aggressive - - true for aggressive garbage collection