org.xins.common.collections.expiry
Class ExpiryFolder

java.lang.Object
  extended byorg.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.


See http://www.xins.org/.