org.dspace.services.model
Interface Cache

public interface Cache

This is a cache which can be used to store data.

This is an abstraction of the general concept of a cache.

A Cache holds objects with keys with a limited lifespan and stores them based on the underlying implementation. This cache interface adheres to the JSR-107 spec.

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

Method Summary

void	clear() Clear out all cached items from this cache.
boolean	exists(String key) Check if a key exists in the cache.
Object	get(String key) Gets an object from the cache if it can be found (maybe be a null).
CacheConfig	getConfig() Returns a readable object which has the configuration used by this cache in it.
List<String>	getKeys() Provides a method for finding out what keys are currently in the cache or getting all items out of the cache.
String	getName() Get the unique name which identifies this cache.
Object	look(String key) Gets an object from the cache without causing it to be refreshed or renewed.
void	put(String key, Object value) Puts an object in the cache which is identified by this key.
boolean	remove(String key) Removes an object from the cache if it exists or does nothing if it does not.
int	size() How many items does this cache hold?

Method Detail

getName

String getName()

Get the unique name which identifies this cache.

Returns:

string

put

void put(String key,
         Object value)

Puts an object in the cache which is identified by this key. Will overwrite an existing object if one is already using this key.

Parameters:

key - the key for an item in the cache

value - an object (this can be a null, e.g. to cache a miss)

Throws:

IllegalArgumentException - if the cache name is invalid or cacheName or key is null

get

Object get(String key)

Gets an object from the cache if it can be found (maybe be a null). Use the exists check to see if the object is in the cache before retrieving.

Parameters:

key - the key for an item in the cache

Returns:

the cached object (may be null) OR null if the cache object cannot be found

Throws:

IllegalArgumentException - if any arguments are null

getKeys

List<String> getKeys()

Provides a method for finding out what keys are currently in the cache or getting all items out of the cache. The keys are returned in no particular order.

NOTE: that this is actually quite costly in most cases and should only be used when really needed. It is much better to fetch the items you actually need directly using get(String).

Returns:

the list of all keys currently in this cache

look

Object look(String key)

Gets an object from the cache without causing it to be refreshed or renewed. Like get(String) except that it keeps the cache from refreshing the item that was retrieved.

Parameters:

key - the key for an item in the cache

Returns:

the cached object (may be null) OR null if the cache object cannot be found

Throws:

IllegalArgumentException - if any arguments are null

See Also:

get(String)

remove

boolean remove(String key)

Removes an object from the cache if it exists or does nothing if it does not.

Parameters:

key - the key for an item in the cache

Returns:

true if the object was removed or false if it could not be found in the cache

Throws:

IllegalArgumentException - if any arguments are null

exists

boolean exists(String key)

Check if a key exists in the cache.

Parameters:

key - the key for an item in the cache

Returns:

true if the object was removed or false if it could not be found in the cache

Throws:

IllegalArgumentException - if any arguments are null

size

int size()

How many items does this cache hold?

Returns:

the count of the number of active items in the cache. Does not include expired items.

clear

void clear()

Clear out all cached items from this cache.

getConfig

CacheConfig getConfig()

Returns a readable object which has the configuration used by this cache in it.

Returns:

the object indicating the configuration of this cache