4
Disk Cache and StreamAccess Objects

This chapter shows you how to work with the disk cache for Object Caching Service for Java, and includes descriptions of disk objects and StreamAccess objects. Disk objects are objects that are stored on a local disk in a file, and the application using the Object Caching Service for Java accesses the file directly. StreamAccess objects are objects that are accessed as a stream (loaded as an OutputStream and read as an InputStream).

This chapter covers the following topics:

• Working with Disk Objects

• Working with StreamAccess Objects

Working with Disk Objects

The Object Caching Service for Java can manage objects on disk as well as in memory.

This section covers the following topics:

• Configuring Properties for Using the Disk Cache

• Local and Distributed Disk Cache Objects

• Adding Objects to the Disk Cache

Configuring Properties for Using the Disk Cache

To configure the Object Caching Service for Java to use a disk cache, set the value of the diskPath configuration property in the OCS4J.properties file.

Setting the diskPath Configuration Property

To configure the Object Caching Service for Java to use a disk cache, the diskPath property in the configuration properties file should be set to the path of the root directory for the disk cache. The default value for diskPath is null, which specifies that the Object Caching Service for Java should not enable the disk cache.

Note: when operating in distributed mode. To share disk cache files, all caches cooperating in the same cache system must specify values for the diskPath property that represent the same physical disk. However, the values specified for the diskPath do not need to be the same. If you configure the diskPath properties to represent different locations on the same or different physical disks, the disk cache objects are not shared.

See Also: "Setting Cache Configuration Properties"

Local and Distributed Disk Cache Objects

This section covers the following topics:

• Local Objects

• Distributed Objects

Local Objects

When operating in local mode, all objects are treated as local objects (even when the DISTRIBUTE attribute is set for an object). In local mode, all objects in the disk cache are only visible to the Object Caching Service for Java cache that loaded them, and they do not survive after process termination. In local mode, objects stored in the disk cache are lost when the process using the cache dies.

Distributed Objects

When operating in distributed mode, disk cache objects are shared by all caches that have access to the file system hosting the disk cache. This configuration allows for better utilization of disk resources and allows disk objects to persist beyond the life of the Object Caching Service for Java process. Distributed memory objects are not shared by all caches since individual copies of each memory object reside in the individual caches across the system.

Objects stored in the disk cache are identified using the concatenation of the path specified in the diskPath configuration property and an internally generated String representing the remaining path to the file. Thus, caches that share a disk cache can have a different directory structure, as long as the diskPath represents the same directory on the physical disk and is accessible to the Object Caching Service for Java processes.

If a memory object that is saved to disk is also distributed, the memory object can survive the death of the process that spooled it.

See Also: "Automatically Adding Objects" for information on using the SPOOL attribute

Adding Objects to the Disk Cache

There are several ways to use the disk cache with the Object Caching Service for Java, including:

• Automatically Adding Objects

• Explicitly Adding Objects

• Using Objects That Only Reside on Disk Cache

Automatically Adding Objects

The Object Caching Service for Java automatically adds certain objects to the disk cache. Such objects may reside either in the memory cache or in the disk cache. If an object in the disk cache is needed, it is copied back to the memory cache. The action of spooling to disk occurs when the Object Caching Service for Java determines that it requires free space in the memory cache. The Object Caching Service for Java automatically moves objects from the memory cache to the disk cache in two cases.

• When space is running out in the memory cache, the Object Caching Service for Java searches through the cache, looking for memory objects that are not currently accessed. These memory objects may be removed from the cache. If the memory object is defined with the SPOOL attribute set, the memory object is written to disk before it is removed. Spooling saves the memory object to the disk cache, and avoids re-creating the object when or if it is needed again. You should set the SPOOL attribute for objects that are expensive to create, especially if the time required to create the object is greater than the cost of loading the object from disk.

• StreamAccess objects are automatically loaded to disk cache. StreamAccess objects give the Object Caching Service for Java latitude as to how the object is accessed. Smaller StreamAccess objects can be accessed from memory or the disk cache, while larger StreamAccess objects are streamed directly from disk. The Object Caching Service for Java determines how to store the StreamAccess object based on the size of the object and the capacity of the cache.

  See Also: "Cache Object Attributes" and "Working with StreamAccess Objects"

Explicitly Adding Objects

In some situations, you may want to force one or more objects to be written to the Object Caching Service for Java disk cache. Using the CacheAccess.save() method, a region, subregion, group, or object is synchronously written to the disk cache (if the object or objects are already in the disk cache, they are not written again).

Note: Using CacheAccess.save() saves an object to disk even when the SPOOL attribute is not set for the object.

Calling CacheAccess.save() on a region, subregion, or group saves all the objects within the region, subregion, or group to the disk cache. During a CacheAccess.save() method call, if an object is encountered that cannot be written to disk, either because it is not serializable, or for other reasons, the event is recorded in the Object Caching Service for Java log and the save operation continues with the next object.

Using Objects That Only Reside on Disk Cache

Objects that you only access directly from disk cache are loaded into the disk cache by calling CacheLoader.createDiskObject() from the CacheLoader.load() method. The createDiskObject() method returns a File object that the application can use to load the disk object. If the disk object's attributes are not defined for the disk object, set them using the createDiskObject() method. The system manages local and distributed disk objects differently; the determination of local or distributed is made when the system creates the object, based on the specified attributes.

Note: If you want to share a disk cache object between distributed caches in the same cache system, you must define the DISTRIBUTE attribute when the disk cache object is created. This attribute cannot be changed for the disk cache object after the object is created.

When CacheAccess.get() is called on a disk object, the full path name to the file is returned, and the application can open the file, appropriate to its needs.

Disk objects are stored on a local disk and 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 the mode the Object Caching Service for Java is running in, either distributed, or local).

Example 4-1 shows a loader object that loads a disk object into the cache.

See Also: "Implementing a CacheLoader" and "Cache Object Attributes"

Example 4-1 Creating a Disk Object in a CacheLoader

import oracle.ias.cache.*;

class YourObjectLoader extends CacheLoader
{
   public Object load(Object handle, Object args) {
      File file;
      FileOutputStream = out;
      Attributes attr = new Attributes();

      attr.setFlags(Attributes.DISTRIBUTE);
      try 
      {
         file = createDiskObject(handle, attr);
         out = new FileOutputStream(file);

         out.write((byte[])getInfofromsomewhere());
         out.close();
     }
     catch (Exception ex) {
       // translate exception to CacheException, and log exception
         throw exceptionHandler("exception in file handling", ex)
      }
      return file;
      }
   }

Example 4-2 shows application code that uses an Object Caching Service for Java disk object. This example assumes the region named "Stock-Market" is already defined with the "YourObjectLoader" loader set up in Example 4-1 as the default loader for the region.

Example 4-2 Application Code That Uses a Disk Object

import oracle.ias.cache.*;

try
{
   FileInputStream in;
   File file;
   String filePath;
   CacheAccess cacc = CacheAccess.getAccess("Stock-Market");

   filePath = (String)cacc.get("file object");
   file = new File(filePath);
   in = new FileInputStream(filePath);
   in.read(buf);

// do something interesting with the data
   in.close();
   cacc.close();
}
catch (Exception ex)
{
// handle exception
}

Working with 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. Smaller StreamAccess objects can be accessed from memory or from the disk cache, while larger StreamAccess objects are streamed directly from disk. The Object Caching Service for Java automatically determines where to access the StreamAccess object based on the size of the object and the capacity of the cache.

The user is always presented with a stream object, an InputStream for reading and an OutputStream for writing, regardless of whether the object is in a file or in memory. The StreamAccess object allows the Object Caching Service for Java user to always access the object in a uniform manner, without regard to object size or resource availability.

Creating a StreamAccess Object

To create a StreamAccess object, call the CacheLoader.createStream() method from the CacheLoader.load() method when the object is loaded into the cache. The createStream() method returns an OutputStream object. The OutputStream object can be used to load the object into the cache.

If the attributes have not already been defined for the object, they should be set using the createStream() method. The system manages local and distributed disk objects differently; the determination of local or distributed is made when the system creates the object, based on the attributes.

Note: If you want to share a StreamAccess object between distributed caches in the same cache system, you must define the DISTRIBUTE attribute when the StreamAccess object is created. This attribute cannot be changed after the object is created.

Example 4-3 shows a loader object that loads a StreamAccess object into the cache.

Example 4-3 Creating a StreamAccess Object in a Cache Loader

import oracle.ias.cache.*;

class YourObjectLoader extends CacheLoader
{
   public Object load(Object handle, Object args) {
     OutputStream = out;
     Attributes attr = new Attributes();
     attr.setFlags(Attributes.DISTRIBUTE);

     try 
     {
        out = createStream(handle, attr);
        out.write((byte[])getInfofromsomewhere());
     }
     catch (Exception ex) {
        // translate exception to CacheException, and log exception
        throw exceptionHandler("exception in write", ex)
     }
     return out;
     }
}