oracle.ias.cache
Class CacheAccess

java.lang.Object
  |
  +--oracle.ias.cache.CacheAccess

public class CacheAccess

extends java.lang.Object

CacheAccess provides a public API to access the cache. The CacheAccess object is associated with a region and can be used to access any object in that region. CacheAccess is not thread safe, which means if multiple threads are going to access the cache concurrently, each thread should instantiate its own CacheAccess instance.

Since:

2.0.0

Method Summary

Type	Method
void	cancelResponse() terminates the request for a reply from the previous invalidate or update.
void	close() releases the resource used by current CacheAccess object.
void	createPool(java.lang.String name, PoolInstanceFactory factory, Attributes attr, int min, int max) creates an object pool containing at least min instances of the object created by calling factory.createInstance().
void	createPool(java.lang.String name, java.lang.String group, PoolInstanceFactory factory, Attributes attr, int min, int max) creates an object pool containing at least min instances of the object created by calling factory.createInstance().
void	defineGroup(java.lang.String name) is used to create a new group within the context of the region referred to the CacheAccess object.
void	defineGroup(java.lang.String name, Attributes attr) is used to create a new group within the context of the region referred to the CacheAccess object.
void	defineGroup(java.lang.String name, java.lang.String group) is used to create a new group within the context of the region referred to the CacheAccess object and associated with the group specified.
void	defineGroup(java.lang.String name, java.lang.String group, Attributes attr) is used to create a new group within the context of the region referred to the CacheAccess object and associated with the group specified.
void	defineObject(java.lang.Object name, Attributes attr) is used to specify the attributes to associate with an object when it is loaded.
void	defineObject(java.lang.Object name, java.lang.String group, Attributes attr) is used to specify the attributes to associate with an object when it is loaded.
static void	defineRegion(java.lang.String region) creates a named region within the cache.
static void	defineRegion(java.lang.String region, Attributes attr) creates a named region within the cache.
void	defineSubRegion(java.lang.String name) is used to define a new subRegion within the context of the region referred to the CacheAccess object.
void	defineSubRegion(java.lang.String name, Attributes attr) is used to define a new subRegion within the context of the region referred to the CacheAccess object.
void	destroy() destroys all objects associated with the current region including the region.
void	destroy(java.lang.Object name) invalidates all objects associated with name, removing all references to the objects from the cache.
void	disable() invalidates all the objects in the region and marks all the groups in the region and the region itself as DISABLED.
void	disable(java.lang.Object name) invalidates all the objects within the scope of the name and marks all the groups, regions and subregions within the scope of the name as DISABLED.
void	enable() Re-enables the current region, including all the cache objects, groups and subregions in the region.
void	enable(java.lang.Object name) re-enables the objects, groups, and subregions within the scope of the name.
java.lang.Object	get(java.lang.Object name) returns a reference to the object associated with name.
java.lang.Object	get(java.lang.Object name, java.lang.Object args) returns a reference to the object associated with name.
java.lang.Object	get(java.lang.Object name, java.lang.String group, java.lang.Object args) returns a reference to the object associated with name.
static CacheAccess	getAccess() is a static method that returns a CacheAccess object to the default region.
static CacheAccess	getAccess(java.lang.String region) is a static method that returns a CacheAccess object allowing access to the specified cache region.
static CacheAccess	getAccess(java.lang.String region, boolean checkRegion) is a static method that returns a CacheAccess object allowing access to the specified cache region.
Attributes	getAttributes() returns an attribute object describing the current region.
Attributes	getAttributes(java.lang.Object name) returns an attribute object describing the current attributes associated with the object name (can be a group).
static java.lang.String	getDefRegionName() returns the name of the default Region.
java.lang.Object	getOwnership(int timeout) claims the ownership of the region, if the region has been defined as "SYNCHRONIZE".
java.lang.Object	getOwnership(java.lang.Object name, int timeout) claims the ownership of the object with specified name for this CacheAccess instance, if the object has been defined as "SYNCHRONIZE".
java.lang.Object	getOwnership(java.lang.Object name, java.lang.String group, int timeout) claims the ownership of the object with specified name for this CacheAccess instance, if the object has been defined as "SYNCHRONIZE".
java.lang.String	getParent() returns the name of the parent region if any.
PoolAccess	getPool(java.lang.String name) returns a PoolAccess object associated with the object name.
java.lang.String	getRegionName() returns the name of the current region of the CacheAccess object.
CacheAccess	getSubRegion(java.lang.String name) getSubRegion will return a CacheAccess object associated with the named subRegion.
void	invalidate() marks all objects within the region as invalid.
void	invalidate(java.lang.Object name) marks all objects within the scope of name as invalid.
boolean	isDisabled() returns a boolean to indicate if the region, which this cache access is referencing, is disabled or not.
boolean	isDisabled(java.lang.Object name) returns a boolean to indicate if the cache entity (region, group or object) identified by Object "name" is disabled.
boolean	isPresent(java.lang.Object name) returns true if the named object currently exists in the cache false otherwise.
java.lang.Object[]	listNames() returns a list of the names of all objects in this region This list is only the names of the objects, it doesn't obtain a reference to the object.
java.util.Enumeration	listObjects() returns an Enumeration that will allow access to the objects in the region.
java.lang.String[]	listRegions() returns an array of all subRegions in this region The list contains only the subRegions in the region itself, it does not contain subRegions in subRegions of the region.
void	preLoad(java.lang.Object name) allows for asynchronous loading of objects into the cache.
void	preLoad(java.lang.Object name, java.lang.Object args) allows for asynchronous loading of objects into the cache.
void	preLoad(java.lang.Object name, java.lang.String group, java.lang.Object args) allows for asynchronous loading of objects into the cache.
void	put(java.lang.Object name, Attributes attr, java.lang.Object obj) allows a new object to be placed into the cache identified by name.
void	put(java.lang.Object name, java.lang.Object obj) allows a new object to be placed into the cache identified by name.
void	put(java.lang.Object name, java.lang.String group, java.lang.Object obj) allows a new object to be placed into the cache identified by name.
void	put(java.lang.Object name, java.lang.String group, java.lang.Object obj, Attributes attr) allows a new object to be placed into the cache identified by name.
void	releaseOwnership(int timeout) is used to explicitly give up ownership of the region.
void	releaseOwnership(java.lang.Object name, int timeout) is used to explicitly give up ownership of the named object.
java.lang.Object	replace(java.lang.Object name, java.lang.Object obj) creates a new version of the object identified by name, replacing the current version with the object obj.
java.lang.Object	replace(java.lang.Object name, java.lang.String group, java.lang.Object obj) creates a new version of the object identified by name, replacing the current version with the object obj.
void	resetAttributes(Attributes attr) allows for some of the attributes of a region to be reset, in particular: expiration time, time to live, default time to live, idle time, and event handlers.
void	resetAttributes(java.lang.Object name, Attributes attr) allows for some of the attributes of the named object to be reset, in particular: expiration time, time to live, default time to live, idle time, and event handlers.
void	save() causes all the objects within the scope of region to be saved to the disk cache.
void	save(java.lang.Object objname) causes all the objects within the scope of name to be saved to the disk cache.
void	waitForResponse(int timeout) is 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

defineRegion

public static void defineRegion(java.lang.String region,
                                Attributes attr)
                         throws CacheNotAvailableException,
                                NullObjectNameException,
                                ObjectExistsException,
                                CacheException

creates a named region within the cache. This defines the name space for storing objects. Region names must be globally unique. This would typically be the application name. If the cache system has not been initialized, it will be initialized using the Cache attributes defined in the properties file javacache.properties. If the properties file is not found, default values will be used. Once a region is created, you may call getAccess(region) to obtain an instance of a CacheAccess object to access the region.

Parameters:

region - The name of a region. It must be globally unique.

attr - Default Attributes of the region. This parameter can be null, if not setting any attributes to a region.

Throws:

ObjectExistsException - if the specified region already exists.

NullObjectNameException - if the region name is null.

CacheNotAvailableException - if it cannot initialize the Cache Service.

Since:

2.0.0

See Also:

getAccess, Attributes, CacheAttributes

defineRegion

public static void defineRegion(java.lang.String region)
                         throws CacheNotAvailableException,
                                NullObjectNameException,
                                ObjectExistsException,
                                CacheException

creates a named region within the cache. This defines the name space for storing objects. Region names must be globally unique. This would typically be the application name. If the cache system has not been initialized, it will be initialized using the Cache attributes defined in the properties file javacache.properties. If the properties file is not found, default values will be used. Once a region is created, you may call getAccess(region) to obtain an instance of a CacheAccess object to access the region.

Parameters:

region - The name of a region. It must be globally unique.

Throws:

ObjectExistsException - if the specified region already exists.

NullObjectNameException - if the region name is null.

CacheNotAvailableException - if it cannot initialize the Cache Service.

Since:

2.0.0

See Also:

getAccess, Attributes, CacheAttributes

getAccess

public static CacheAccess getAccess()
                             throws CacheException

is a static method that returns a CacheAccess object to the default region. When the CacheAccess object is no longer needed, close() must be called to release the resource used by current CacheAccess object.

Returns:

An instance of CacheAccess object. This object is not thread- safe.

Throws:

CacheNotAvailableException - is thrown if the Cache Service cannot be initialized.

Since:

2.0.0

See Also:

getAccess, defineRegion, close

getAccess

public static CacheAccess getAccess(java.lang.String region)
                             throws CacheNotAvailableException

is a static method that returns a CacheAccess object allowing access to the specified cache region. When the CacheAccess object is no longer needed, close() must be called to release the resource used by current CacheAccess object.

Parameters:

region - Name of an existing region. Call defineRegion to create a region first.

Returns:

An instance of CacheAccess object. This object is not thread- safe.

Throws:

CacheNotAvailableException - is thrown if the Cache Service cannot be initialized.

Since:

2.0.0

See Also:

getAccess, defineRegion, close

getAccess

public static CacheAccess getAccess(java.lang.String region,
                                    boolean checkRegion)
                             throws CacheNotAvailableException,
                                    RegionNotFoundException,
                                    CacheException

is a static method that returns a CacheAccess object allowing access to the specified cache region. When the CacheAccess object is no longer needed, close() must be called to release the resource used by current CacheAccess object.

Parameters:

region - Name of an existing region. Call defineRegion to create a region first.

checkRegion - Set TRUE for checking the existance of the specified region. If this flag is set as TRUE and the region does not exist, a RegionNotFoundException will be thrown.

Returns:

An instance of CacheAccess object. This object is not thread- safe.

Throws:

CacheNotAvailableException - is thrown if the Cache Service cannot be initialized.

RegionNotFoundException - is thrown if the region does not exist and checkRegion is TRUE.

Since:

2.0.0

See Also:

getAccess, defineRegion, close

defineObject

public void defineObject(java.lang.Object name,
                         Attributes attr)
                  throws CacheException

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 specific 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 - Name of a object to be defined

group - Name of a parent group where the new object belongs to.

attr - Attributes of the object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

Attributes, setAttributes, defineGroup

defineObject

public void defineObject(java.lang.Object name,
                         java.lang.String group,
                         Attributes attr)
                  throws CacheException

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 specific 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 group will be used.

Parameters:

name - Name of a object to be defined

group - Name of a parent group where the new object belongs to.

attr - Attributes of the object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

Attributes, setAttributes, defineGroup

resetAttributes

public void resetAttributes(Attributes attr)
                     throws CacheException,
                            InvalidHandleException

allows for some of the attributes of a region to be reset, in particular: expiration time, time to live, default time to live, idle time, and event handlers. The cache loader object and attributes set as flags can't be reset with resetAttributes, the object must be destroyed and redefined to change those parameters. Changing default setting will not affect existing objects. Only object loaded after the reset will use the new defaults.

Parameters:

attr - Attributes of the object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

Attributes, setAttributes, defineGroup

resetAttributes

public void resetAttributes(java.lang.Object name,
                            Attributes attr)
                     throws CacheException,
                            InvalidHandleException

allows for some of the attributes of the named object to be reset, in particular: expiration time, time to live, default time to live, idle time, and event handlers. The cache loader object and attributes set as flags can't be reset with resetAttributes, the object must be destroyed and redefined to change those parameters. Changing default setting will not affect existing objects. Only object loaded after the reset will use the new defaults.

Parameters:

name - Name of a object to be defined

attr - Attributes of the object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

Attributes, setAttributes, defineGroup

get

public java.lang.Object get(java.lang.Object name)
                     throws ObjectNotFoundException,
                            NotARetrievableObjectException,
                            RegionNotFoundException,
                            InvalidHandleException,
                            CacheException

returns a reference to the object associated with name. If the object is not currently in the cache and a loader object has been registered to the name of the object, then the object will be loaded into the cache. If a loader object has not been defined for this name, then, for DISTRIBUTE object, the default load method will do a netSearch for the object to see if the object exist in any other cache in the system; for a non DISTRIBUTE object, an ObjectNotFoundException will be thrown. The object returned by get is always a reference to a shared object. Get will always return the latest version of the object. A CacheAccess object will only maintain a reference to one cached object at any given time. If get is called multiple times, the object accessed previously will be released.

Parameters:

name - An unique name of the object in the Cache within the region specified by the current CacheAccess. The name Object must implement the equals and hashCode methods.

Returns:

ObjectA reference to the object associated with a name

Throws:

ObjectNotFoundException - is thrown if the object is not found in the cache.

RegionNotFoundException - is thrown if the region is not found in the cache.

NotARetrievableObjectException - it thrown if the name refers to is a group or pool object.

InvalidHandleException - If the CacheAccess is no longer valid

CacheException - if any other error occurs.

Since:

2.0.0

See Also:

load, get, get, put, put, put, put, defineObject

get

public java.lang.Object get(java.lang.Object name,
                            java.lang.Object args)
                     throws ObjectNotFoundException,
                            NotARetrievableObjectException,
                            RegionNotFoundException,
                            InvalidHandleException,
                            CacheException

returns a reference to the object associated with name. If the object is not currently in the cache and a loader object has been registered, the object will be loaded into the cache passing the args parameter to the load method of the loader object. If a loader object has not been defined for this name, then, for DISTRIBUTE object, the default load method will do a netSearch for the object to see if the object exist in any other cache in the system; for a non DISTRIBUTE object, an ObjectNotFoundException will be thrown. The object returned by get is always a reference to a shared object. Get will always return the latest version of the object. A CacheAccess object will only maintain a reference to one cached object at any given time. If get is called multiple times, the object accessed previously will be released.

Parameters:

name - An unique name of the object in the Cache within the region specified by the current CacheAccess The name Object must implement the equals and hashCode methods.

args - This arguments will be passed to the registered loader's load method. The usage is up to the implementation of the loader object.

Returns:

ObjectA reference to the object associated with the name

Throws:

ObjectNotFoundException - is thrown if the object is not found in the cache.

RegionNotFoundException - is thrown if the region is not found in the cache.

NotARetrievableObjectException - it thrown if name refers to a group or pool object.

InvalidHandleException - If the CacheAccess is no longer valid

CacheException - if any other error occurs.

Since:

2.0.0

See Also:

load, get, get, put, put, put, put, defineObject

get

public java.lang.Object get(java.lang.Object name,
                            java.lang.String group,
                            java.lang.Object args)
                     throws ObjectNotFoundException,
                            NotARetrievableObjectException,
                            RegionNotFoundException,
                            InvalidHandleException,
                            CacheException

returns a reference to the object associated with name. If the object is not currently in the cache and a loader object has been registered, the object will be loaded into the cache passing the args parameter to the load method of the loader object. If a loader object has not been defined for this name, then, for DISTRIBUTE object, the default load method will do a netSearch for the object to see if the object exist in any other cache in the system; for a non DISTRIBUTE object, an ObjectNotFoundException will be thrown. If a group is specified and the object is not loaded, the object will be associated with the group. The group must already exist. The object returned by get is always a reference to a shared object. Get will always return the latest version of the object. A CacheAccess object will only maintain a reference to one cached object at any given time. If get is called multiple times, the object accessed previously will be released.

Parameters:

name - An unique name of the object in the Cache within the current region The name Object must implement the equals and hashCode methods.

group - If the object has not been loaded into the cache yet, this object will be associates with the specified group. A group can be created by calling defineGroup(String).

args - The arguments will be passed to the registered loader's load method. The usage is up to the implementation of the loader object.

Returns:

A reference to the named object.

Throws:

ObjectNotFoundException - is thrown if the object is not found in the cache.

RegionNotFoundException - is thrown if the region is not found in the cache.

NotARetrievableObjectException - is thrown if name refers to a group or pool object in the cache.

InvalidHandleException - if the CacheAccess is no longer valid

Since:

2.0.0

See Also:

load, get, get, put, put, put, put, defineObject, defineGroup

preLoad

public void preLoad(java.lang.Object name)
             throws ObjectNotFoundException,
                    InvalidHandleException,
                    CacheException

allows for asynchronous loading of objects into the cache. This method will schedule a background task to load the object via the registered loader object. If no loader object has been registered, an ObjectNotFoundException will be thrown. The name object must implement the equals and hashCode methods.

Parameters:

name - An unique name of the object in the Cache within the current region The name Object must implement the equals and hashCode methods.

Throws:

InvalidHandleException - if the CacheAccess is no longer valid

Since:

2.0.0

See Also:

load, get, put, defineGroup

preLoad

public void preLoad(java.lang.Object name,
                    java.lang.Object args)
             throws ObjectNotFoundException,
                    InvalidHandleException,
                    CacheException

allows for asynchronous loading of objects into the cache. This method will schedule a background task to load the object via the registered loader object. If no loader object has been registered, an ObjectNotFoundException will be thrown. The name objec must implement the equals and hashCode methods.

Parameters:

name - An unique name of the object in the Cache within the current region The name Object must implement the equals and hashCode methods.

args - The arguments will be passed to the registered loader's load method. The usage is up to the implementation of the loader object.

Throws:

ObjectNotFoundException - is thrown if the loader object is not found

InvalidHandleException - if the CacheAccess is no longer valid

Since:

2.0.0

See Also:

load, get, put, defineObject, defineGroup

preLoad

public void preLoad(java.lang.Object name,
                    java.lang.String group,
                    java.lang.Object args)
             throws ObjectNotFoundException,
                    InvalidHandleException,
                    CacheException

allows for asynchronous loading of objects into the cache. This method will schedule a background task to load the object via the registered loader object. If no loader object has been registered, an ObjectNotFoundException will be thrown. The name objec must implement the equals and hashCode methods.

Parameters:

name - An unique name of the object in the Cache within the current region The name Object must implement the equals and hashCode methods.

group - If the object has not been loaded into the cache yet, this object will be associates with the specified group. A group can be created by calling defineGroup(String).

args - The arguments will be passed to the registered loader's load method. The usage is up to the implementation of the loader object.

Throws:

ObjectNotFoundException - is thrown if the loader object is not found

InvalidHandleException - if the CacheAccess is no longer valid

Since:

2.0.0

See Also:

load, get, put, defineObject, defineGroup

put

public void put(java.lang.Object name,
                java.lang.Object obj)
         throws CacheException

allows a new object to be placed into the cache identified by name. If there is currently an object associated with name in the cache, an ObjectExistException is thrown. Names are scoped to a region so they must be unique within the region they are placed. Put 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. Put is not valid on a pool object. Put is not associated with any loader object. If a loader object has been registered to a name, an exception will be thrown if using the same existing name with put.

Parameters:

name - A name associated with the object to be put into the cache. This name has to be unique within a region. The name Object must implement the equals and hashCode methods.

obj - Object to be put into the cache

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

put, put, put, get, load

put

public void put(java.lang.Object name,
                java.lang.String group,
                java.lang.Object obj)
         throws CacheException

allows a new object to be placed into the cache identified by name. If there is currently an object associated with name in the cache, an ObjectExistException is thrown. The object will be associated with the specified group. The group must already exist in the cache. A group can be create by calling defineGroup. Names are scoped to a region so they must be unique within the region they are placed. Put is intended for very simple caching situations. In general it is better to create a CacheLoad object and allow the cache to manage the creation and loading of objects. Put is not valid on a pool object. Put is not associated with any loader object. If a loader object has been registered to a name, an exception will be thrown if using the same existing name with put.

Parameters:

name - Name associated with the object to be put into the cache. The name Object must implement the equals and hashCode methods.

group - The Group where the object associated with

obj - Object to be put into the cache

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

put, put, put, get, load, defineGroup

put

public void put(java.lang.Object name,
                Attributes attr,
                java.lang.Object obj)
         throws CacheException

allows a new object to be placed into the cache identified by name. If there is currently an object associated with name in the cache, an ObjectExistException is thrown. Names are scoped to a region so they must be unique within the region they are placed. Put 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. Put is not valid on a pool object. Put is not associated with any loader object. If a loader object has been registered to a name, an exception will be thrown if using the same existing name with put.

Parameters:

name - Name associated with the object to be put into the cache The name Object must implement the equals and hashCode methods.

attr - Attributes associate with the object

obj - Object to be put into the cache

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

put, put, put, Attributes, get, load

put

public void put(java.lang.Object name,
                java.lang.String group,
                java.lang.Object obj,
                Attributes attr)
         throws CacheException

allows a new object to be placed into the cache identified by name. If there is currently an object associated with name in the cache, an ObjectExistException is thrown. The object will be associated with the specified group. The group must already exist in the cache. Group can be create by calling defineGroup. Names are scoped to a region so they must be unique within the region they are placed. Put 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. Put is not valid on a pool object. Put is not associated with any loader object. If a loader object has been registered to a name, an exception will be thrown if using the same existing name with put.

Parameters:

name - A globally unique name associated with the object to be put into the cache

group - The Group where the object associated with

obj - Object to be put into the cache

attr - Attributes associate with the object

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

put, put, put, Attributes, get, load, defineGroup

replace

public java.lang.Object replace(java.lang.Object name,
                                java.lang.Object obj)
                         throws CacheException

creates a new version of the object identified by name, replacing the current version with the object obj. The attributes will be inherited from the existing object. If the object doesn't exist in the cache replace is equivalent to a put. Names are scoped to a region so they must be unique within the region they are placed. Replace is not valid on a pool object.

Parameters:

name - Name of the object to be replaced. The name Object must implement the equals and hashCode methods.

obj - to replace the current object in the cache

Returns:

a reference to the newly cached object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

replace, get, get, get

replace

public java.lang.Object replace(java.lang.Object name,
                                java.lang.String group,
                                java.lang.Object obj)
                         throws CacheException,
                                NullObjectException

creates a new version of the object identified by name, replacing the current version with the object obj. If the object does not exist in the cache, replace is equivalent to a put. The specified attributes will be associated with the new version of the object. Names are scoped to a region so they must be unique within the region they are placed. Replace is not valid on a pool object.

Parameters:

name - Name of the object to be replaced. The name Object must implement the equals and hashCode methods.

group - The Group where the object associated with

obj - to replace the current object in the cache

Returns:

a reference to the newly cached object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

replace, replace, get, get, get, defineGroup

invalidate

public void invalidate()
                throws CacheException

marks all objects within the region as invalid. Invalidate does not affect the region or groups within the region, just individual objects are invalidated. To completely remove ALL objects in the region destroy must be called.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

invalidate, getAccess, getAccess, defineRegion, destroy, destroy

invalidate

public void invalidate(java.lang.Object name)
                throws CacheException

marks all objects within the scope of name as invalid. If name refers to a group object the invalidate will cascade to all objects associated with the group or any subgroups. The group objects themselves are not invalidated. Destroy must be called to remove group object. Invalidate doesn't "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 - An object name or a group name.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

invalidate, destroy, destroy

disable

public void disable()
             throws CacheException

invalidates all the objects in the region and marks all the groups in the region and the region itself as DISABLED. The environment built by defineRegion, defineGroup or defineObject will be kept intact. Operations in a DISABLED region are defined as following: put, replace, preLoad will be no operation. If a loader is defined, get will return the object loaded by the loader, but the object will not be put into cache. A DISABLED region, group or object can be re-enabled by calling enable.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

disable

public void disable(java.lang.Object name)
             throws CacheException

invalidates all the objects within the scope of the name and marks all the groups, regions and subregions within the scope of the name as DISABLED. The environment built by defineRegion, defineGroup or defineObject will be kept intact. Operations in a DISABLED object, group or region is defined as following: put, replace, preLoad will be no operation. If a loader is defined, get will return the object loaded by the loader, but the object will not be put into cache. A DISABLED region, group or object can be re-enabled by calling enable.

Parameters:

name - An object identifying a cache region, group or object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

enable

public void enable()
            throws CacheException

Re-enables the current region, including all the cache objects, groups and subregions in the region. After the enable, all the subregions, groups and objects are marked as NOT DISABLED. CacheAccess APIs are going to behave as defined.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

enable

public void enable(java.lang.Object name)
            throws CacheException

re-enables the objects, groups, and subregions within the scope of the name. After the enable, all the subregions and groups are marked as NOT DISABLED. CacheAccess APIs are going to behave as defined.

Parameters:

name - An object identifying a cache region, group or object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

isDisabled

public boolean isDisabled()
                   throws CacheException

returns a boolean to indicate if the region, which this cache access is referencing, is disabled or not.

Returns:

true, if the region is disabled; false, otherwise.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

isDisabled

public boolean isDisabled(java.lang.Object name)
                   throws CacheException

returns a boolean to indicate if the cache entity (region, group or object) identified by Object "name" is disabled.

Returns:

true, if the named region, group or object is disabled; false, otherwise.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

save

public void save()
          throws CacheException,
                 NullObjectNameException

causes all the objects within the scope of region to be saved to the disk cache. Objects that can't be written to disk will be ignored. All exceptions encountered will be logged. Local objects will be saved in the process specific disk cache, distributed objects will be saved in the machine global disk cache. Save can be used as a check point method. The distributed objects saved in the machine global disk cache can be retrieved by another cache process.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

save

public void save(java.lang.Object objname)
          throws CacheException,
                 NullObjectNameException

causes all the objects within the scope of name to be saved to the disk cache. If name refers to a specific object and the object is not serializable a CacheException will be logged. If the save references a group, objects that can't be serialized will be ignored. All exceptions encountered will be logged. Local objects will be saved in the process specific cache, distributed objects will be saved in the machine global disk cache. Save can be used as a check point method. The distributed objects saved in the machine global disk cache can be retrieved by another cache process.

Parameters:

name - An object name or a group name.

Throws:

NullArgumentException - if the object passed in is null

CacheException - if any cache error occurs.

Since:

2.0.0

close

public void close()

releases the resource used by current CacheAccess object. Application is required to make this call when it no longer need this CacheAccess instance.

Since:

2.0.0

See Also:

getAccess, getAccess

defineGroup

public void defineGroup(java.lang.String name)
                 throws CacheException

is used to create a new group within the context of the region referred to the CacheAccess object. The group is identified by the name specified. The attributes for the group are the same as those specified for the region.

Parameters:

name - Name of a group to be created

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup

defineGroup

public void defineGroup(java.lang.String name,
                        java.lang.String group)
                 throws CacheException

is used to create a new group within the context of the region referred to the CacheAccess object and associated with the group specified. The new group is identified by the name specified. The attributes for the group are the same as those specified for the group this new group was associated with.

Parameters:

name - Name of a group to be created

group - Name of the group the new group will be associated with

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup

defineGroup

public void defineGroup(java.lang.String name,
                        Attributes attr)
                 throws CacheException

is used to create a new group within the context of the region referred to the CacheAccess object. The group is identified by the name specified. The specified attributes will be set for the group. If the attributes argument is null, the attributes for the group are the same as those specified for the region.

Parameters:

name - Name of a group to be created

attr - Attributes of the group object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup

defineGroup

public void defineGroup(java.lang.String name,
                        java.lang.String group,
                        Attributes attr)
                 throws CacheException

is used to create a new group within the context of the region referred to the CacheAccess object and associated with the group specified. The new group is identified by the name specified. The specified attributes will be set for the group. If the attributes argument is null, the attributes for the group are the the same as those specified for the group this new group was associated with.

Parameters:

name - Name of a group to be created.

group - Name of a parent group where the new created group belongs to.

attr - Attributes of the group object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup

defineSubRegion

public void defineSubRegion(java.lang.String name)
                     throws CacheException

is used to define a new subRegion within the context of the region referred to the CacheAccess object. A subRegion defines a unique name space, independent of the parent but is still related to the parent in that it will inherit the parents attributes and invalidates and destroys will cascade into the subRegion.

Parameters:

name - Name of a subRegion to be created.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup, defineSubRegion

defineSubRegion

public void defineSubRegion(java.lang.String name,
                            Attributes attr)
                     throws CacheException

is used to define a new subRegion within the context of the region referred to the CacheAccess object. A subRegion defines a unique name space, independent of the parent but is still related to the parent in that it will inherit the parents attributes and invalidates and destroys will cascade into the subRegion.

Parameters:

name - Name of a subRegion to be created.

attr - Attributes of the group object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup, defineSubRegion

getSubRegion

public CacheAccess getSubRegion(java.lang.String name)
                         throws CacheException

getSubRegion will return a CacheAccess object associated with the named subRegion. The subRegion named may be a direct child of the current region or a descendent of the child. The name of a descendent other than a direct child is specified as ///...

Parameters:

name - Name of a subRegion to be created.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

defineGroup, defineGroup, defineGroup, defineSubRegion, defineSubRegion

getParent

public java.lang.String getParent()
                           throws CacheException

returns the name of the parent region if any. region. If the current region was not defined as a subRegion the parent will be null.

Returns:

the name of the parent region if any.

Throws:

CacheException - if any cache error occurs.

Since:

2.1.0

See Also:

defineSubRegion, defineSubRegion

createPool

public void createPool(java.lang.String name,
                       PoolInstanceFactory factory,
                       Attributes attr,
                       int min,
                       int max)
                throws InvalidArgumentException,
                       CacheException

creates an object pool containing at least min instances of the object created by calling factory.createInstance(). Any cache object attributes set in attr will be associated with all objects in the pool. If the argument max is greater than 0, the pool will never contain more than max objects. A value less than or equal to 0 indicates no maximum. The pool size may go below min if the object instances are idle and the cache requires more space for other users. If min is below zero or max is below min or max is below 1, the InvalidArgumentException will be thrown.

Parameters:

name - The name of the object pool.

factory - A user-defined PoolInstanceFactory.

attr - Attributes of the objects.

min - Minimum instances of the objects in the pool.

max - Maximum instances of the objects in the pool.

Throws:

InvalidArgumentException - If min is below zero or max is below min or max is below 1

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

PoolAccess, PoolInstanceFactory, Attributes

createPool

public void createPool(java.lang.String name,
                       java.lang.String group,
                       PoolInstanceFactory factory,
                       Attributes attr,
                       int min,
                       int max)
                throws InvalidArgumentException,
                       CacheException

creates an object pool containing at least min instances of the object created by calling factory.createInstance(). Any cache object attributes set in attr will be associated with all objects in the pool. If the argument max is set, the pool will never contain more than max objects. The pool size may go below min if the object instances are idle and the cache requires more space for other users. If min is below zero or max is below min or max is below 1, the InvalidArgumentException will be thrown.If group is specified the pool will be created as part of the group specified.

Parameters:

name - The name of the object pool.

group - A group where the pool will be created in.

factory - A user-defined PoolInstanceFactory.

attr - Attributes of the objects.

min - Minimum instances of the objects in the pool.

max - Maximum instances of the objects in the pool.

Throws:

InvalidArgumentException - If min is below zero or max is below min or max is below 1

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

PoolAccess

destroy

public void destroy()
             throws CacheException

destroys all objects associated with the current region including the region. The CacheAccess object can no longer be used as it will be closed and returned to the cache pool. Destroy can't be called on the default region.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

destroy, destroy, getAccess, getAccess

destroy

public void destroy(java.lang.Object name)
             throws CacheException

invalidates all objects associated with name, removing all references to the objects from the cache.

Parameters:

name - Name of the scope where all objects will be destroyed

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

destroy

waitForResponse

public void waitForResponse(int timeout)
                     throws CacheException

is used to wait for replies returned from invalidates or updates when a reply is requested. This method will block the calling thread until the response for all replies associated with the CacheAccess object are received or until the timeout value is reached. Timeout is the maximum number of milliseconds to wait for all remote caches to reply. If the timeout is reached before all responses are received a TimeoutException is thrown. If this method times out and the caller does not intend to call WaitForResponse again on this event cancelResponse should be called.

Parameters:

timeout - Timeout is the maximum number of milliseconds to wait for all remote caches to reply

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

cancelResponse, Attributes

cancelResponse

public void cancelResponse()
                    throws CacheException

terminates the request for a reply from the previous invalidate or update. If a response was requested then 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. It affects all response associated with the CacheAccess object.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

waitForResponse, Attributes

getOwnership

public java.lang.Object getOwnership(int timeout)
                              throws CacheException

claims the ownership of the region, if the region has been defined as "SYNCHRONIZE". If a region is defined SYNCHRONIZE ownership must be acquired before any object in the region can be loaded or replace. If ownership is not available, the thread making this call will be blocked for the specified timeout period. The local cache is checked first, if the local cache doesn't hold ownership of the object, a message is sent to all other caches in the system. The ownership concept is designed to maintain strong consistency among distributed caches.

After an ownership is acquired, it is maintained until it is explicitly released by the user with the releaseOwnership method. The ownership of a region, group, or object is associated with a CacheAccess object instance. A CacheAccess object instance can have ownership of more than one object at a time.

Parameters:

name - Name of an object for getting its ownership

timeout - A period of time in milliseconds to be block if ownership of the specified object is not available.

Returns:

the actual object the lock is associated with to be used in release lock

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

ReleaseOwnership, Attributes

getOwnership

public java.lang.Object getOwnership(java.lang.Object name,
                                     int timeout)
                              throws CacheException

claims the ownership of the object with specified name for this CacheAccess instance, if the object has been defined as "SYNCHRONIZE". If a object is defined SYNCHRONIZE ownership must be acquired before the object can be loaded or replace. If ownership is not available, the thread making this call will be blocked for the specified timeout period. The local cache is checked first, if the local cache doesn't hold ownership of the object, a message is sent to all other caches in the system. The ownership concept is designed to maintain strong consistency among distributed caches.

After an ownership is acquired, it is maintained until it is explicitly released by the user with the releaseOwnership method. The ownership of a region, group, or object is associated with a CacheAccess object instance. A CacheAccess object instance can have ownership of more than one object at a time.

Parameters:

name - Name of an object for getting its ownership

timeout - A period of time in milliseconds to be block if ownership of the specified object is not available.

Returns:

the actual object the lock is associated with to be used in release lock

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

ReleaseOwnership, Attributes

getOwnership

public java.lang.Object getOwnership(java.lang.Object name,
                                     java.lang.String group,
                                     int timeout)
                              throws CacheException

claims the ownership of the object with specified name for this CacheAccess instance, if the object has been defined as "SYNCHRONIZE". If a object is defined SYNCHRONIZE ownership must be acquired before the object can be loaded or replace. If synchronization has been defined as "SYNCHRONIZE_DEFAULT" on the group rather than on the specific object, the group name must also be passed in as a parameter. If ownership is not available, the thread making this call will be blocked for the specified timeout period. The local cache is checked first, if the local cache doesn't hold ownership of the object, a message is sent to all other caches in the system. The ownership concept is designed to maintain strong consistency among distributed caches.

After an ownership is acquired, it is maintained until it is explicitly released by the user with the releaseOwnership method. The ownership of a region, group, or object is associated with a CacheAccess object instance. A CacheAccess object instance can have ownership of more than one object at a time.

Parameters:

name - Name of an object for getting its ownership

group - Name of an group the object is associated with

timeout - A period of time in milliseconds to be block if ownership of the specified object is not available.

Returns:

the actual object the lock is associated with to be used in release lock

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

ReleaseOwnership, Attributes

isPresent

public boolean isPresent(java.lang.Object name)

returns true if the named object currently exists in the cache false otherwise.

Parameters:

name - Name of the object for getting its attributes

Returns:

true if the object exists in the cache, false otherwise

Since:

2.0.0

releaseOwnership

public void releaseOwnership(int timeout)
                      throws CacheException

is used to explicitly give up ownership of the region. Ownership is only relevant if the region is defined as SYNCHRONIZE. ReleaseOwnership will block until any outstanding updates have completed or until the timeout has been reached. If the method times out, ownership is not released. ReleaseOwnership may be called again to wait for a new timeout period. If the timeout is less than 0, the lock is released without waiting for the update to complete. Releasing ownership before the update completes can cause the object to be inconsistent across distributed caches.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

getOwnership, getOwnership, Attributes

releaseOwnership

public void releaseOwnership(java.lang.Object name,
                             int timeout)
                      throws CacheException

is used to explicitly give up ownership of the named object. Ownership is only relevant if the object is defined as SYNCHRONIZE or the group containing the object is defined as SYNCHRONIZE_DEFAULT. ReleaseOwnership will block until any outstanding updates have completed or until the timeout has been reached. If the method times out, ownership is not released. ReleaseOwnership may be called again to wait for a new timeout period. If the timeout is less than 0, the lock is released without waiting for the update to complete. Releasing ownership before the update completes can cause the object to be inconsistent across distributed caches.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

getOwnership, getOwnership, Attributes

getAttributes

public Attributes getAttributes()
                         throws CacheException

returns an attribute object describing the current region.

Returns:

An Attributes Object of the current region.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

getAttributes, Attributes

getAttributes

public Attributes getAttributes(java.lang.Object name)
                         throws CacheException

returns an attribute object describing the current attributes associated with the object name (can be a group).

Parameters:

name - Name of the object for getting its attributes

Returns:

An Attributes Object of the specified object in the cache.

Throws:

CacheException - if any cache error occurs.

Since:

2.0.0

See Also:

getAttributes, Attributes

getPool

public PoolAccess getPool(java.lang.String name)
                   throws NotAPoolException,
                          ObjectNotFoundException,
                          CacheException

returns a PoolAccess object associated with the object name. The PoolAccess object can then be used to retrieve an instance of an object from the pool. If name does not refer to a pool object, a NotAPoolException will be thrown. If name is not in the cache an ObjectNotFoundException will be thrown.

Parameters:

name - Name of a pool object.

Returns:

A PoolAccess object.

Throws:

NotAPoolException - if name does not refer to a pool object.

ObjectNotFoundException - if name is not in the cache.

CacheException - if any other error occurs

Since:

2.0.0

See Also:

PoolAccess

getRegionName

public java.lang.String getRegionName()

returns the name of the current region of the CacheAccess object.

Returns:

The region name of the current CacheAccess object

Since:

2.0.0

See Also:

getAccess, getDefRegionName

listNames

public java.lang.Object[] listNames()
                             throws RegionNotFoundException,
                                    InvalidHandleException,
                                    CacheException

returns a list of the names of all objects in this region This list is only the names of the objects, it doesn't obtain a reference to the object. This list is a snapshot of the region at the time. If the list is used to retrieve objects from the cache, it is possible the object is no longer in the cache at the time of the retrieval. This may result in the object being reloaded or an ObjectNotFoundException. The list contains only the objects in the region itself, it does not contain objects in subRegions of the region.

Returns:

Object[]An array of names of objects in the region name

Throws:

RegionNotFoundException - is thrown if the region is not found in the cache.

InvalidHandleException - If the CacheAccess is no longer valid

CacheException - if any other error occurs.

Since:

2.1.1

listRegions

public java.lang.String[] listRegions()
                               throws RegionNotFoundException,
                                      InvalidHandleException,
                                      CacheException

returns an array of all subRegions in this region The list contains only the subRegions in the region itself, it does not contain subRegions in subRegions of the region.

Returns:

String[]An array of the names of the subRegions in the region

Throws:

RegionNotFoundException - is thrown if the region is not found in the cache.

InvalidHandleException - If the CacheAccess is no longer valid

CacheException - if any other error occurs.

Since:

2.1.1

listObjects

public java.util.Enumeration listObjects()
                                  throws RegionNotFoundException,
                                         InvalidHandleException,
                                         CacheException

returns an Enumeration that will allow access to the objects in the region. With each nextElement call, a ListObject is returned. The ListObject contains the name of the next object in the region and a reference to the object. The reference to the object is tied to the CacheAccess handle as if CacheAccess.get had been called. Each subsequent nextElement call will release the reference to the previous object. When listObjects is executed a list of the objects in the region at the time is created. Objects on that list may be invalidated by another user or based on time to live before they are referenced by the nextElement method on the Enumeration. Any objects on the list that have been invalidate will be ignore. Only valid objects will be returned to the caller. The Enumeration contains only the objects in the region itself, it does not contain objects in subRegions of the region.

Returns:

EnumerationAn Enumeration of objects in the region name

Throws:

RegionNotFoundException - is thrown if the region is not found in the cache.

InvalidHandleException - If the CacheAccess is no longer valid

CacheException - if any other error occurs.

Since:

2.1.1

getDefRegionName

public static java.lang.String getDefRegionName()

returns the name of the default Region.

Returns:

The default region name of the Cache Service

Since:

2.0.0

See Also:

getRegionName