Defining Your Environment

One of the main features of the Java Object Cache is the ability to control how an object in the cache is managed. This is done by defining the environment in which objects are managed. The environment includes defining a private namespace within the cache, a region, defining object associations or object groups and defining the attributes of an object in the cache. The primary methods for setting up a cache environment are CacheAccess.defineRegion(), CacheAccess.defineSubRegion(), CacheAccess.defineGroup(), and CacheAccess.defineObject().

Defining a Region/Sub-Region

All objects within the cache are stored in the context of a region. A region defines a namespace within the cache. All objects within a region must be uniquely named.

To create a region named "Stock-Market", you would invoke the static method defineRegion of CacheAccess. To access objects in the region use the getAccess method to obtain an instance of a CacheAccess object. Attributes may be defined for a region when it is defined. The attributes defined will be inherited by all objects in the region. See the chapter on Cache Object Attributes for details.

import oracle.ias.cache.*;

  Attributes attr = new Attributes();
  attr.setFlags(Attributes.DISTRIBUTE); // make all objects in the region distributed

  try
  {

    // define a region with defined attributes
    CacheAccess.defineRegion("Stock-Market", attr);
    // OR
    // define a region using default attributes
    CacheAccess.defineRegion("Stock-Market");

    CacheAccess cacc = CacheAccess.getAccess("Stock-Market");

    // do something useful with the objects in the region

  }
  catch(CacheException ex)
  {

    // handle exception
  }

  try
  {

    // define a sub-region with defined attributes
    cacc.defineSubRegion("Oracle", attr);
    // OR
    // define a sub-region while inheriting attributes
    cacc.defineSubRegion("Oracle");

    // obtain access to sub-region
    CacheAccess cacc2 = cacc.getSubRegion("Oracle");

    // do something useful with the objects in the sub-region

  }
  catch(CacheException ex)
  {

    // handle exception

  }

  try
  {

    // define and obtain access to Month1
    CacheAccess cacc3 = CacheAccess.getAccess("Stock-Market/Oracle/Q1/Month1", attr, true);
    // OR
    // define and obtain access to Month1 while inheriting attributes
    CacheAccess cacc3 = cacc2.getSubRegion("Q1/Month1", null);
    // OR
    // define and obtain access to Month1 with defined attributes
    CacheAccess cacc3 = cacc2.getSubRegion("Q1/Month1", attr);

    // define and obtain access to region with defined attributes
    CacheAccess cacc4 = CacheAccess.getAccess("This/Is/My/Region", attr, false);

    // do something useful with the objects in the sub-region

  }
  catch(CacheException ex)
  {

    // handle exception

  }

At times it is useful to create an association between two or more objects within the cache. Objects are typically associated because they will be invalidated together or because they have a common set of attributes. To provide this functionality the cache has the concept of a "group." Any set of cache objects within the same region can be associated using a group (including other groups). Before an object can be associated with a group, the group must be defined. A group is defined with a name and can be defined with its own attributes or inherit the attributes from the group or region it is associated with.

To define a group named "NYSE" in the existing region, "Stock-Market", you would get access to the region then call defineGroup.

import oracle.ias.cache.*;

  try
  {

    CacheAccess cacc = CacheAccess.getAccess("Stock-Market");
    // define the group without attributes
    cacc.defineGroup("NYSE");
    // OR

    // set the default idle time for object
    // in the group to 2 minutes
    Attributes attr = new Attributes();

    attr.setIdleTime(120);

    // define the group with attributes
    cacc.defineGroup("NYSE", attr);

    cacc.defineGroup("Pending IPO", "NYSE");
    // OR
    cacc.defineGroup("Pending IPO", "NYSE", attr);

    cacc.put("CPB", "NYSE", "Day high $27, day low $26.5", attr);

    cacc.get("loaded object", "NYSE");
    // OR
    cacc.get("loaded object", "NYSE", args);

    cacc.close();

  }
  catch (CacheException ex)
  {

    // handle exception

  }

It is often useful to describe to the Caching service how an individual object is to be managed within the cache before the object is loaded into the cache. This can be done by using the CacheAccess.defineObject() method. defineObject is used to associate attributes with an object. Attributes can include such information as how to load the object into the cache, whether the object is local or distributed, how long the object should remain in the cache before being invalidated, etc. If attributes are not defined for an object, the default attributes set for the region or group the object is associated with will be used. Attributes may also be set in the CacheLoader.load() method using the CacheLoader.setAttributes(), CacheLoader.createStream(), CacheLoader.createDiskObject() methods or with CacheAccess.put().

import oracle.ias.cache.*;

  try
  {

    CacheAccess cacc = CacheAccess.getAccess("Stock-Market");

    MyLoader loader = new MyLoader();

    // set the default idle time and the loader for the object
    // and indicate the object is distributed
    Attributes attr = new Attributes();
    attr.setLoader(loader);
    attr.setFlags(Attributes.DISTRIBUTE);

    attr.setIdleTime(120); // in the group to 2 minutes

    // define the objects attributes
    cacc.defineObject("ORCL", attr);

    // object is loaded using the defined loader if not already in the cache
    result = (String)cacc.get("ORCL");

    // since the object is being explicitly "put" into the cache
    // the loader is not defined
    attr.setLoader(null);
    cacc.put("ORCL", "Day high $27, day low $26.5", attr);

    result = (String)cacc.get("ORCL");

    cacc.close();
  }
  catch (CacheException ex)
  {

    // handle exception

  }