Interface CacheManager
-
- All Known Implementing Classes:
ConcurrentCache
public interface CacheManager
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
ageOut()
Age as many objects as possible out of the cache.void
clean(Matchable partialKey)
Clean all objects that match the partialKey (or exact key).void
cleanAll()
Place all objects in their clean state by calling their clean method if they are dirty.Cacheable
create(java.lang.Object key, java.lang.Object createParameter)
Create an object in the cache.void
deregisterMBean()
Deregister the MBean that monitors this cache.boolean
discard(Matchable partialKey)
Discard all objects that match the partialKey (or exact key).Cacheable
find(java.lang.Object key)
Find an object in the cache.Cacheable
findCached(java.lang.Object key)
Find an object in the cache.void
registerMBean(java.lang.String dbName)
Register an MBean that allows user to monitor this cache instance.void
release(Cacheable entry)
Release aCacheable
object previously found withfind()
orfindCached()
, or created withcreate()
, and which is still kept by the caller.void
remove(Cacheable entry)
Delete and remove an object from the cache.void
shutdown()
Shutdown the cache.void
useDaemonService(DaemonService daemon)
This cache can use this DaemonService if it needs some work to be done in the background.java.util.Collection
values()
Return a Collection of the Cacheables currently in the cache.
-
-
-
Method Detail
-
find
Cacheable find(java.lang.Object key) throws StandardException
Find an object in the cache.Find an object in the cache that matches the key provided using the equals() method, i.e. the return Cacheable will have getIdentifier.equals(key) true. If the object does not exist in the cache it will be added by one of:
- creating a new holder object and calling its initParameter() method and then its setIdentity() method with key as the parameter.
- Calling clearIdentity() on an holder object in the clean state and then calling its setIdentity() method with key as the parameter.
- Calling clean() on a dirty holder object and then calling clearIdentity() on an holder object in the clean state and then calling its setIdentity() method with key as the parameter.
The returned object is kept, i.e. its identity will not change, until the release() method is called. The release() method must be called after the caller is finished with the object and throw away the reference to it, e.g.Page p = (Page) pageCache.find(pageKey); // do stuff with p // release p pageCache.release(p); p = null;
- Returns:
- A reference to an object in the cache, or null if the object cannot be found.
- Throws:
StandardException
- Standard Derby error policy.- See Also:
Cacheable.setIdentity(java.lang.Object)
-
findCached
Cacheable findCached(java.lang.Object key) throws StandardException
Find an object in the cache.Find an object in the cache that matches the key provided using the equals() method, i.e. the return Cacheable will have getIdentifier.equals(key) true. If a matching object does not exist in the cache, null is returned.
The returned object is kept, i.e. its identity will not change, until the release() method is called. The release() method must be called after the caller is finished with the object and throw away the reference to it, e.g.Page p = (Page) pageCache.findCached(pageKey); if (p != null) { // do stuff with p // release p pageCache.release(p); p = null; }
- Throws:
StandardException
- Standard Derby error policy.
-
create
Cacheable create(java.lang.Object key, java.lang.Object createParameter) throws StandardException
Create an object in the cache. The resulting object will match the key provided using the equals() method, i.e. the return Cacheable will have getIdentifier.equals(key) true. If an object that matches the key already exists in the cache then an exception is thrown.
The object will be added by one of:- creating a new holder object and calling its initParameter() method and then its createIdentity() method with key as the parameter.
- Calling clearIdentity() on an holder object in the clean state and then calling its createIdentity() method with key as the parameter.
- Calling clean() on a dirty holder object and then calling clearIdentity() on an holder object in the clean state and then calling its createIdentity() method with key as the parameter.
The returned object is kept, i.e. its identity will not change, until the release() method is called. The release() method must be called after the caller is finished with the object and throw away the reference to it, e.g.Page p = (Page) pageCache.create(pageKey, createType); // do stuff with p // release p pageCache.release(p); p = null;
- Returns:
- A reference to an object in the cache.
- Throws:
StandardException
- Standard Derby error policy.- See Also:
Cacheable.createIdentity(java.lang.Object, java.lang.Object)
-
release
void release(Cacheable entry)
Release aCacheable
object previously found withfind()
orfindCached()
, or created withcreate()
, and which is still kept by the caller. After this call the caller must throw away the reference to item.- Parameters:
entry
- the cached object to release
-
remove
void remove(Cacheable entry) throws StandardException
Delete and remove an object from the cache. It is up to the user of the cache to provide synchronization of some form that ensures that only one caller executes remove() on a cached object.
The object must previously have been found withfind()
orfindCached()
, or created withcreate()
, and it must still be kept by the caller. The item will be placed into the NoIdentity state through clean(true) (if required) and clearIdentity(). The removal of the object will be delayed until it is not kept by anyone. Objects that are in the to be removed state can still be found through find() and findCached() until their keep count drops to zero. This call waits until the object has been removed.
After this call the caller must throw away the reference to item.- Parameters:
entry
- the object to remove from the cache- Throws:
StandardException
- Standard Derby error policy.
-
cleanAll
void cleanAll() throws StandardException
Place all objects in their clean state by calling their clean method if they are dirty. This method guarantees that all objects that existed in the cache at the time of the call are placed in the clean state sometime during this call. Objects that are added to the cache during this call or objects that are dirtied during this call (by other callers) are not guaranteed to be clean once this call returns.- Throws:
StandardException
- Standard Derby error policy.- See Also:
Cacheable.clean(boolean)
,Cacheable.isDirty()
-
clean
void clean(Matchable partialKey) throws StandardException
Clean all objects that match the partialKey (or exact key). Any cached object that results in the partialKey.equals(Object) method returning true when passed the cached object will be cleaned.In order to clean more than one object the Cacheable equals method must be able to handle a partial key, e.g. a page has PageKey but a clean may pass a ContainerKey which will discard all pages in that container.
- Throws:
StandardException
- Standard Derby error policy.
-
ageOut
void ageOut()
Age as many objects as possible out of the cache. This call is guaranteed not to block. It is not guaranteed to leave the cache empty.
It is guaranteed that all unkept, clean objects will be removed from the cache.
-
shutdown
void shutdown() throws StandardException
Shutdown the cache. This call stops the cache returning any more valid references on afind()
,findCached()
orcreate()
call, and then cleanAll() and ageOut() are called. The cache remains in existence until the last kept object has been unkept.- Throws:
StandardException
- Standard Derby error policy.
-
useDaemonService
void useDaemonService(DaemonService daemon)
This cache can use this DaemonService if it needs some work to be done in the background. The caller must ensure that it has exclusive access to the cache when this method is called. No synchronization is required in the implementations of this method.
-
discard
boolean discard(Matchable partialKey)
Discard all objects that match the partialKey (or exact key). Any cached object that results in the partialKey.equals(Object) method returning true when passed the cached object will be thrown out of the cache if and only if it is not in use. The Cacheable will be discarded without its clean method being called.If partialKey is null, it matches all objects. This is a way to discard all objects from the cache in case of emergency shutdown.
In order to discard more than one object the Cacheable equals method must be able to handle a partial key, e.g. a page has PageKey but a discard may pass a ContainerKey which will discard all pages in that container.
- Returns:
- true if discard has successful gotten rid of all objects that match the partial or exact key. False if some objects that matches were not gotten rid of because it was kept.
-
values
java.util.Collection values()
Return a Collection of the Cacheables currently in the cache. The Collection should be a copy so that external synchronization isn't required.This method should only be used for diagnostic purposes.
- Returns:
- a Collection of all the elements in the cache
-
registerMBean
void registerMBean(java.lang.String dbName) throws StandardException
Register an MBean that allows user to monitor this cache instance. This is a no-op if the platform does not support Java Management Extensions (JMX).
The MBean will be automatically deregistered when
shutdown()
is called, or it can be manually deregistered by callingderegisterMBean()
.- Parameters:
dbName
- the unique name of the database to which the cache belongs- Throws:
StandardException
- if an error occurs when registering the MBean
-
deregisterMBean
void deregisterMBean()
Deregister the MBean that monitors this cache. If there is no MBean for this instance, this is a no-op.
-
-