6
Advanced Cache Usage

This chapter covers advanced Object Caching Service for Java features, including pool objects and event listeners.

This chapter includes the following sections:

• Working with Pool Objects

• Implementing a Cache Event Listener

Working with Pool Objects

A pool object is a special cache object 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, stored as a static across the entire cache instance, while the objects within the pool object are private objects that the Object Caching Service for Java manages. Users access individual objects within the pool with a check out, using a pool access object, and then return the objects to the pool when they are no longer needed.

This section covers the following topics:

• Creating Pool Objects

• Using Objects from a Pool

• Implementing a Pool Object Instance Factory

Creating Pool Objects

To create a pool object, use CacheAccess.createPool(). The CreatePool() method takes as arguments a PoolInstanceFactory, and an Attributes object, plus two integer arguments. The integer arguments specify the maximum pool size and the minimum pool size. By supplying a group name as an argument to CreatePool(), a pool object is associated with a group.

Attributes, including TimeToLive or IdleTime may be associated with a pool object. These attributes can be applied to the pool object itself, when specified in the attributes set with CacheAccess.createPool(), or they can be applied to the objects within the pool individually.

Using CacheAccess.createPool(), specify minimum and maximum sizes with the integer arguments. The minimum is specified first. It sets the minimum number of objects to create within the pool. The minimum size is interpreted as a request rather than a guaranteed minimum. Objects within a pool object are subject to removal from the cache due to lack of resources, so the pool may decrease the number of objects below the requested minimum value. The maximum pool size puts a hard limit on the number of objects available in the pool.

Note: Pool objects, and the objects within a pool object are always treated as local objects.

See Also: "Implementing a Pool Object Instance Factory" "Cache Object Attributes"

Example 6-1 shows how to create a pool object.

Example 6-1 Creating a Pool Object

import oracle.ias.cache.*;

   try
   {
      CacheAccess cacc = CacheAccess.getAccess("Stock-Market");
      Attributes  attr = new Attributes();
      QuoteFactory poolFac = new QuoteFactory();

      // set IdleTime for an object in the pool to three minutes
      attr.setIdleTime(180);
      // create a pool in the "Stock-Market" region with a minimum of
      // 5 and a maximum of 10 object instances in the pool
      cacc.createPool("get Quote", poolFac, attr, 5, 10);
      cacc.close();
   }  
   catch(CacheException ex)  
   {
           // handle exception
   }
}

Using Objects from a Pool

To access objects in a pool, use a PoolAccess object. The PoolAccess.getPool() static method returns a handle to a specified pool. The PoolAccess.get() method returns an instance of an object from within the pool (this checks out an object from the pool). When an object is no longer needed, return it to the pool, using the PoolAccess.returnToPool() method, which checks the object back into the pool. Finally, call the PoolAccess.close() method when the pool handle is no longer needed.

Example 6-2 shows the calls required to create a PoolAccess object, check an object out of the pool, and then check the object back in and close the PoolAccess object.

Example 6-2 Using a PoolAccess Object

PoolAccess pacc = PoolAccess.getPool("Stock-Market", "get Quote");
//get an object from the pool
GetQuote  gq = (GetQuote)pacc.get();
// do something useful with the gq object
// return the object to the pool
pacc.returnToPool(gq);   
pacc.close();

Implementing a Pool Object Instance Factory

The Object Caching Service for Java instantiates and removes objects within a pool, using an application-defined factory object, a PoolInstanceFactory. The PoolInstanceFactory is an abstract class with two methods that you must implement, createInstance() and destroyInstance().

The Object Caching Service for Java calls createInstance() to create instances of objects being accumulated within the pool. The Object Caching Service for Java calls destroyInstance() when an instance of an object is being removed from the pool (object instances from within the pool are passed into destroyInstance()).

The size of a pool object, that is the number of objects within the pool, is managed using these PoolInstanceFactory() methods. The system decreases or increases the size and number of objects in the pool, based on demand, and based on the values of the TimeToLive or IdleTime attributes. Example 6-3 shows the calls required when implementing a PoolInstanceFactory.

Example 6-3 Implementing Pool Instance Factory Methods

import oracle.ias.cache.*;
   public class MyPoolFactory implements PoolInstanceFactory 
   {
       public Object createInstance()
      {
         MyObject obj = new MyObject();
         obj.init();
         return obj;
       }
       public void destroyInstance(Object obj)
       {
           ((MyObject)obj).cleanup();
       }
   }

Implementing a Cache Event Listener

There are a number of events that can occur in the life cycle of a cached object, including object creation and object invalidation. This sections shows how an application can be notified when cache events occur.

To receive notification of an object's creation, implement event notification as part of the cacheLoader. For notification of invalidation or updates, implement a CacheEventListener and associate the CacheEventListener with an object, group, region, or subregion using Attributes.setCacheEventListener().

CacheEventListener is an interface that extends java.util.EventListener. The cache event listener provides a mechanism to establish a callback method that is registered, and then executes when the event occurs. In the Object Caching Service for Java, the event listener executes when a cached object is invalidated or updated.

An event listener is associated with a cached object, group, region, or subregion. If an event listener is associated with a group, region, or subregion, the listener only runs when the group, region, or subregion itself is invalidated. Invalidating a member does not trigger the event. Attributes.setCacheEventListener() takes a boolean argument, that if true, applies the event listener to each member of the region, subregion, or group, rather than to the region, subregion, or group itself. In this case, the invalidation of an object within the region, subregion, or group triggers the event.

The CacheEventListener interface has one method, handleEvent(). This method takes a single argument, a CacheEvent object that extends java.util.EventObject. This object has two methods getID(),which returns the type of event (OBJECT_INVALIDATION or OBJECT_UPDATED), and getSource(), which returns the object being invalidated. For group objects, the getSource() method returns the name of the group.

The handleEvent() method is executed in the context of a background thread that the Object Caching Service for Java manages. Avoid using JNI code in this method, as the expected thread context may not be available.

Example 6-4 shows how a CacheEventListener is implemented and associated with an object or a group.

Example 6-4 Implementing a CacheEventListener

import oracle.ias.cache.*;
   // A CacheEventListener for a cache object
   class MyEventListener implements
   CacheEventListener  {

       public void handleEvent(CacheEvent ev)
       {
          MyObject obj = (MyObject)ev.getSource();
          obj.cleanup();
        }

       // A CacheEventListener for a group object
       class MyGroupEventListener implements CacheEventListener {
       public void handleEvent(CacheEvent ev) 
       {
          String groupName = (String)ev.getSource();
          app.notify("group " + groupName + " has been invalidated");

       }
   }

Use the Attributes.listener attribute to specify the CacheEventListener for a region, subregion, group, or object.

Example 6-5 shows how to set a cache event listener on an object. Example 6-6 shows how to set a cache event listener on a group.

See Also: "Defining and Using Cache Objects" for information on working with attributes

Example 6-5 Setting a Cache Event Listener on an Object

import oracle.ias.cache.*;

   class YourObjectLoader extends CacheLoader
   {
      public YourObjectLoader () {
      }

      public Object load(Object handle, Object args) {
         Object obj = null;
         Attributes attr = new Attributes();    
         MyEventListener el = new MyEventListener();
         attr.setCacheEventListener(CacheEvent.OBJECT_INVALIDATED, el);

         // your implementation to retrieve or create your object

         setAttributes(handle, attr);
         return obj;
    }      
}

Example 6-6 Setting a Cache Event Listener on a Group

import oracle.ias.cache.*;
try    
{
   CacheAccess cacc = CacheAccess.getAccess(myRegion);  
   Attributes attr = new Attributes ();

   MyGroupEventListener listener = new MyGroupEventListener();   
   attr.setCacheEventListener(CacheEvent.OBJECT_INVALIDATED, listener);

   cacc.defineGroup("myGroup", attr);
   //....
   cacc.close();

}catch(CacheException ex)      
{
   // handle exception
}