org.jboss.as.ejb3.cache.spi

Interface BackingCache<K extends Serializable,V extends Cacheable<K>,E extends BackingCacheEntry<K,V>>

All Superinterfaces:

AffinitySupport<K>, Removable<K>

All Known Subinterfaces:

GroupAwareBackingCache<K,V,G,M>, PassivatingBackingCache<K,V,E>

All Known Implementing Classes:

AbstractBackingCache, GroupAwareBackingCacheImpl, NonPassivatingBackingCacheImpl, PassivatingBackingCacheImpl

public interface BackingCache<K extends Serializable,V extends Cacheable<K>,E extends BackingCacheEntry<K,V>>
extends Removable<K>, AffinitySupport<K>

An internal cache to which an external-facing Cache delegates, either directly or indirectly.

There are two key distinctions between a BackingCache and the external-facing Cache:

1. A Cache directly handles external classes that implement the limited Cacheable interface. CacheItem is deliberately limited to avoid placing a implementation burden on external classes. A BackingCache works with instances of the more expressive internal interface BackingCacheEntry, and thus can directly implement more complex functionality.
2. A BackingCache does not attempt to control concurrent client access to its cached BackingCacheEntry instances, beyond the simple act of marking the entries as being in or out of use. It assumes the external-facing Cache is preventing concurrent access to a given entry and is properly coordinating calls to the backing cache.

Author:

Brian Stansberry, Paul Ferraro

Method Summary

Methods

Modifier and Type	Method and Description
void	addLifecycleListener(BackingCacheLifecycleListener listener) Registers a listener for callbacks when the cache starts and stops.
E	create() Creates and caches a new instance of C, wrapped by a new T.
void	discard(K key) Discard the specified object from cache.
E	get(K key) Get the specified object from cache.
boolean	isClustered() Gets whether this cache supports clustering functionality.
E	peek(K key) Peek at an object which might be in use.
E	release(K key) Release the object from use.
void	removeLifecycleListener(BackingCacheLifecycleListener listener) Removes a registered lifecycle listener.
void	start() Start the cache.
void	stop() Stop the cache.

Methods inherited from interface org.jboss.as.ejb3.cache.Removable

remove

Methods inherited from interface org.jboss.as.ejb3.cache.AffinitySupport

getStrictAffinity, getWeakAffinity, hasAffinity

Method Detail

create

E create()

Creates and caches a new instance of C, wrapped by a new T. The new T *is* returned, but is not regarded as being "in use". Callers *must not* attempt to use the underlying C without first calling #get(Object).

Returns:

the new T

get

E get(K key)
                                     throws javax.ejb.NoSuchEJBException

Get the specified object from cache. This will mark the entry as being in use.

Parameters:

key - the identifier of the object

Returns:

the object

Throws:

javax.ejb.NoSuchEJBException - if the object does not exist

peek

E peek(K key)
                                      throws javax.ejb.NoSuchEJBException

Peek at an object which might be in use. Does not change the status of the item in terms of whether it is in use.

Parameters:

key - the identifier of the object

Returns:

the object

Throws:

javax.ejb.NoSuchEJBException - if the object does not exist

release

E release(K key)

Release the object from use.

Parameters:

key - the identifier of the object

Returns:

the entry that was released

discard

void discard(K key)

Discard the specified object from cache.

Parameters:

key - the identifier of the object

start

void start()

Start the cache.

stop

void stop()

Stop the cache.

isClustered

boolean isClustered()

Gets whether this cache supports clustering functionality.

Returns:

true if clustering is supported, false otherwise

addLifecycleListener

void addLifecycleListener(BackingCacheLifecycleListener listener)

Registers a listener for callbacks when the cache starts and stops.

Parameters:

listener - the listener. Cannot be null.

removeLifecycleListener

void removeLifecycleListener(BackingCacheLifecycleListener listener)

Removes a registered lifecycle listener.

Parameters:

listener - the listener. Cannot be null.