2
Working with Objects and Attributes

This chapter describes the important constructs for the Object Caching Service for Java. The constructs include:

Object Caching Service for Java Object Types

This section describes the object types that the Object Caching Service for Java manages, including:

Memory Objects

Memory objects are Java objects that the Object Caching Service for Java manages. Memory objects are stored in the Java VM's heap space as Java objects. Memory objects can hold HTML pages, the results of a database query, or any information that can be stored as a Java object.

Memory objects are usually loaded into the Object Caching Service for Java with an application-supplied loader. The source of the memory object may be controlled externally (for example, using data in a table on the Oracle9i Database Server). The application supplied loader accesses the source and either creates or updates the memory object. Without the Object Caching Service for Java, the application would be responsible for accessing the source directly, rather than using the loader.

You can update memory objects by obtaining a private copy of the memory object, applying the changes to the copy, and then placing the updated object back in the cache (using CacheAccess.replace()).

The CacheAccess.defineObject() method associates attributes with an object. If attributes are not defined, the object inherits the default attributes from its associated region, subregion, or group.

An application can request that a memory object be spooled to a local disk (using the SPOOL attribute). Setting this attribute allows the caching service to handle memory objects that are large, or costly to re-create and seldom updated. When the disk cache is set up to be significantly larger than the memory cache, objects on disk usually stay in the disk cache longer than objects in memory.

Combining memory objects that are spooled to a local disk with the distributed feature from the DISTRIBUTE attribute provides object persistence (when the Object Caching Service for Java is running in distributed mode). Object persistence allows you to re-create objects when the system or the Java VM is restarted after the process fails or shuts down.

There are very few restrictions on Object Caching Service for Java memory objects. Memory objects can contain any Java object.

Disk Objects

Disk objects are stored on a local disk and are accessed directly from the disk by the application using the Object Caching Service for Java. Disk objects may be shared by all Object Caching Service for Java processes, or they may be local to a particular process, depending on the setting for the DISTRIBUTE attribute (and whether the Object Caching Service for Java is running in distributed or local mode).

Disk objects can be invalidated explicitly or by setting the TimeToLive or IdleTime attributes. Disk objects can be updated by obtaining a private copy of the disk object (file). When the Object Caching Service for Java requires additional space, disk objects that are not being referenced may be removed from the cache.

There are very few restrictions on disk objects in the Object Caching Service for Java.

StreamAccess Objects

StreamAccess objects are objects that are accessed as a stream, and are automatically loaded to the disk cache. The object is loaded as an OutputStream and read as an InputStream. The Object Caching Service for Java determines how to access the StreamAccess object based on the size of the object and the capacity of the cache. Smaller objects are accessed from memory, while larger objects are streamed directly from disk.

The cache user's access to the StreamAccess object is through an InputStream. All the attributes that apply to memory objects and disk objects also apply to StreamAccess objects. A StreamAccess object does not provide a mechanism to manage a stream; for example, StreamAccess objects cannot manage socket endpoints. InputStream and OutputStream objects are available to access fixed sized, potentially very large objects.

The Object Caching Service for Java places some restrictions on StreamAccess objects.

Pool Objects

A pool object is a special class of objects that the Object Caching Service for Java manages. A pool object contains a set of identical object instances. The pool object itself is a shared object, while the objects within the pool are private objects. Individual objects within the pool can be checked out to be used and then returned to the pool when they are no longer needed.

Attributes, including TimeToLive or IdleTime may be associated with a pool object. These attributes apply to the pool object as a whole, or they can be applied to the objects within the pool individually.

The Object Caching Service for Java instantiates objects within a pool using an application-defined factory object. The size of a pool decreases or increases based on demand and on the values of the TimeToLive or IdleTime attributes. A minimum size for the pool is specified when the pool is created. The minimum-size value is interpreted as a request rather than a guaranteed minimum value. Objects within a pool object are subject to removal from the cache due to lack of space, so the pool may decrease below the requested minimum value. A maximum pool size value can be set that puts a hard limit on the number of objects available in the pool.

Object Caching Service for Java Environment

The Object Caching Service for Java environment includes the following:

This section describes these Object Caching Service for Java environment constructs.

Cache Regions

Objects that use the caching service are managed within a cache region. A cache region defines a name space within the cache. Each object within a cache region must be uniquely named, and the combination of the cache region name and the object name must uniquely identify an object. Thus, cache region names must be unique from other region names, and all objects within a region must be uniquely named relative to the region (multiple objects can have the same name if they are within different regions or subregions).

You can define as many regions as you need to support your application. However, most applications only require one region. The Object Caching Service for Java provides a default region; when a region is not specified, objects are placed in the default region.

Attributes may be defined for a region and are then inherited by the objects, subregions, and groups within the region.

Cache Subregions

Objects that use the caching service are managed within a cache region. Specifying a subregion within a cache region defines a child hierarchy. A cache subregion defines a name space within a cache region, or cache subregion. Each object within a cache subregion must be uniquely named, and the combination of the cache region name, the cache subregion name, and the object name must uniquely identify an object.

You can define as many subregions as you need to support your application.

A subregion inherits its attributes from its parent region or subregion unless the attributes are defined when the subregion is defined. A subregion's attributes are inherited by the objects within the subregion. If a subregion's parent region is invalidated or destroyed, the subregion is also invalidated or destroyed.

Cache Groups

A cache group creates an association between objects within the Object Caching Service for Java. Cache groups allow related objects to be manipulated together. Objects are typically associated in a cache group because they need to be invalidated together or they use common attributes. Any set of cache objects within the same region or subregion can be associated using a cache group, which may in turn, include other cache groups.

An Object Caching Service for Java object can only belong to one group at any given time. Before an object can be associated with a group, the group must be explicitly created. A group is defined with a name. A group may have its own attributes, or it may inherit its attributes from its parent region, subregion, or group.

Group names are not used to identify individual objects. A group defines a set or collection of objects that have something in common. A group does not define a hierarchical name space. Object type does not distinguish objects for naming purposes; therefore, a region cannot include a group and a memory object with the same name. Use subregions to define a hierarchical name space within a region.

Groups can contain groups, with the groups having a parent and child relationship. The child group inherits attributes from the parent group.

Cache Object Attributes

Cache object Attributes (Attributes) affect how the Object Caching Service for Java manages objects. Each object type, region, subregion, and group has a set of associated attributes. An object's applicable attributes contain either the default attribute values; the attribute values inherited from the object's parent region, subregion, or group; or the attribute values that you select for the object.

Attributes fall into two categories:

Attributes that must be defined before an object is loaded into the cache. Table 2-1 summarizes these attributes. Each of the attributes shown in Table 2-1 does not have corresponding set or get methods, except the LOADER attribute. Use the Attributes.setFlags() method to set these attributes.
Attributes that can be modified after an object is stored in the cache. Table 2-2 summarizes these attributes.

Note:
Some attributes do not apply to certain types of objects. See Object Types sections in the descriptions in Table 2-1 and Table 2-2.

Using Attributes Defined Before Object Loading

The attributes shown in Table 2-1 must be defined on an object before the object is loaded. These attributes determine an object's basic management characteristics.

The following list shows the methods you can use to set the attributes shown in Table 2-1 (by setting the values of an Attributes object argument).

CacheAccess.defineRegion()
CacheAccess.defineSubRegion()
CacheAccess.defineGroup()
CacheAccess.defineObject()
CacheAccess.put()
CacheAccess.createPool()
CacheLoader.createDiskObject()
CacheLoader.createStream()
CacheLoader.SetAttributes()

Note:
You cannot reset the attributes shown in Table 2-1 by using the CacheAccess.resetAttributes()method.

Table 2-1 Object Caching Service for Java Attributes-Set at Object Creation

Attribute Name	Description
`DISTRIBUTE`	This attribute specifies whether an object is local or distributed. When using the Object Caching Service for Java distributed-caching feature, an object is set as a local object so that updates and invalidations are not propagated to other caches in the site. Object Types: When set on a region, subregion, or a group, this attribute sets the default value for the `DISTRIBUTE` attribute for the objects within the region, subregion, or group, unless the objects explicitly set their own `DISTRIBUTE` attribute. Pool objects are always local, so this attribute does not apply to pool objects. Default Value: All objects are local.
`GROUP_TTL_DESTROY`	This attribute indicates that the associated object, group, or region should be destroyed when the `TimeToLive` expires. Object Types: When set on a region or a group, all the objects within the region or group, and the region, subregion, or group itself are destroyed when the `TimeToLive` expires. Default Value: By default only group member objects are invalidated when the `TimeToLive` expires.
`LOADER`	This attribute specifies the `CacheLoader` associated with the object. Object Types: When set on a region or a group, the specified `CacheLoader` becomes the default loader for the region, subregion, or group, the `LOADER` attribute is individually specified on objects within the region or the group. Default Value: By default, no `LOADER` is set.
`ORIGINAL`	This attribute indicates that the object was created by the application in the cache, rather than loaded from an external source. `ORIGINAL` objects are not removed from the cache when the reference count goes to zero. `ORIGINAL` objects must be explicitly destroyed when they are no longer useful. Object Types: When set on a region or a group, this attribute sets the default value for the `ORIGINAL` attribute for the objects within the region, subregion, or group, unless the objects set their own `ORIGINAL` attribute. Default Value: By default, this attribute is not set.
`REPLY`	This attribute specifies whether objects can expect to receive a reply from remote caches after a request for an object update or invalidation has completed. This attribute should be set when a high level of consistency is required between cached objects. If the `DISTRIBUTE` attribute is not set, or the cache is started in nondistributed mode, `REPLY` is ignored. Object Types: When set on a region or a group, this attribute sets the default value for the `REPLY` attribute for the objects within the region, subregion, or group, unless the objects explicitly set their own `REPLY` attribute. For memory, StreamAccess, and disk objects, this attribute only applies when the `DISTRIBUTE` attribute is set to the value `DISTRIBUTE`. Pool objects are always local, so this attribute does not apply for pool objects. Default Value: By default no reply is sent. When `DISTRIBUTE` is set to local the `REPLY` attribute is ignored.
`SPOOL`	This attribute specifies that a memory object should be stored on disk rather than being lost when the cache system removes it from memory to regain space. This attribute only applies to memory objects. If the object is also distributed, the object can survive the death of the process that spooled it. Local objects are only accessible by the process that spools them, so if the Object Caching Service for Java is not running in distributed mode, the spooled object is lost when the process dies. Note: An object must be serializable to be spooled. If this attribute is set on a region, subregion, or group, all associated objects must implement the `java.io.Serializable` interface. Object Types: When set on a region, subregion, or a group, this attribute sets the default value for the `SPOOL` attribute for the objects within the region, subregion, or group, unless the objects set their own `SPOOL` attribute. Default Value: By default, memory objects are not stored to disk.
`SYNCHRONIZE`	This attribute is used to synchronize updates within multiple threads or at multiple locations within a site. Updates are synchronized by obtaining ownership for objects. Use the `CacheAccess.getOwnership()` method to obtain ownership of an object. Setting the `SYNCHRONIZE` attribute does not prevent a user from reading or invalidating the object. Object Types: When set on a region, subregion, or a group, ownership is applied to the region, subregion, or group as a whole. Pool objects do not use this attribute. Default Value: By default updates are not synchronized.
`SYNCHRONIZE_DEFAULT`	This attribute indicates that all objects in a region, subregion, or group should be synchronized. Each user object in the region, subregion, or group is marked with the `SYNCHRONIZE` attribute. Ownership of the object must be obtained before the object can be loaded or updated. Setting the `SYNCHRONIZE_DEFAULT` attribute does not prevent a user from reading or invalidating objects. Thus, ownership is not required for reads or invalidation of objects that have the `SYNCHRONIZE` attribute set. Object Types: When set on a region, subregion, or a group, ownership is applied to individual objects within the region, subregion, or group. Pool objects do not use this attribute. Default Value: By default updates are not synchronized.

Using Attributes Defined Before or After Object Loading

A set of Object Caching Service for Java attributes can be modified either before or after object loading. Table 2-2 lists these attributes. These attributes can be set using the methods listed in the list shown before Table 2-1, and can be reset using the CacheAccess.resetAttributes() method.

Table 2-2 Object Caching Service for Java Attributes

Attribute Name	Description
`DefaultTimeToLive`	The `DefaultTimeToLive` applies only to regions, subregions, and groups. This attribute establishes a default value for the `TimeToLive` that is applied to all objects individually within the region, subregion, or group. This value can be overridden be setting the `TimeToLive` on individual objects. Object Types: When set on a region, subregion, group, or pool, this attribute applies to all the objects within the region, subregion, group, or pool, unless the objects explicitly set their own `TimeToLive`. Default Value: no automatic invalidation.
`IdleTime`	The `IdleTime` attribute specifies the amount of time an object may remain idle, with a reference count of 0, in the cache before being invalidated. If the `TimeToLive` or `DefaultTimeToLive` attribute is set, the `IdleTime` attribute is ignored. Object Types: When set on a region, subregion, group, or pool, this attribute applies individually to each object within the region, subregion, group, or pool, unless the objects explicitly set `IdleTime`. Default Value: no automatic `IdleTime` invalidation.
`CacheEventListener`	This attribute specifies the `CacheEventListener` associated with the object. Object Types: When set on a region, subregion, or a group, the specified `CacheEventListener` becomes the default `CacheEventListener` for the region, subregion, or group, unless a `CacheEventListener` is specified individually on objects within the region, subregion, or the group. Default Value: By default, no `CacheEventListener` is set.
`TimeToLive`	The `TimeToLive` attribute establishes the maximum amount of time an object remains in the cache before being invalidated. If associated with a region, subregion, or group, all objects in the region, subregion, or group are invalidated when the time expires. If the region, subregion, or group is not destroyed (that is if, `GROUP_TTL_DESTROY` is not set) the `TimeToLive` value is reset. Object Types: When set on a region, subregion, group, or pool, this attribute applies to the region, subregion, group, or pool, as a whole, unless the objects explicitly set their own `TimeToLive`. Default Value: no automatic invalidation.
`Version`	An application may set a `Version` for each instance of an object in the cache. The `Version` is available for application convenience and verification. The caching system does not use this attribute. Object Types: When set on a region, subregion, group, or pool, this attribute applies to all the objects within the region, subregion, group, or pool, unless the objects explicitly set their own `Version`. Default Value: The default `Version` is `0`.

Restrictions on Identifying Objects

Objects are identified by a name that can be any Java object. Usually, the name is represented with a String. The Java object used for the identifying name must override the default Java object equals method, and the default Java object hashcode method. The String class provides implementations for both of these methods.

If you provide an object to use as the Object Caching Service for Java name, you need to provide implementations for the equals and hashcode methods for the object. If the object is distributed, then the Serializable interface must also be implemented.

2 Working with Objects and Attributes