org.adroitlogic.ultraesb.api.cache
Interface Cache

public interface Cache

Main cache class where the user is supposed to use for all the interactions with a specific cache. This exposes all the usage methods like put entries to the cache, update entries in the cache and get and delete entries from the cache. Apart form that this API is also instrumented with some other meta information related methods for the users to give the meta information about the cache and its entries.

In UltraESB there are 6 main types of caches, they are namely;

• LOCAL_PERMANENT - Entries you put will not get expired but do not get persisted, meaning that the content will be lost after a restart. The cache doesn't maintain the life cycle and the user should take care of the life cycle of an entry, otherwise you might face a resource exhaustion.
• LOCAL_TEMP - Entries you put will be expired after the specified time in the eh cache configuration. Default time out will be decided on the following parameters;
  • time to live - maximum life time of an entry (defaults to 10 minutes)
  • idle time - maximum idle time of an entry (defaults to 5 minutes)
  if the requirement is to keep the entry more than the above defaults, it is recommended to use the LOCAL_PERMANENT cache and manage the entry life cycle by your self.
• LOCAL_PERSISTENT - Entries you put will be persisted in to the disk and will be available even after JVM restart, or a machine restart, provided that the disk will remain readable and not corrupted
• DISTRIBUTED_PERMANENT - Only applicable when clustering is enabled. Entries you put will not get expired but do not get persisted but replicated among the cluster, if the node is part of a cluster which has identical node running, when this node is restarted, the cache will be loaded from the running node in the cluster. Life cycle of an entry has to be managed by the user.
• DISTRIBUTED_TEMP - Only applicable when clustering is enabled. Entries you put will be expired after the specified time in the eh cache configuration. Default time out will be decided on the following parameters;
  • time to live - maximum life time of an entry (defaults to 10 minutes)
  • idle time - maximum idle time of an entry (defaults to 5 minutes)
  if the requirement is to keep the entry more than the above defaults, it is recommended to use the DISTRIBUTED_PERMANENT cache and manage the entry life cycle by your self. The entry content will be replicated among the cluster and be available among all the nodes in the cluster until it gets expired.
• DISTRIBUTED_PERSISTENT - Only applicable when clustering is enabled. Entries you put will be persisted in to the disk and will be available even after JVM restart, or a machine restart, provided that the disk will remain readable and not corrupted. Also the entries will be replicated among the cluster. At startup if there are any nodes in the cluster the cache will be bootstrapped with the content from any of the arbitrary nodes in the cluster.

Since:

1.4.0

See Also:

CacheEntry

Method Summary

CacheEntry	delete(java.lang.Object key) Deletes the entry with the given key from the cache.
java.lang.Object	get(java.lang.Object key) Gets the value stored with the given key, the key itself has to be serializable if the cache is distributed, so does the value returned
CacheEntry	getEntry(java.lang.Object key) The entry representing the given key in the cache, the returned entry contains the value associated with the key as well as the meta information about the entry
java.lang.String	getName() Gets the name of this cache, it is not expected that the user changes this name, but the name is exposed as an identifier of the cache.
CacheType	getType() Gets the type of the cache, it has to be one of the; LOCAL_TEMP LOCAL_PERMANENT LOCAL_PERSISTENT DISTRIBUTED_TEMP DISTRIBUTED_PERMANENT DISTRIBUTED_PERSISTENT
boolean	isDistributed() Whether this cache is of distributed cache type, if the cache type is one of the following it is a distributed cache; DISTRIBUTED_TEMP DISTRIBUTED_PERMANENT DISTRIBUTED_PERSISTENT
boolean	isPermanent() Whether the cache keeps its content permanently (i.e.
boolean	isPersistent() Whether the cache persists its contents to the disk.
void	put(java.lang.Object key, java.lang.Object value) Puts an entry into the cache with the given key and value pair.

Method Detail

getType

CacheType getType()

Gets the type of the cache, it has to be one of the;

• LOCAL_TEMP
• LOCAL_PERMANENT
• LOCAL_PERSISTENT
• DISTRIBUTED_TEMP
• DISTRIBUTED_PERMANENT
• DISTRIBUTED_PERSISTENT

Returns:

the type of the cache

get

java.lang.Object get(java.lang.Object key)

Gets the value stored with the given key, the key itself has to be serializable if the cache is distributed, so does the value returned

Parameters:

key - of which the cache entry value is required

Returns:

the cache entry value for the given key

put

void put(java.lang.Object key,
         java.lang.Object value)

Puts an entry into the cache with the given key and value pair. If the cache is a distributed cache both the key and the value has to be Serializable. This method is used to create a new entry as well as to update an existing entry.

Parameters:

key - the cache key to index the cache entry

value - the value associated with the above key in the cache

delete

CacheEntry delete(java.lang.Object key)

Deletes the entry with the given key from the cache. If the cache is distributed the key has to be Serializable even if the resource is persisted, this call will permanently remove this entry.

Parameters:

key - entry key which needs to be removed

Returns:

the removed entry

getEntry

CacheEntry getEntry(java.lang.Object key)

The entry representing the given key in the cache, the returned entry contains the value associated with the key as well as the meta information about the entry

Parameters:

key - the key of which the entry is required

Returns:

the entry associated with the given key in the cache

getName

java.lang.String getName()

Gets the name of this cache, it is not expected that the user changes this name, but the name is exposed as an identifier of the cache.

Returns:

the name of the cache

isDistributed

boolean isDistributed()

Whether this cache is of distributed cache type, if the cache type is one of the following it is a distributed cache;

• DISTRIBUTED_TEMP
• DISTRIBUTED_PERMANENT
• DISTRIBUTED_PERSISTENT

Returns:

true if the cache is of one of the above types, false otherwise

isPermanent

boolean isPermanent()

Whether the cache keeps its content permanently (i.e. not expire). The method is implemented to give the logical meaning, so anything which return true to the Cache.isPersistent() should return true for this method too. In concrete terms all of the following types will belong to the permanent category.;

• LOCAL_PERMANENT
• LOCAL_PERSISTENT
• DISTRIBUTED_PERMANENT
• DISTRIBUTED_PERSISTENT

Returns:

true if the cache is of one of the above types, false otherwise

isPersistent

boolean isPersistent()

Whether the cache persists its contents to the disk. The concrete cache types belonging to this category are;

• LOCAL_PERSISTENT
• DISTRIBUTED_PERSISTENT

Returns:

true if the cache is of one of the above types, false otherwise