Cache Interface

com.bea.p13n.cache
Cache Interface

public interface Cache

    extends CacheDefaults, CacheStats, ReloadableCache

The main interface for the cache. Provides methods to add, access, and remove entries from a cache.

Keys may be any object, although it is suggested that Strings or lightweight Serializable objects be used. In order to receive notifications to invalidate a particular key in the cache (from other nodes of a cluster or from Admin server), the key must be Serializable (so it can be transmitted between servers). Such keys must also have properly implemented equals() and hashcode() methods.

CAUTION: The cache data structure does not itself provide immutability of its values. In other words, it returns references to its actual objects. It is recommended that those values protect themselves from change unless that change is actually desired - remember these objects will eventually expire from the Cache.


All Superinterfaces
CacheDefaults, CacheStats, ReloadableCache

Field Summary

   
Fields from interface com.bea.p13n.cache.CacheDefaults
DEFAULT_ENABLED, DEFAULT_MAX_ENTRIES, DEFAULT_TTL, MAX_ENTRIES_MAX, TTL_NEVER_EXPIRE
 

Method Summary

public void
clear()
Remove all elements from the cache.
public boolean
containsKey(Object key)
Determines if an entry exists in the cache.
public Set
entrySet()
Access the values of the key/value pair of the Cache.
public Object
get(Object key)
Retrieve an entry in the Cache.
public int
getMaxEntries()
Get the max number of entries the cache can have.
public String
getName()
Get cache name.
public long
getTtl()
Get the time-to-live, in milliseconds, of entries for the cache.
public boolean
isEnabled()
Is the cache enabled?
public Set
keySet()
Access the keys of the key/value pair of the Cache.
public Object
put(Object key, Object value)
Put a value into the cache.
public Object
put(Object key, Object value, long ttl)
Put a value into the cache, with a specific time-to-live.
public Object
remove(Object key)
Removes a single entry from the Cache if it exists.
public void
setEnabled(boolean newEnabled)
Set enabled mode of cache.
public void
setMaxEntries(int maxEntries)
Set the max number of items the cache can have.
public void
setTtl(long timeToLive)
Set the default time-to-live for all elements in cache.
public int
size()
Size of the cache.
public String
toString()
Describes the attributes of the cache.
 
Methods from interface com.bea.p13n.cache.CacheStats
getHitCount, getHitRate, getMissCount, resetStats
 
Methods from interface com.bea.p13n.cache.ReloadableCache
getReloader, put, put, reload, setReloader, unsetReloader
   

Method Detail

clear() Method

public void clear()
Remove all elements from the cache.


containsKey(Object) Method

public boolean containsKey(Object key)
Determines if an entry exists in the cache.

Parameters

key
The key of a key/value pair to check for existence in the cache.

Returns

boolean true if the object associated with that key exists in the cache, false otherwise.

entrySet() Method

public Set entrySet()
Access the values of the key/value pair of the Cache. Values that have expired are not included in this set.

Returns

Set The set of values of the key/value pair of the Cache.

get(Object) Method

public Object get(Object key)
Retrieve an entry in the Cache. Returns null if the entry does not exist or has expired or if the cache is not enabled. Otherwise, it returns the Value associated with the key and moves the entry to the top of the LRU list (making it the most recently used object.

Parameters

key
The key of a key/value pair to retrieve from the cache.

Returns

Object the value of the key/value pair asslciated with the key, or null if the entry does not exist or has expired.

getMaxEntries() Method

public int getMaxEntries()
Get the max number of entries the cache can have. The cache uses a LRU strategy, so that it will never contain more than maxEntries entries.

Returns

the maximum number of entries of the cache

getName() Method

public String getName()
Get cache name. Each cache has a unique name, and is referenced by that name. The CacheFactory maintains a collection of cache objects, and the cache name represents the key in the key/value pair in the collection.

Returns

The cache name

getTtl() Method

public long getTtl()
Get the time-to-live, in milliseconds, of entries for the cache. Unless specified for each entry individually, the time-to-live is set upon creation of the cache and applies to all entries in the cache.

Returns

the cache's time-to-live value in milliseconds

isEnabled() Method

public boolean isEnabled()
Is the cache enabled?

Returns

boolean, true if it is enabled, flase otherwise.

keySet() Method

public Set keySet()
Access the keys of the key/value pair of the Cache. Values that have expired are not included in this set.

Returns

Set The set of keys in the key/value entries of the cacbe.

put(Object, Object) Method

public Object put(Object key, 
                  Object value)
Put a value into the cache.

Neither the key nor the value can be null

Parameters

key
the key of the entry to create
value
the value to associate with the key

Returns

Object the previous value for the key

put(Object, Object, long) Method

public Object put(Object key, 
                  Object value, 
                  long ttl)
Put a value into the cache, with a specific time-to-live.

Neither the key nor the value can be null

Parameters

key
the key of the entry to create
value
the value to associate with the key
ttl
time-to-live, in milliseconds, of the object. This ttl overrides the default ttl for the cache, and applies only to this object.

Returns

Object the previous value for the key

remove(Object) Method

public Object remove(Object key)
Removes a single entry from the Cache if it exists.

Parameters

key
The key of a key/value pair to remove from the cache.

Returns

The object that was removed, or null if object did not exist.

setEnabled(boolean) Method

public void setEnabled(boolean newEnabled)
Set enabled mode of cache. Disabling the cache will flush the cache and cause fetch, add, and remove to do nothing.

Parameters

newEnabled
true to enable the cache, false to disable the cache.

setMaxEntries(int) Method

public void setMaxEntries(int maxEntries)
Set the max number of items the cache can have. Because the cache implements a LRU (least-recently-used) strategy, the maximum allowed value for this is defined in CacheDefaults.MAX_ENTRIES_MAX.

Parameters

maxEntries
the maximum size of the cache

setTtl(long) Method

public void setTtl(long timeToLive)
Set the default time-to-live for all elements in cache. Note that using a value of TTL_NEVER_EXPIRE, means elements will never expire.

Parameters

timeToLive
timeToLive, in milliseconds

size() Method

public int size()
Size of the cache. This returns the size of the internal map. This may or may not match the size of the collection returned from the values method. The values method will strip out all expired values.

Returns

int The number of entries in the cache.

toString() Method

public String toString()
Describes the attributes of the cache.

Overrides
Object.toString()

Returns

the attributes of the cache.