Configure Cacheable Objects and Regions

Next step is to configure cacheable objects and regions.

Configure Cacheable Objects Using XML Mapping File

Enabling the use of second level cache does not cache each class's object by default. Instead classes that need to be cached are marked cacheable as a part of class 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 the name of the second level cache region to use for this class's objects. If no region is specified, a fully qualified class name will be used as the region name with default region configurations.
Usage Specifies caching concurrency strategy to use for this class. Hibernate allows the following three concurrency strategies 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 marks a class as an Entity Bean. This class should at least have a package scope.
    Table This annotation allows you to define the details of the table to use 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 the primary key (@Id) values.
    Column This annotation specifies 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 the Hibernate documentation for further details about Hibernate annotations and caching strategies.

    How to Configure 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 the region's configurations and other related configurations used by NCache. You can place this file in the root directory of the application or in the config folder of the 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="demoClusteredCache" priority="BelowNormal" expiration-type="Absolute" expiration-period="8"/>
        <region name="CustomRegion" cache-name="demoClusteredCache" 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.40)(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 the 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 configurations specified based on the application-id specified in Hibernate's configuration file. Following are the configurable options in the 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 the 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-region 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 to 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. The region's name should be unique.

    cache-name: This option allows the user to specify NCache's cache name to use for this region.

    priority: The priority you want to use for items cached. The possible values are :
  • Default
  • Low
  • BelowNormal
  • Normal
  • AboveNormal
  • High
  • NotRemovable

    expiration-type: This options allows the user to specify the type of expiration for any item in this region. The 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. You can configure multiple tags for multiple dependencies. The following options can be configured for each dependency.

    entity-name: Dependencies are added according to the fully qualified name of classes. This option allows the user to specify name of class for which to add the current dependency. Any entity can have at 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 use for building NCache's database dependency.

    cache-key-format: This option configures the 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. It may also include "[en]" which will be replaced with the entity name. The 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 its primary key, cache-key is formed by combining all keys separated by the composite-key-separator. Composite-key-separator must be of one character length. Its default value is "$".

    See Also

    Initialize Cache
    Add/Update in Cache
    Hibernate First Level Cache
    Configure Hibernate Application
    Use Query Caching