<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">

Package   Class  Tree  Deprecated  Index  Help 
 Oracle Application Server 10g Java Object Cache API Reference
10g(9.0.4)<br/>B10388-01
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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
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, oracle.ias.cache.PoolInstanceFactory factory, oracle.ias.cache.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, oracle.ias.cache.PoolInstanceFactory factory, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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.
static oracle.ias.cache.CacheAccess getAccess()
          is a static method that returns a CacheAccess object to the default region.
static oracle.ias.cache.CacheAccess getAccess(java.lang.String region)
          is a static method that returns a CacheAccess object allowing access to the specified cache region.
static oracle.ias.cache.CacheAccess getAccess(java.lang.String region, oracle.ias.cache.Attributes attr, boolean subRegion)
          is a static method that returns a CacheAccess object allowing access to the specified cache region.
static oracle.ias.cache.CacheAccess getAccess(java.lang.String region, boolean checkRegion)
          is a static method that returns a CacheAccess object allowing access to the specified cache region.
 oracle.ias.cache.AggregateStatus getAggregateStatus()
          returns an aggregate status object describing the aggregate status associated with the group or region name.
 oracle.ias.cache.AggregateStatus 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.
 oracle.ias.cache.Attributes getAttributes()
          returns an attribute object describing the current region.
 oracle.ias.cache.Attributes getAttributes(java.lang.Object name)
          returns an attribute object describing the current attributes associated with the object name (can be a group).
 int getCount()
          returns the current total count of objects for this region including objects in subRegions
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.
 oracle.ias.cache.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.
 oracle.ias.cache.ObjectStatus getStatus()
          returns an status object describing the current status associated with the object name (can be a group).
 oracle.ias.cache.ObjectStatus getStatus(java.lang.Object name)
          returns an status object describing the current status associated with the object name (can be a group).
 oracle.ias.cache.CacheAccess getSubRegion(java.lang.String name)
          getSubRegion will return a CacheAccess object associated with the named subRegion.
 oracle.ias.cache.CacheAccess getSubRegion(java.lang.String name, oracle.ias.cache.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, oracle.ias.cache.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, oracle.ias.cache.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(oracle.ias.cache.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, oracle.ias.cache.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.
 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Method Detail

defineRegion

public static void defineRegion(java.lang.String region,
                                oracle.ias.cache.Attributes attr)
                         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.
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.
CacheNotAvailableException - if it cannot initialize the Cache Service.
CacheException
Since:
2.0.0
See Also:
getAccess, Attributes, CacheAttributes

defineRegion

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.
CacheNotAvailableException - if it cannot initialize the Cache Service.
CacheException
Since:
2.0.0
See Also:
getAccess, Attributes, CacheAttributes

getAccess

public static oracle.ias.cache.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.
CacheException
Since:
2.0.0
See Also:
getAccess, defineRegion, close

getAccess

public static oracle.ias.cache.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 oracle.ias.cache.CacheAccess getAccess(java.lang.String region,
                                                     boolean checkRegion)
                                              throws CacheNotAvailableException,
                                                     oracle.ias.cache.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.
oracle.ias.cache.RegionNotFoundException - is thrown if the region does not exist and checkRegion is TRUE.
CacheException
Since:
2.0.0
See Also:
getAccess, defineRegion, close

getAccess

public static oracle.ias.cache.CacheAccess getAccess(java.lang.String region,
                                                     oracle.ias.cache.Attributes attr,
                                                     boolean subRegion)
                                              throws CacheNotAvailableException,
                                                     oracle.ias.cache.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. 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.
Throws:
CacheNotAvailableException - is thrown if the Cache Service cannot be initialized.
oracle.ias.cache.RegionNotFoundException
CacheException
Since:
9.0.4
See Also:
getAccess, defineRegion, close

defineObject

public void defineObject(java.lang.Object name,
                         oracle.ias.cache.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
attr - Attributes of the object.
Throws:
CacheException - if any cache error occurs.
Since:
2.0.0
See Also:
Attributes, defineGroup

defineObject

public void defineObject(java.lang.Object name,
                         java.lang.String group,
                         oracle.ias.cache.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, defineGroup

resetAttributes

public void resetAttributes(oracle.ias.cache.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.
InvalidHandleException
Since:
2.0.0
See Also:
Attributes, defineGroup

resetAttributes

public void resetAttributes(java.lang.Object name,
                            oracle.ias.cache.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.
InvalidHandleException
Since:
2.0.0
See Also:
Attributes, defineGroup

get

public java.lang.Object get(java.lang.Object name)
                     throws oracle.ias.cache.ObjectNotFoundException,
NotARetrievableObjectException,
                            oracle.ias.cache.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:
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.
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 oracle.ias.cache.ObjectNotFoundException,
NotARetrievableObjectException,
                            oracle.ias.cache.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:
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.
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 oracle.ias.cache.ObjectNotFoundException,
NotARetrievableObjectException,
                            oracle.ias.cache.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:
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.
NotARetrievableObjectException - is thrown if name refers to a group or pool object in the cache.
InvalidHandleException - if the CacheAccess is no longer valid
CacheException
Since:
2.0.0
See Also:
load, get, get, put, put, put, put, defineObject, defineGroup

loadList

public void loadList(java.lang.Object[] name)
              throws NotARetrievableObjectException,
                     oracle.ias.cache.RegionNotFoundException,
InvalidHandleException,
CacheException
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.
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:
9.0.4
See Also:
loadList, get, get, CacheListLoader

loadList

public void loadList(java.lang.Object[] name,
                     java.lang.Object args)
              throws NotARetrievableObjectException,
                     oracle.ias.cache.RegionNotFoundException,
InvalidHandleException,
CacheException
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.
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:
9.0.4
See Also:
loadList, get, get, CacheListLoader

loadList

public void loadList(java.lang.Object[] name,
                     java.lang.String group,
                     java.lang.Object args)
              throws NotARetrievableObjectException,
                     oracle.ias.cache.RegionNotFoundException,
InvalidHandleException,
CacheException
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.
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:
9.0.4
See Also:
load, get, get

preLoad

public void preLoad(java.lang.Object name)
             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 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
oracle.ias.cache.ObjectNotFoundException
CacheException
Since:
2.0.0
See Also:
load, get, put, defineGroup

preLoad

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
InvalidHandleException - if the CacheAccess is no longer valid
CacheException
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 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.
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
InvalidHandleException - if the CacheAccess is no longer valid
CacheException
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,
                oracle.ias.cache.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,
                oracle.ias.cache.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,
                                oracle.ias.cache.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.
oracle.ias.cache.NullObjectException
Since:
2.0.0
See Also:
replace, replace, get, get, get, defineGroup

replaceRemote

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
Returns:
a reference to the newly cached object.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
replace, replace, get, get, get

replaceRemote

public void replaceRemote(java.lang.Object name,
                          java.lang.String group,
                          java.lang.Object obj,
                          oracle.ias.cache.CacheAddress addr)
                   throws CacheException,
                          oracle.ias.cache.NullObjectException
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
obj - to replace the current object in the cache
Returns:
a reference to the newly cached object.
Throws:
CacheException - if any cache error occurs.
oracle.ias.cache.NullObjectException
Since:
9.0.4
See Also:
replace, replace, replace, get, get, get

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(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.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
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

invalidate

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.
Throws:
CacheException - if any cache error occurs.
Since:
2.0.0
See Also:
invalidate, destroy, destroy

invalidate

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.
Parameters:
names - An array of object and/or group names.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
invalidate, destroy, destroy

invalidate

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.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
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,
                 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.
Throws:
CacheException - if any cache error occurs.
oracle.ias.cache.NullObjectNameException
Since:
2.0.0

save

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
CacheException - if any cache error occurs.
oracle.ias.cache.NullObjectNameException
Since:
2.0.0

spool

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
CacheException - if any cache error occurs.
oracle.ias.cache.NullObjectNameException
Since:
9.0.4

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,
                        oracle.ias.cache.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,
                        oracle.ias.cache.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,
                            oracle.ias.cache.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 oracle.ias.cache.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 <child>/<descendent>/<descendent2>/...
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

getSubRegion

public oracle.ias.cache.CacheAccess getSubRegion(java.lang.String name,
                                                 oracle.ias.cache.Attributes attr)
                                          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 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.
Parameters:
name - Name of a subRegion to be created.
attr - Attributes to set for the region
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
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,
                       oracle.ias.cache.PoolInstanceFactory factory,
                       oracle.ias.cache.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,
                       oracle.ias.cache.PoolInstanceFactory factory,
                       oracle.ias.cache.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(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.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
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

destroy

public void destroy(java.lang.Object name,
                    boolean localOnly)
             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
localOnly - If true the object should only be invalidated in the local cache. The invalidation will not be distributed.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
destroy

destroy

public void destroy(java.lang.Object[] names)
             throws CacheException
invalidates all objects associated with the array of names, removing all references to the objects from the cache.
Parameters:
names - Array of names of the scope where all objects will be destroyed
CacheException
Since:
9.0.4
See Also:
destroy, destroy

destroy

public void destroy(java.lang.Object[] names,
                    boolean localOnly)
             throws CacheException
invalidates all objects associated with the array of names, removing all references to the objects from the cache.
Parameters:
names - Array of names of the scope where all objects will be destroyed
localOnly - If true the objects should only be invalidated in the local cache. The invalidation will not be distributed.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
destroy, 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:
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.
Parameters:
timeout - Timeout is the maximum number of milliseconds to wait for all
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.
Parameters:
name - Name of an object for releasing its ownership
timeout - Timeout is the maximum number of milliseconds to wait for all
Throws:
CacheException - if any cache error occurs.
Since:
2.0.0
See Also:
getOwnership, getOwnership, Attributes

getAttributes

public oracle.ias.cache.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 oracle.ias.cache.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

getStatus

public oracle.ias.cache.ObjectStatus getStatus()
                                        throws CacheException
returns an status object describing the current status associated with the object name (can be a group).
Returns:
An Attributes Object of the specified object in the cache.
Throws:
CacheException - if any cache error occurs.
Since:
2.0.0
See Also:
getStatus, ObjectStatus

getAggregateStatus

public oracle.ias.cache.AggregateStatus getAggregateStatus()
                                                    throws CacheException
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.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
getAggregateStatus, AggregateStatus

getStatus

public oracle.ias.cache.ObjectStatus getStatus(java.lang.Object name)
                                        throws CacheException
returns an status object describing the current status 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:
getStatus, ObjectStatus

getAggregateStatus

public oracle.ias.cache.AggregateStatus getAggregateStatus(java.lang.Object name)
                                                    throws CacheException
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.
Throws:
CacheException - if any cache error occurs.
Since:
9.0.4
See Also:
getAggregateStatus, AggregateStatus

getCount

public int getCount()
             throws CacheException
returns the current total count of objects for this region including objects in subRegions
Returns:
The number of objects in the region include objects in subRegions
CacheException
Since:
9.0.3

getPool

public oracle.ias.cache.PoolAccess getPool(java.lang.String name)
                                    throws NotAPoolException,
                                           oracle.ias.cache.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.
oracle.ias.cache.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 oracle.ias.cache.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:
oracle.ias.cache.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 oracle.ias.cache.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:
oracle.ias.cache.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 oracle.ias.cache.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:
oracle.ias.cache.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

getAllCached

public java.util.Vector getAllCached(java.lang.Object name,
                                     int timeout)
                              throws oracle.ias.cache.ObjectNotFoundException,
NotARetrievableObjectException,
                                     oracle.ias.cache.RegionNotFoundException,
InvalidHandleException,
CacheException
returns a Vector of instances of the named object from all the caches in the distributed system. 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.
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.
InvalidHandleException - If the CacheAccess is no longer valid
CacheException - if any other error occurs.
NotARetrievableObjectException
Since:
2.0.0
See Also:
load, get, get, put, put, put, put, defineObject

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
Package   Class  Tree  Deprecated  Index  Help 
 Oracle Application Server 10g Java Object Cache API Reference
10g(9.0.4)<br/>B10388-01
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2003 Oracle Corporation. All Rights Reserved.