org.fjank.jcache
Class CacheAccessImpl2

java.lang.Object
  org.fjank.jcache.CacheAccessImpl2

public final class CacheAccessImpl2
extends Object

An optimized implementation of CacheAccess. No exceptions is thrown excpet in really exceptional situations. The Map interface uses this class directly, while the old CacheAccessImpl interface should be reprogrammed to work with this class.

Method Summary

void	cancelResponse() terminates the request for a reply from the previous invalidate or update.
void	close() will return the CacheAccess object to the cache.
void	defineGroup(String name) Is used to create a new group object.
void	defineGroup(String name, Attributes attributes) Is used to create a new group object.
void	defineGroup(String name, String group) Is used to create a new group which belongs to another group.
void	defineGroup(String name, String groupName, Attributes attributes) Is used to create a new group which belongs to another group.
void	defineObject(Object name, Attributes attributes) is used to specify the attributes to associate with an object when it is loaded.
void	defineObject(Object name, String group, Attributes attributes) See defineObject(Object, Attributes)
void	destroy() Will invalidate all objects within the region for this CacheAccess object, and the region itself.
void	destroy(Object name) Will invalidate all objects in the named region and the named region.
Object	get(Object name) Returns a reference to the object accosiated with the specified name.
Object	get(Object name, Object arguments) Gets the object from the cache.
Object	get(Object name, String group, Object arguments) Gets the object from the specified group.
Attributes	getAttributes() Will return an attribute object describing the current attributes associated for the region for this CacheAccess.
Attributes	getAttributes(Object name) will return an attribute object describing the current attributes associated with the object name.
CacheException	getException(boolean cached) Will return the last exception which occured.
boolean	getOwnership(Object name, int timeout) will claim ownership for the named object for this instance of CacheAccess.
CacheRegion	getRegion() Gets the region this access applies to.
void	invalidate() Will mark all objects in the region as invalid.
void	invalidate(Object name) Will mark all objects withing the scope of the specified name as invalid.
boolean	isPresent(Object name) Check the existence of a valid copy of the named object in the region associated with this CacheAccess object.
void	preLoad(Object name) This method allows for asynchronous loading of object into the cache.
void	preLoad(Object name, Object arguments) See preLoad(Object).
void	preLoad(Object name, String group, Object arguments) See preLoad(Object).
void	put(Object name, Attributes attributes, Object object) See put(Object, Object)
boolean	put(Object name, Object object) inserts the specified object into the cache, and associates it with the specified name.
void	put(Object name, String group, Attributes attributes, Object object) See put(Object, Object)
void	put(Object name, String group, Object object) See put(Object, Object)
void	releaseOwnership() Is called to explicitly give up ownership for an object.
Object	replace(Object name, Object object) Will create a new version of the object indentified by the name, replacing the current version with the object specified.
Object	replace(Object name, String group, Object object) See replace(Object, Object)
Object	replaceWithoutDistribution(Object name, Object object)
Object	replaceWithoutDistribution(Object name, String group, Object object)
void	resetAttributes(Attributes attributes) allows for some attributes of a region to be reset.
void	resetAttributes(Object name, Attributes attributes) See resetAttributes(Attributes).
void	save() Will cause all objects within the region of this CacheAccess to be saved to the disk cache.
void	save(Object name) See save().
void	waitForResponse(int timeout) May be used to wait for replies returned from invalidates or updates when a reply is requested.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

cancelResponse

public void cancelResponse()

terminates the request for a reply from the previous invalidate or update. If a response was requested, the either cancelResponse or waitForResponse should be called to terminate the request and free up related structures. If the waitForResponse method times out, cancelResponse should be called. All response associated with the CacheAccess object are canceled. If the object is local or a reply has not been requested, this call returns immediantely.

close

public void close()

will return the CacheAccess object to the cache. Any attempt to use a CacheAccess object after it has been closed will be ignored.

defineGroup

public void defineGroup(String name)

Is used to create a new group object. The attributes of the region or group the new group is associated with are used.

Parameters:

name - the name of the new group.

defineGroup

public void defineGroup(String name,
                        Attributes attributes)

Is used to create a new group object. The attrbutes-parameter are used as the attributes for the new group.

Parameters:

name - the group the new group should be associated with.

attributes - the attributes of the new group.

defineGroup

public void defineGroup(String name,
                        String group)

Is used to create a new group which belongs to another group. The attributes of the group the new group is attached to are used as the attrbutes for the new group.

Parameters:

name - the name of the new group.

group - the group the new group should be associated with.

defineGroup

public void defineGroup(String name,
                        String groupName,
                        Attributes attributes)

Is used to create a new group which belongs to another group. The attrbutes-parameter are used as the attributes for the new group.

Parameters:

name - the name of the new group.

groupName - the group the new group should be associated with.

attributes - the attributes of the new group.

defineObject

public void defineObject(Object name,
                         Attributes attributes)

is used to specify the attributes to associate with an object when it is loaded. This can include the loader object, cache event handlers, and spesific attributes for the object such as distribute, spool, etc. Attributes (with the exception of the CacheLoader object itself) can also be specified within the load method of the CacheLoader object using the setAttributes method, if the attributes for an object are not defined, the attributes of the region will be used.

Parameters:

name - the name of the object to associate the attributes with.

attributes - the attributes to associate.

defineObject

public void defineObject(Object name,
                         String group,
                         Attributes attributes)

See defineObject(Object, Attributes)

Parameters:

name - the name of the object to associate the attributes with.

group - the group the object to associate the attributes with is contained in.

attributes - the attributes to associate.

destroy

public void destroy()

Will invalidate all objects within the region for this CacheAccess object, and the region itself. All references to the objects and any loaders registered will be destroyed. This object is unusable after this operation, will be closed and returned to the cache pool.

destroy

public void destroy(Object name)

Will invalidate all objects in the named region and the named region.

Parameters:

name - the name of the region to destroy.

See Also:

destroy()

get

public Object get(Object name)

Returns a reference to the object accosiated with the specified name. If the object is a streamAccess object, an InputStreamis returned, if the object is a disk object, a String containg the full path to the object is returned. The name parameter must override the Object.equals(Object)and Object.hashCode() methods. If a loader object has not been registered for the object the default load method will do a netSearch for the object. A CacheAccess will only maintain a reference to one cached object at any gived time. If get is called multiple times, the object accessed previously, will be released.

Parameters:

name - the name of the object to get.

Returns:

a reference to a shared object. Will always return the latest version of the object.

get

public Object get(Object name,
                  Object arguments)

Gets the object from the cache. If the object is not currently in the cache and a loader object has been registered, the object will be loaded into the cache with the arguments specified.

Parameters:

name - the name of the object to get.

arguments - the arguments wich is passed to the load method of the CacheLoader, if registered.

Returns:

a reference to a shared object. Will always return the latest version of the object.

See Also:

get(Object)

get

public Object get(Object name,
                  String group,
                  Object arguments)

Gets the object from the specified group. If the object is not currently in the cache, and a loader object has been registered, the object will be loaded into the cache and accosiated with the specified group.

Parameters:

name - the name of the object to get.

group - The group the Object is associated with.

arguments - the arguments wich is passed to the load method of the CacheLoader, if registered.

Returns:

a reference to a shared object. Will always return the latest version of the object.

See Also:

get(Object)

getAttributes

public Attributes getAttributes()

Will return an attribute object describing the current attributes associated for the region for this CacheAccess.

Returns:

an Attributes object for the region of this CacheAccess.

getAttributes

public Attributes getAttributes(Object name)

will return an attribute object describing the current attributes associated with the object name.

Parameters:

name - the name of the object to get the attributes for.

Returns:

an Attributes object for the named object.

getOwnership

public boolean getOwnership(Object name,
                            int timeout)

will claim ownership for the named object for this instance of CacheAccess. If ownership is not available, this method will block for the specified timeout. The local cache is checked first, if the local cache does not hold ownership of the object, a message is sent to all other caches in the system. Ownership is only relevant for synchronized objects. Ownership is maintained until an update or invalidation completes (this includes the reciept of replies when applicable) or until ownership is explicitly released with a call to releaseOwnership(). An instance of CacheAccess con only hold ownership of one object at a time. Ownership only applies to individual objects, it is not available on groups.

Parameters:

name - the name of the object to claim ownership for.

timeout - number of milliseconds to wait for the ownership claim.

Returns:

true if ownership was obtained, false otherwise.

invalidate

public void invalidate()

Will mark all objects in the region as invalid.

invalidate

public void invalidate(Object name)

Will mark all objects withing the scope of the specified name as invalid. If the name refers to a group object, the invalidate will cascade to all objects associated with the group or any subgroups. Invalidate does not "unregister" an object. The loader object will remain associated with the object name. To completely remove any knowledge of an object from the cache, destroy must be called.

Parameters:

name - the name of the object to invalidate.

isPresent

public boolean isPresent(Object name)

Check the existence of a valid copy of the named object in the region associated with this CacheAccess object.

Parameters:

name - the name of the object to check the existence for.

Returns:

true if a valid copy was found, false otherwise.

preLoad

public void preLoad(Object name)

This method allows for asynchronous loading of object into the cache. This method will schedule a background task to the registered load method, then return. Any exception that occur during the load, will be written to the log, if logging is on and a log is available.

Parameters:

name - the name of the object to load.

preLoad

public void preLoad(Object name,
                    Object arguments)

See preLoad(Object).

Parameters:

name - the name of the object to load.

arguments - these arguments will be passed to the load method of the loader object.

preLoad

public void preLoad(Object name,
                    String group,
                    Object arguments)

See preLoad(Object).

Parameters:

name - the name of the object to load.

group - the group the new object will be associated with.

arguments - these arguments will be passed to the load method of the loader object.

put

public void put(Object name,
                Attributes attributes,
                Object object)

See put(Object, Object)

Parameters:

name - the name associated with the object.

attributes - the attributes to associate with the object put into the cache,

object - the object wich is put in the cache.

See Also:

put(Object,Object)

put

public void put(Object name,
                String group,
                Attributes attributes,
                Object object)

See put(Object, Object)

Parameters:

name - the name associated with the object.

group - The group associated with the object.

attributes - the attributes to associate with the object put into the cache,

object - the object wich is put in the cache.

See Also:

put(Object,Object)

getException

public CacheException getException(boolean cached)

Will return the last exception which occured. If no exception has occured, this will return null.

Parameters:

cached - if true, a cached exception is returned. The stacktrace of this exception will not be correct. Otherwise a new CacheException will be created. if you use false as the cache parameter, be adviced that this will be detrimental for performance.

Returns:

the last CacheException which occured.

put

public boolean put(Object name,
                   Object object)

inserts the specified object into the cache, and associates it with the specified name. Names are scoped to a region, so they must be unique within the region they are placed. This method is intended for very simple caching situations. In general it is better to create a CacheLoader object and allow the cache to manage the creation and loading of objects. Default attributes are assumed.

Parameters:

name - the name associated with the object.

object - the object wich is put in the cache.

put

public void put(Object name,
                String group,
                Object object)

See put(Object, Object)

Parameters:

name - the name associated with the object.

group - The group associated with the object.

object - the object wich is put in the cache.

See Also:

put(Object, Object)

releaseOwnership

public void releaseOwnership()

Is called to explicitly give up ownership for an object. Ownership is only relevant for synchronized objects. If ownership is not held, releaseOwnership is ignored.

replace

public Object replace(Object name,
                      Object object)

Will create a new version of the object indentified by the name, replacing the current version with the object specified. If the object doesn't exist in the cache, replace is equivalent to a put. The attributes will be inherited from the existing object or if no object exists, from the group or region the object associated with. Names are in the scope of a region so they must be unique within the region they are placed. This method is not valid on a disk, StreamAccess or Group Object.

Parameters:

name - the name of the object to replace.

object - The new object to be put in the cache.

Returns:

a reference to the newly replaced object.

replaceWithoutDistribution

public Object replaceWithoutDistribution(Object name,
                                         Object object)

replace

public Object replace(Object name,
                      String group,
                      Object object)

See replace(Object, Object)

Parameters:

name - the name of the object to replace.

group - the group the object is associated with.

object - The new object to be put in the cache.

Returns:

a reference to the newly replaced object.

replaceWithoutDistribution

public Object replaceWithoutDistribution(Object name,
                                         String group,
                                         Object object)

resetAttributes

public void resetAttributes(Attributes attributes)

allows for some attributes of a region to be reset. The attributes are expiration time attributes, time to live, default time to live, idle time and event handlers. The cacheloader and attributes explicitly set can't be reset with this method. To do this the object must be destroyed and redefined change those parameters. Changing the default settings on groups and regions will not affect existing objects. Only objects loaded after the reset will use the new defaults.

Parameters:

attributes - The new attributes to append to the region.

resetAttributes

public void resetAttributes(Object name,
                            Attributes attributes)

See resetAttributes(Attributes).

Parameters:

name - the name of the region to reset the attributes for.

attributes - the new attributes for the named region.

save

public void save()

Will cause all objects within the region of this CacheAccess to be saved to the disk cache. All exceptions encountered will be logged if logging is on. Local objects will be saved in the process specific cache, distributed objects will be saved in the machine global disk cache.

save

public void save(Object name)

See save(). If the name refers to a specific object and that object does not implement the Serializableinterface, a CacheExceptionwill be logged. If the name referenced a group or a region, all objects not implementing Serializableis ignored.

Parameters:

name - the name of the object to save.

waitForResponse

public void waitForResponse(int timeout)

May be used to wait for replies returned from invalidates or updates when a reply is requested. This method will block the calling thread until all the responses associated with the CacheAccess object have been retrieved or the time indicated in the timeout variable has expired. If this method times out and the caller does not intend to call waitForResponse again on this object, cancelResponse should be called. If the object is local or a reply has not been requested, this call return immediately.

Parameters:

timeout - the maximum number of milliseconds to wait for remote caches to reply.

getRegion

public CacheRegion getRegion()

Gets the region this access applies to.

Returns:

the region this access applies to.