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
Version:
2.0.6 07/31/2000
Method Summary
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(boolean localOnly)
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
destroy(java.lang.Object[] names)
invalidates all objects associated with the array of names, removing
all references to the objects from the cache.
void
destroy(java.lang.Object[] names,
boolean localOnly)
invalidates all objects associated with the array of names, removing
all references to the objects from the cache.
void
destroy(java.lang.Object name,
boolean localOnly)
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.
getAccess(java.lang.String region,
Attributes attr,
boolean subRegion)
is a static method that returns a CacheAccess object
allowing access to the specified cache region.
getAccess(java.lang.String region,
boolean checkRegion)
is a static method that returns a CacheAccess object
allowing access to the specified cache region.
getAggregateStatus(java.lang.Object name)
returns an aggregate status object describing the aggregate
status associated with the group or region name.
java.util.Vector
getAllCached(java.lang.Object name,
int timeout)
returns a Vector of instances of the named object from all the caches in
the distributed system.
java.util.Vector
getAllCached(java.lang.Object name,
int timeout,
boolean ignoreRemoteEx)
returns a Vector of instances of the named object from all the caches in
the distributed system.
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.
getSubRegion(java.lang.String name,
Attributes attr)
getSubRegion will return a CacheAccess object associated with the
named subRegion.
void
invalidate()
marks all objects within the region as invalid.
void
invalidate(boolean localOnly)
marks all objects within the region as invalid.
void
invalidate(java.lang.Object name)
marks all objects within the scope of name as invalid.
void
invalidate(java.lang.Object[] names)
marks all objects within the scope of names as invalid.
void
invalidate(java.lang.Object[] names,
boolean localOnly)
marks all objects within the scope of names as invalid.
void
invalidate(java.lang.Object name,
boolean localOnly)
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
loadList(java.lang.Object[] name)
load an array of objects into the cache.
void
loadList(java.lang.Object[] name,
java.lang.Object args)
load an array of objects into the cache.
void
loadList(java.lang.Object[] name,
java.lang.String group,
java.lang.Object args)
load an array of objects into the cache.
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
replaceRemote(java.lang.Object name,
java.lang.Object obj,
oracle.ias.cache.CacheAddress addr)
creates a new version of the object identified by name,in a remote cache,
replacing the current version with the object obj.
void
replaceRemote(java.lang.Object name,
java.lang.String group,
java.lang.Object obj,
oracle.ias.cache.CacheAddress addr)
creates a new version of the object identified by name,in a remote cache,
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
spool(java.lang.Object objname)
causes the object to be spooled to disk
If the object is not serializable a CacheException will be logged.
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:
oracle.ias.cache.ObjectExistsException - if the specified region already exists.
oracle.ias.cache.NullObjectNameException - if the region name is null.
public static void defineRegion(java.lang.String region)
throws CacheNotAvailableException,
oracle.ias.cache.NullObjectNameException,
oracle.ias.cache.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:
oracle.ias.cache.ObjectExistsException - if the specified region already exists.
oracle.ias.cache.NullObjectNameException - if the region name is null.
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.
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.
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.
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.
If the region doesn't exist it will be created using the Attributes
provided. If the attr parameter is null, the default attributes will be
used.
When accessing a subRegion, the getSubRegion method should be used. If
the subRegion doesn't exist a region named "region/subRegion" will be
created not a subRegion within the region "region".
Parameters:
region - Name of the region to access
attr - Attributes to set for the region
subRegion - indicates the region is a subRegion so the name
should be interrupted as a hierarchy rather than a single region name
Returns:
An instance of CacheAccess object. This object is not thread-
safe.
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.
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.
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.
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.
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:
oracle.ias.cache.ObjectNotFoundException - is thrown if the object is not found
in the cache.
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
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:
oracle.ias.cache.ObjectNotFoundException - is thrown if the object is not found
in the cache.
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
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:
oracle.ias.cache.ObjectNotFoundException - is thrown if the object is not found
in the cache.
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
load an array of objects into the cache. The objects are stored in the
cache as individual objects. This method just allows for multiple
objects to be loaded with a single call to the loader. If an object in
the list is already in the cache it will not be reloaded. All other
names in the list will be passed to the CacheListLoader object associated
with the objects. If there is no CacheListLoader object available for
an object in the list or the CacheListObject is not the same for all
objects in the list, the objects will be loaded as individual objects.
Any exceptions that occur during the load will be logged and the
processing of the list will continue. Only the last exception will be
thrown.
Parameters:
name - An array of object names to be loaded in to the cache
Throws:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
load an array of objects into the cache. The objects are stored in the
cache as individual objects. This method just allows for multiple
objects to be loaded with a single call to the loader. If an object in
the list is already in the cache it will not be reloaded. All other
names in the list will be passed to the CacheListLoader object associated
with the objects. If there is no CacheListLoader object available for
an object in the list or the CacheListObject is not the same for all
objects in the list, the objects will be loaded as individual objects.
Any exceptions that occur during the load will be logged and the
processing of the list will continue. Only the last exception will be
thrown.
Parameters:
name - An array of object names to be loaded in to the cache
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:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.