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.
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 unique name of the object in the Cache within the region
specified by the current CacheAccess. The name Object must implement
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.
the equals and hashCode methods.
Throws:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
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.
public void preLoad(java.lang.Object name,
java.lang.Object args)
throws oracle.ias.cache.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:
oracle.ias.cache.ObjectNotFoundException - is thrown if the loader object is not
found
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:
oracle.ias.cache.ObjectNotFoundException - is thrown if the loader object is not
found
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.
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
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.
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
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.
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
public void replaceRemote(java.lang.Object name,
java.lang.Object obj,
oracle.ias.cache.CacheAddress addr)
throws CacheException
creates a new version of the object identified by name,in a remote cache,
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
addr - the CacheAddress object associated with the remote cache
creates a new version of the object identified by name,in a remote cache,
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:
addr - the CacheAddress object associated with the remote cache
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
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.
public void invalidate(boolean localOnly)
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.
Parameters:
localOnly - If true the region should only be invalidated in the
local cache. The invalidation will not be distributed.
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.
public void invalidate(java.lang.Object name,
boolean localOnly)
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.
localOnly - If true the object should only be invalidated in the
local cache. The invalidation will not be distributed.
public void invalidate(java.lang.Object[] names)
throws CacheException
marks all objects within the scope of names as invalid. If any of the
objects in the names array
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.
public void invalidate(java.lang.Object[] names,
boolean localOnly)
throws CacheException
marks all objects within the scope of names as invalid. If any of the
objects in the names array
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:
names - An array of object and/or group names.
localOnly - If true the objects should only be invalidated in the
local cache. The invalidation will not be distributed.
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.
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.
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.
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.
public void save()
throws CacheException,
oracle.ias.cache.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.
public void save(java.lang.Object objname)
throws CacheException,
oracle.ias.cache.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.
Throws:
NullArgumentException - if the object passed in is null
public void spool(java.lang.Object objname)
throws CacheException,
oracle.ias.cache.NullObjectNameException
causes the object to be spooled to disk
If the object is not serializable a CacheException will be logged.
All exceptions encountered will be logged. Local objects
will be saved in the process specific cache, distributed objects will
be spooled in the machine global disk cache. The spooling is an
asynchronous operation. Once the object is on disk it will be removed
from memory, if it is not currently being referenced.
Throws:
NullArgumentException - if the object passed in is null
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.
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
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.
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.
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.
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.
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
///...
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
child/descendent/descendent2/...
If the subRegion doesn't exist it will be created using the Attributes
provided. If the attr parameter is null, the attributes will be
inherited from the parent.
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.
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.
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.
public void destroy(boolean localOnly)
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.
Parameters:
localOnly - If true the region should only be invalidated in the
local cache. The invalidation will not be distributed.
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
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.
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:
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
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
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
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.
Parameters:
timeout - Timeout is the maximum number of milliseconds to wait for all
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.
Parameters:
name - Name of an object for releasing its ownership
timeout - Timeout is the maximum number of milliseconds to wait for all
returns an aggregate status object describing the aggregate
status associated with the group or region name.
This method is not applicable to a cached object. A null will be returned
if called on a cache object
Returns:
An Attributes Object of the specified object in the cache.
returns an aggregate status object describing the aggregate
status associated with the group or region name.
This method is not applicable to a cached object. A null will be returned
if called on a cache object
Parameters:
name - Name of the object for getting its attributes
Returns:
An Attributes Object of the specified object in the cache.
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.
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:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
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:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
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:
oracle.ias.cache.RegionNotFoundException - is thrown if the region is not found
in the cache.
returns a Vector of instances of the named object from all the caches in
the distributed system. All of the instances must be of the same basic
type (i.e., they must all be memory objects, or all be disk objects, or
all be stream objects). The object is not loaded into the cache, only
instances of the object that are currently in the cache are returned.
This method can be used to collect instance specific information from
across the cache system, such as instance statics. If the object is not
found in any cache, an empty vector will be returned. After processing
the data in the Vector, cancelResponse should be called to clean up any
temporary files. A CacheAccess object will only maintain a reference to
one cached object at any given time. If getAllCached 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.
timeout - Timeout is the maximum number of milliseconds to wait for all
Returns:
VectorA vector to instances of 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 Vector of instances of the named object from all the caches in
the distributed system. All of the instances must be of the same basic
type (i.e., they must all be memory objects, or all be disk objects, or
all be stream objects). The object is not loaded into the cache, only
instances of the object that are currently in the cache are returned.
This method can be used to collect instance specific information from
across the cache system, such as instance statics. If the object is not
found in any cache, an empty vector will be returned. Exceptions thrown
by remote caches are ignored unless ignoreRemoteEx is set to false.
After processing the data in the Vector, cancelResponse should be called
to clean up any temporary files. A CacheAccess object will only maintain
a reference to one cached object at any given time. If getAllCached 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.
timeout - Timeout is the maximum number of milliseconds to wait for all
ignoreRemoteEx - A boolean variable to indicate whether the user
cares about possible exceptions returned by remote caches
Returns:
VectorA vector to instances of 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.
oracle.ias.cache.CacheAccess
