org.xins.common.collections.expiry
Class ExpiryFolder

java.lang.Object
  org.xins.common.collections.expiry.ExpiryFolder

public final class ExpiryFolder

extends Object

Expiry folder. Contains values indexed by key. Entries in this folder will expire after a predefined amount of time, unless their lifetime is extended within that timeframe. This is done using the get(Object) method.

Listeners are supported. Listeners are added using the addListener(ExpiryListener) method and removed using the removeListener(ExpiryListener) method. If a listener is registered multiple times, it will receive the events multiple times as well. And it will have to be removed multiple times as well.

This class is thread-safe.

Since:

XINS 1.0.0

Version:

$Revision: 1.52 $ $Date: 2006/10/24 09:31:13 $

Author:

Ernst de Haan, Anthony Goubard

Constructor Summary

ExpiryFolder(String name, ExpiryStrategy strategy)
Constructs a new ExpiryFolder with the specified name and strategy.

ExpiryFolder(String name, ExpiryStrategy strategy, boolean strictChecking, long maxQueueWaitTime)
Deprecated. Deprecated since XINS 1.0.1. Use the constructor ExpiryFolder(String,ExpiryStrategy) instead.

Method Summary

void	addListener(ExpiryListener listener) Adds the specified object as a listener for expiry events.
void	copy(ExpiryFolder newFolder) Copies the entries of this ExpiryFolder into another one.
boolean	equals(Object obj) Checks whether this object is considered equal to the argument.
Object	find(Object key) Finds the value associated with a key.
Object	get(Object key) Gets the value associated with a key and extends the lifetime of the matching entry, if there was a match.
String	getName() Returns the name given to this expiry folder.
ExpiryStrategy	getStrategy() Returns the strategy associated with this folder.
int	hashCode() Returns a hash code value for the object.
void	put(Object key, Object value) Associates the specified key with the specified value.
Object	remove(Object key) Removes the specified key from this folder.
void	removeListener(ExpiryListener listener) Removes the specified object as a listener for expiry events.
int	size() Gets the number of entries.
String	toString() Returns a textual representation of this object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ExpiryFolder

public ExpiryFolder(String name,
                    ExpiryStrategy strategy)
             throws IllegalArgumentException,
                    IllegalStateException

Constructs a new ExpiryFolder with the specified name and strategy. When the strategy is stopped (see ExpiryStrategy.stop() then this folder becomes invalid and can no longer be used.

Parameters:

name - description of this folder, to be used in log and exception messages, not null.

strategy - the strategy that should be applied, not null.

Throws:

IllegalArgumentException - if name == null || strategy == null.

IllegalStateException - if the strategy is already stopped.

Since:

XINS 1.0.1

ExpiryFolder

public ExpiryFolder(String name,
                    ExpiryStrategy strategy,
                    boolean strictChecking,
                    long maxQueueWaitTime)
             throws IllegalArgumentException

Deprecated. Deprecated since XINS 1.0.1. Use the constructor ExpiryFolder(String,ExpiryStrategy) instead.

Constructs a new ExpiryFolder with the specified name and strategy and some specific tweaks. When the strategy is stopped (see ExpiryStrategy.stop() then this folder becomes invalid and can no longer be used.

Since XINS 1.0.1, the arguments strictChecking and maxQueueWaitTime are not used at all.

Parameters:

name - description of this folder, to be used in log and exception messages, not null.

strategy - the strategy that should be applied, not null.

strictChecking - flag that indicates if checking of thread synchronization operations should be strict or loose.

maxQueueWaitTime - the maximum time in milliseconds a thread can wait in the queue for obtaining read or write access to a resource, must be > 0L.

Throws:

IllegalArgumentException - if name == null || strategy == null || maxQueueWaitTime <= 0L.

Method Detail

equals

public boolean equals(Object obj)

Checks whether this object is considered equal to the argument.

Parameters:

obj - the object to compare with.

Returns:

true if this object is considered equal to obj, or false otherwise.

See Also:

Object.equals(Object)

hashCode

public int hashCode()

Returns a hash code value for the object.

Returns:

a hash code value for this object.

See Also:

Object.hashCode(), equals(Object)

getName

public String getName()

Returns the name given to this expiry folder.

Returns:

the name assigned to this expiry folder, not null.

addListener

public void addListener(ExpiryListener listener)
                 throws IllegalStateException,
                        IllegalArgumentException

Adds the specified object as a listener for expiry events.

Parameters:

listener - the listener to be registered, cannot be null.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if listener == null.

removeListener

public void removeListener(ExpiryListener listener)
                    throws IllegalStateException,
                           IllegalArgumentException

Removes the specified object as a listener for expiry events.

If the listener cannot be found, then nothing happens.

Parameters:

listener - the listener to be unregistered, cannot be null.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if listener == null.

size

public int size()
         throws IllegalStateException

Gets the number of entries.

Returns:

the number of entries in this expiry folder, always >= 0.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

get

public Object get(Object key)
           throws IllegalStateException,
                  IllegalArgumentException

Gets the value associated with a key and extends the lifetime of the matching entry, if there was a match.

The more recently the specified entry was accessed, the faster the lookup.

Parameters:

key - the key to lookup, cannot be null.

Returns:

the value associated with the specified key, or null if and only if this folder does not contain an entry with the specified key.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if key == null.

find

public Object find(Object key)
            throws IllegalStateException,
                   IllegalArgumentException

Finds the value associated with a key. The lifetime of the matching entry is not extended.

The more recently the specified entry was accessed, the faster the lookup.

Parameters:

key - the key to lookup, cannot be null.

Returns:

the value associated with the specified key, or null if and only if this folder does not contain an entry with the specified key.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if key == null.

put

public void put(Object key,
                Object value)
         throws IllegalStateException,
                IllegalArgumentException

Associates the specified key with the specified value.

Parameters:

key - they key for the entry, cannot be null.

value - they value for the entry, cannot be null.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if key == null || value == null.

remove

public Object remove(Object key)
              throws IllegalStateException,
                     IllegalArgumentException

Removes the specified key from this folder.

Parameters:

key - the key for the entry, cannot be null.

Returns:

the old value associated with the specified key, or null if and only if this folder does not contain an entry with the specified key.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if key == null.

copy

public void copy(ExpiryFolder newFolder)
          throws IllegalStateException,
                 IllegalArgumentException

Copies the entries of this ExpiryFolder into another one. This method does not perform a deep copy, so if a key is added or removed, both folders will be modified.

Parameters:

newFolder - the new folder where the entries should be copied into, cannot be null, cannot be this.

Throws:

IllegalStateException - if the associated ExpiryStrategy has stopped already.

IllegalArgumentException - if newFolder == null or newFolder == this or if the precision of newFolder is not the same as for this ExpiryFolder.

getStrategy

public ExpiryStrategy getStrategy()
                           throws IllegalStateException

Returns the strategy associated with this folder.

Returns:

the strategy, never null.

Throws:

IllegalStateException - if the associated strategy has already stopped.

toString

public String toString()

Returns a textual representation of this object.

Returns:

a textual representation of this ExpiryFolder, which includes the name.