Configure Cacheable Objects and Regions

Next step is to configure cachable objects and regions.

Configue Cacheable Objects Using XML Mapping File

Enabling use of second level cache does not cache each class's object by default. Instead classes that need to be cached are to be marked cacheable in class's mapping (.hbm.xml) file. Following is a sample mapping file Customer.hbm.xml with caching configuration:

<hibernate-mapping>
  <class name="hibernator.BLL.Customer" table="customer" >
    <id column="CustomerID" name="CustomerID" >
      <generator class="assigned"/>
    </id>
    <property name="Address" type="java.lang.String">
      <column name="Address"/>
    </property>
    <property name="Region" type="java.lang.String">
      <column name="Region"/>
    </property>
    <cache usage="read-write"/>
    ...
  </class>
</hibernate-mapping>

Members	Description
Region	Specifies name of second level cache region to be used for this class's objects. If no region is specified, fully qualified class name will be used as region name with default region configurations.
Usage	Specifies caching concurrency strategy to be used for this class. Hibernate allows following three concurrency strategies to be used for caching: read-write nonstrict-read-write read-only

Configure Cacheable Objects Using Hibernate Annotaions

Hibernate introduced a new method to define mappings from version 3.5 and onwards. This method acts as a replacement or an addition to the old XML mapping method. This method is known as Hibernate Annotations.

Following code sample demonstrates how you can use Hibernate Annotations in your application.

@Entity
@Table(name = "Customer")
public class Customer {
   @Id @GeneratedValue
   @Column(name = "CustomerID")
   private int CustomerID;

   @Column(name = "Address")
   private String Address;

   public Customer() {}

   public int getCustomerID() {
      return CustomerID;
   }

   public void setId( int CustomerID ) {
      this.CustomerID = CustomerID;
   }

   public String getAddress() {
      return Address;
   }

   public void setAddress( String Address ) {
      this.Address = Address;
   }
}

Annotations	Description
Entity	This annotation is used to mark a class as an Entity bean. This class should atleast have a package scope.
Table	This annotation allows you define the details of the table that will be used for the purpose of persisting the Entity in the database.
Id	The primary key of your Entity bean is annotated with the @Id annotation. Depending on your table structure this can either be a single field or a combination of multiple fields.
GeneratedValue	This annotation is used for automatically generating primary key (@Id) values.
Column	This annotation is used to specify the properties of the column to which a property or field will be mapped. It has the following attributes: name: used for explicitly specifying the name of the column. length: used for specifying the size of the column that has been used to map a value. nullable: used for specifying a column to be nullable or not based on generated schema. unique: used for specifying a column to be unique.

See Hibernate documentation for further details about Hibernate annotations and caching strategies.

How to Cofigure Cache Regions

Hibernate uses cache regions to store objects. NCache allows cache regions to be configured with different properties. For this purpose NCache has a configuration file named "NCacheHibernate.xml", which contains all region's configurations and other related configurations used by NCache. This file can be placed at the root directory of application or in config folder of NCache Installation directory.

Following is a sample NCacheHibernate.xml configuration file:

<configuration>
<application-config application-id="myapp" enable-cache-exception="true" default-region-name="DefaultRegion" key-case-sensitivity="false">
    <cache-regions>
        <region name="hibernator.BLL.Customer:Customer" cache-name="myPartitionedcache" priority="BelowNormal" expiration-type="Absolute" expiration-period="8"/>
        <region name="CustomRegion" cache-name="myPartitionedcache" priority="default" expiration-type="sliding" expiration-period="8"/>
        <region name="DefaultRegion" cache-name="demoCache" priority="default" expiration-type="none" expiration-period="0" />
    </cache-regions>    
    <database-dependencies>
        <dependency entity-name="hibernator.BLL.Customer" type="oracle" sql-statement="select ContactName from Customer where CustomerID ='?'" cache-key-format="hibernator.BLL.Customer#[pk]" connection-string="Data Source=(DESCRIPTION =(ADDRESS =(PROTOCOL = TCP)(HOST = 20.200.20.180)(PORT = 1521))(CONNECT_DATA =(SERVER = DEDICATED) (SERVICE_NAME = orcl))); User Id=john; Password=alachisoft"/>
    </database-dependencies>
</application-config>
</configuration>

application-config: This section lets you specify configuration for the use of NCache for a particular application. Multiple application configurations can be specified in NCacheHibernate.xml. Any Hibernate application will use one of the specified configuration based on the application-id specified in hibernate's configuration file. Following are the configurable options in application-config section.

Members	Description
application-id	This options lets you specify the unique id for current application-config. This id is used to select appropriate configuration for a particular application.
enable-cache-exception	Identifies whether the exceptions if occurred in NCache will be propagated to Hibernate provider.
default-region-name	Allows the user to specify a default region for the application. If a particular region's configurations are not found default region's configurations will be used. Specified default region's configuration must exist in cache-regions section.
key-case-sensitivity	This option allows the user to specify whether cache keys will be case sensitive or not. This option has to be configured according to the database used. If database is case-sensitive set this option true, otherwise false.
cache-regions	This section lets you configure multiple cache regions for Hibernate application. Each region's configuration is specified in region tag.
region	This tag contains the configurations for one particular region. Following options can be configured for any particular region. name: Each region is identified by its name. Name of the region should be unique. cache-name: This option allows the user to specify NCache's cache name to be used for this region. priority: The priority you want to use for items cached. The possible values are : Default Low BelowNormal Normal Above Normal High NotRemovable expiration-type: This options allows the user to specify the type of expiration for any item in this region. Possible values are absolute/sliding/none. expiration-period: This option allows the user to specify expiration period if absolute/sliding expiration is configured. Its value should be greater than 0.
Database dependencies	This section lets you specify database dependencies for the current Hibernate application. dependency: Each dependency is configured in a dependency tag. Multiple tags can be configured for multiple dependencies. Following options can be configured for each dependency. entity-name: Dependencies are added based on the fully qualified name of classes. This option allows the user to specify name of class for which current dependency is to be added. Any entity can have maximum one dependency. type: This option allows the user to specify database dependency type. Possible values are oracle/oledb. Since NCache provider uses connection string specified in Hibernate's configuration, use dependency type appropriate to connection string. sql-statement: Allows the user to specify sql statement to be used for building NCache's database dependency. cache-key-format: This option is used to configure cache key format for any item of current entity type. Cache key format should include "[pk]" in it, which will be replaced with the primary key of record. cache-key-format may also include "[en]" which will be replaced with entity name. Default value of cache key format is "HibernateNCache:[en] #[pk]". Same cache key format should be used while writing database trigger incase of oledb database dependency. See NCache help for writing database trigger for oledb dependency. composite-key-separator: If the records of current entity have composite key as primary key, cache-key is formed by combining all keys separated by composite-key-separator. composite-key-separator must be of one character length. Its default value is "$".

Configure Cacheable Objects and Regions

Configue Cacheable Objects Using XML Mapping File

Configure Cacheable Objects Using Hibernate Annotaions

How to Cofigure Cache Regions

See Also