net.itrixlabs.cache.core

Interface ApplicationCache<Key,V>

All Superinterfaces:

org.springframework.beans.factory.DisposableBean, org.springframework.beans.factory.InitializingBean

All Known Implementing Classes:

AbstractFileSystemCache, SerializableAuthCache, SerializableCsrfCache, SerializableGenericCache, SerializableUserCache

public interface ApplicationCache<Key,V>
extends org.springframework.beans.factory.InitializingBean, org.springframework.beans.factory.DisposableBean

Primordial interface for maintaining application cache. In contrast to other cache providers, this type of cache ensures type checking and specifies efficient caching for a distributed systems. However, implementations can be focused upon non-distributed systems too.

Implementations should provide appropriate methods to set their cache parameters (e.g. time-to-live) and/or force removal of entities before their normal expiration. These are not part of the AuthorizationCache interface contract because they vary depending on the type of caching system used (in-memory, disk, cluster, hybrid etc.).

Caching is generally only required in applications which do not maintain server-side state, such as remote clients or web services. The authentication credentials are then presented on each invocation and the overhead of accessing a database or other persistent storage mechanism to validate would be excessive. In this case, you would configure a cache to store the UserDetails information rather than loading it each time.

Note that the interface is declared abstract which doesn't make any sense. But, it's just to notify the programmer that this type is not an initialization/autowiring candidate. Interfaces/Classes extending/implementing this contract must be initialized so as to support multiple types and instances of cache per container (as suited).

Since:

November 10^th, 2015

Author:

Abhinav Rai

Method Summary

Modifier and Type	Method and Description
void	evictFromCache(Object key) Removes the specified entry from the cache.
void	flush()
V	getFromCache(Object key) Obtains a stored entry from the cache.
void	initialize() Initializes the application cache (doesn't create it).
boolean	isPresentInCache(Object key) Checks the application cache on which the method is called for the specified key and returns true if the condition is true, else false.
void	putInCache(Object key, V entry) Places an entry in the cache.

Methods inherited from interface org.springframework.beans.factory.InitializingBean

afterPropertiesSet

Methods inherited from interface org.springframework.beans.factory.DisposableBean

destroy

Method Detail

initialize

void initialize()

Initializes the application cache (doesn't create it). Can make use of a data-store for pre-fetching already stored application data (if required) typically upon container restart.

Each type of application cache is initialized separately in order to maintain sanity and usage simplicity. Thus, please be advised that a cache type must be instantiated & initialized manually before use (manually just means that extra code is required for the same).

getFromCache

V getFromCache(Object key)

Obtains a stored entry from the cache. Implementations must make sure not to throw an exception even if one occurs here.

Important: Note that you may use any well known java type as key like Long or String or a custom type as long as it abides by the contract defined by the Key interface, i.e., the key should be uniquely identifiable using its value and not the Key instance as whole. In short, you must override the Object.equals(Object) and Object.hashCode() methods of that particular key type to make sure your identifier can be uniquely distinguished from with-in the cache.

Parameters:

key - the unique identifier to use for fetching the entry; be advised that the same identifier must be used for saving the details into the cache

Returns:

a populated entry object containing enough information to facilitate the function it is required for; if none is found

putInCache

void putInCache(Object key,
                V entry)

Places an entry in the cache. The key is the identifier used to subsequently retrieve the entry.

Important: Note that you may use any well known java type as key like Long or String or a custom type as long as it abides by the contract defined by the Key interface, i.e., the key should be uniquely identifiable using its value and not the Key instance as whole. In short, you must override the Object.equals(Object) and Object.hashCode() methods of that particular key type to make sure your identifier can be uniquely distinguished from with-in the cache.

Parameters:

key - the key corresponding to which entry must be stored in the cache

entry - the object entry to place into the cache

evictFromCache

void evictFromCache(Object key)

Removes the specified entry from the cache. The key is the identifier used to remove the entry. If the entry is not found, the method should simply return (not throw an exception).

Some cache implementations may not support eviction from the cache, in which case they should provide appropriate behavior to alter the token in either its documentation, via an exception, or through a log message.

Important: Note that you may use any well known java type as key like Long or String or a custom type as long as it abides by the contract defined by the Key interface, i.e., the key should be uniquely identifiable using its value and not the Key instance as whole. In short, you must override the Object.equals(Object) and Object.hashCode() methods of that particular key type to make sure your identifier can be uniquely distinguished from with-in the cache.

Parameters:

key - the predefined key/identifier for evicting an entry from the cache

isPresentInCache

boolean isPresentInCache(Object key)

Checks the application cache on which the method is called for the specified key and returns true if the condition is true, else false.

Important: Note that you may use any well known java type as key like Long or String or a custom type as long as it abides by the contract defined by the Key interface, i.e., the key should be uniquely identifiable using its value and not the Key instance as whole. In short, you must override the Object.equals(Object) and Object.hashCode() methods of that particular key type to make sure your identifier can be uniquely distinguished from with-in the cache.

Parameters:

key - the key to be tested for presence in the cache

Returns:

true if the key exists, else false (an exception must never be thrown)

flush

void flush()