org.exolab.jms.messagemgr
Class DestinationCache

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

All Implemented Interfaces:

GarbageCollectable, Identifiable, LeaseEventListenerIfc, MessageManagerEventListener, java.io.Serializable

Direct Known Subclasses:

QueueDestinationCache, TopicDestinationCache

public abstract class DestinationCache

extends java.lang.Object

implements MessageManagerEventListener, Identifiable, LeaseEventListenerIfc, GarbageCollectable

A DestinationCache is used to cache messages for a particular destination.

It implements MessageManagerEventListener in order to be notified of messages being added to and removed from MessageMgr

A ConsumerEndpoint registers with a DestinationCache to receive messages for a particular destination.

In all instances this class doesn't deal with Message objects directly, but instead uses their corresponding MessageHandle, which is far more lightweight.

A two level cache is used to facilitate quick seeding of registered consumers and quick per-consumer-acknowledgment strategy. The two level cache includes this, the DestinationCache, at the highest level and then ConsumerManager at the lowest level.

In addition to registering ConsumerEndpoint objects the cache also supports DestinationCacheEventListeners. A listener will be notified when messages are added to the cache but do not actually consume messages. A cache can have one or more registered listeners. This feature is predominately used by browsers or iterators of destinations.

Clients can also become lifecycle listeners for this object to get notified during initialization and shutdwon.

This cache is ordered on priority.

Version:

$Revision: 1.34 $ $Date: 2003/12/29 13:09:15 $

Author:

Jim Alateras

See Also:

Serialized Form

Field Summary

protected java.util.List	_consumers This is the list of consumers that have subscribed to this cache.
protected MessageLeaseHelper	_leaseHelper The message lease helper is used to manage leases for messages cached by the destination

Method Summary

abstract boolean	canDestroy() Determines if this cache can be destroyed
void	collectGarbage(boolean aggressive) Perform any garbage collection on this resource.
java.util.Iterator	getConsumers() Return an enmeration of all consumers attached to this cache.
abstract JmsDestination	getDestination() Return a reference to the underlying destination
java.lang.String	getDestinationByName() Return the string form of the destination
java.lang.String	getId() Return the identity of the object
int	getMaximumSize() Return the cache's maximum size
int	getMessageCount() Return the number of messages currently active for this destination
abstract boolean	messageAdded(JmsDestination destination, MessageImpl message) This method is called when the MessageMgr adds a message for this destination to the cache
abstract void	messageRemoved(JmsDestination destination, MessageImpl message) This method is called when the MessageMgr removes a message from the cache.
void	onLeaseExpired(java.lang.Object leasedObject) This method is called whenever a lease expires.
boolean	registerConsumer(ConsumerEndpoint consumer) Register a consumer with this cache.
protected MessageImpl	resolveExpiredMessage(MessageHandle handle) Resolve an expired message through its handle
void	setCacheEvictionPolicy(CacheEvictionPolicy policy) Set the CacheEvictionPolicy for this object.
void	setMaximumSize(int size) Set the maximum size of the cache.
void	shutdown() Close the cache and unregister all the consumers.
void	unregisterConsumer(ConsumerEndpoint consumer) Remove the consumer for the list of registered consumers.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.exolab.jms.messagemgr.MessageManagerEventListener

persistentMessageAdded, persistentMessageRemoved

Field Detail

_consumers

protected java.util.List _consumers

This is the list of consumers that have subscribed to this cache. It hosts both durable and transient subscribers

_leaseHelper

protected MessageLeaseHelper _leaseHelper

The message lease helper is used to manage leases for messages cached by the destination

Method Detail

setMaximumSize

public void setMaximumSize(int size)

Set the maximum size of the cache. If there are more than this number of messages in the cache the CacheEvictionPolicy is enforced to remove messages.

Parameters:

size - - maximum number of messages a destination can hold

getMaximumSize

public int getMaximumSize()

Return the cache's maximum size

Returns:

int - size of cache

getDestination

public abstract JmsDestination getDestination()

Return a reference to the underlying destination

Returns:

JmsDestination

getDestinationByName

public java.lang.String getDestinationByName()

Return the string form of the destination

Returns:

String

setCacheEvictionPolicy

public void setCacheEvictionPolicy(CacheEvictionPolicy policy)

Set the CacheEvictionPolicy for this object. This determines how messages are removed when the cache's upper limit is reached.

Parameters:

policy - the eviction policy

registerConsumer

public boolean registerConsumer(ConsumerEndpoint consumer)

Register a consumer with this cache. Part of the registration process will be to seed the ConsumerEndpoint with an initial list of messages that it needs to consume and then feed messages to it through the specified listener object.

Messages are subsequently passed down to the consumer's through the listener, as they enter the DestinationCache.

Parameters:

consumer - - message consumer for this destination

Returns:

boolean - true if registered and false otherwise

unregisterConsumer

public void unregisterConsumer(ConsumerEndpoint consumer)

Remove the consumer for the list of registered consumers. If the consumer does not exist then the call fails silently.

Parameters:

consumer - - consumer to remove.

getConsumers

public java.util.Iterator getConsumers()

Return an enmeration of all consumers attached to this cache.

Returns:

Iterator - list of registered consumers

messageAdded

public abstract boolean messageAdded(JmsDestination destination,
                                     MessageImpl message)

This method is called when the MessageMgr adds a message for this destination to the cache

Specified by:

messageAdded in interface MessageManagerEventListener

Parameters:

message - - message added to cache

messageRemoved

public abstract void messageRemoved(JmsDestination destination,
                                    MessageImpl message)

This method is called when the MessageMgr removes a message from the cache.

Specified by:

messageRemoved in interface MessageManagerEventListener

Parameters:

message - - message removed from cache

getMessageCount

public int getMessageCount()

Return the number of messages currently active for this destination

Returns:

int - number of active messages

onLeaseExpired

public void onLeaseExpired(java.lang.Object leasedObject)

This method is called whenever a lease expires. It passes the object that has expired.

Specified by:

onLeaseExpired in interface LeaseEventListenerIfc

Parameters:

leasedObject - reference to the leased object

canDestroy

public abstract boolean canDestroy()

Determines if this cache can be destroyed

Returns:

true if the cache can be destroyed, otherwise false

shutdown

public void shutdown()

Close the cache and unregister all the consumers. Notify any and all DestinationCacheLifecycleListeners.

Once the cache is closed it will no longger receive messages for this destination.

getId

public java.lang.String getId()

Description copied from interface: Identifiable

Return the identity of the object

Specified by:

getId in interface Identifiable

Following copied from interface: org.exolab.jms.Identifiable

Returns:

the object identity

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

resolveExpiredMessage

protected MessageImpl resolveExpiredMessage(MessageHandle handle)

Resolve an expired message through its handle

Parameters:

handle - the expired message's handle

Returns:

the expired message. May be null.