Skip to main content
Previous section   Next section

Using the Caché Hibernate Dialect

Java Persistence Architecture (JPA) is the recommended persistence technology for complex object hierarchies in Java projects. Caché currently supports JPA 1.0 and 2.0 via the Hibernate implementations of the JPA specifications.

Hibernate is an open source framework from JBoss that acts as a wrapper around JDBC to provide object/relational mapping (ORM) services for relational databases. Hibernate provides a vendor-neutral persistence service, which may be a requirement for some projects.

Since every vendor’s implementation of SQL is slightly different, Hibernate includes vendor-provided "dialects" that customize its mappings to specific databases. Current Hibernate distributions (3.2.1GA and higher) include a high performance, customized Caché dialect class.

Requirements

This document assumes that the following software is installed on your system:

  • Caché 2010.2 or higher

  • Hibernate 3.2.1GA or higher (any version that includes the Caché dialect extensions). Hibernate can be downloaded from www.hibernate.org.

  • A supported version of the Java JDK (see “Supported Java Technologies” in the online InterSystems Supported Platforms document for this release).

Installation and Configuration

This section provides instructions for setting up your system to use Hibernate with Caché. The instructions assume that the correct versions of both Caché and Hibernate are installed and operational.

Directories

The instructions in this chapter refer to the following directories:

  • <install-dir> — the Caché installation directory (for the location of <install-dir> on your system, see “Default Caché Installation Directory” in the Caché Installation Guide).

  • <hibernate_root> — the Hibernate installation directory (C:\hibernate-3.2 by default).

System Settings

Make the following changes to your system:

  • cache-jdbc-2.0.0.jar File

    The cache-jdbc-2.0.0.jar file contains the Caché JDBC driver. If you haven't already done so, copy the appropriate version of cache-jdbc-2.0.0.jar (see “The Caché Java Class Packages”) from the default location to:

    <hibernate_root>\lib\cache-jdbc-2.0.0.jar.

  • Java Classpath

    Make sure the following items are on your Java classpath:

    • The jar files from <hibernate_root>\lib

    • The directory or directories where the Hibernate configuration files (hibernate.properties and hibernate.cfg.xml) are kept. By default, both files are in:

      <hibernate_root>\etc

Hibernate Configuration

In the Hibernate configuration files (either hibernate.properties or hibernate.cfg.xml), specify the connection information for your database, and the name of the Caché dialect class.

The following five configuration properties are required:

  • dialect — The fully qualified name of the Caché dialect class. The base dialect class is:

       org.hibernate.dialect.Cache71Dialect
    Copy code to clipboard

    You can use a custom dialect class derived from this base class if you need to enable support for the Hibernate primary key generator classes (see “Support for Sequences”).

  • driver_class — The fully qualified name of the Caché JDBC driver:

       com.intersys.jdbc.CacheDriver
    Copy code to clipboard

    The JDBC driver is contained in the cache-jdbc-2.0.0.jar file (see “System Settings” for details).

  • username — Username for the Caché namespace you want to access (default is _SYSTEM).

  • password — Password for the Caché namespace (default is SYS).

  • url — The URL for the Caché JDBC driver. The format for the URL is:

       jdbc:Cache://<host>:<port>/<namespace>
    Copy code to clipboard

    where <host> is the IP address of the machine hosting Caché, <port> is the SuperServer TCP port of your Caché instance, and <namespace> is the namespace that contains your Caché database data (see Defining a JDBC Connection URL for more details).

A typical entry in hibernate.properties would contain the following lines:

  hibernate.dialect   org.hibernate.dialect.Cache71Dialect
  hibernate.connection.driver_class   com.intersys.jdbc.CacheDriver
  hibernate.connection.username   _SYSTEM
  hibernate.connection.password   SYS
  hibernate.connection.url   jdbc:Cache://127.0.0.1:1972/USER
Copy code to clipboard

The following example shows the same information as it would appear in hibernate.cfg.xml:

  <hibernate-configuration>
    <session-factory>
      <property name="dialect">
        org.hibernate.dialect.Cache71Dialect
      </property>
      <property name="connection.driver_class">
        com.intersys.jdbc.CacheDriver</property>
      <property name="connection.username">_SYSTEM</property>
      <property name="connection.password">SYS</property>
      <property name="connection.url">
        jdbc:Cache://127.0.0.1:1972/USER
      </property>
    </session-factory>
  </hibernate-configuration>
Copy code to clipboard
Caution:

If the same property is set in both hibernate.properties and hibernate.cfg.xml, Hibernate will use the value from hibernate.cfg.xml.

Supported Features

Using Hibernate with SQL

The following SQL features are not supported by the Caché Hibernate dialect:

  • The longvarbinary and longvarchar types are not supported in a WHERE clause.

  • Row valued expressions such as WHERE (A,B,C)=(1,2,3) are not supported.

Support for Sequences

The base class for Caché dialects is Cache71Dialect in package org.hibernate.dialect. You can extend this class to enable support for the optional Hibernate primary key generator methods. This support is required if you want to enable Oracle-style sequences or use other non-standard generation methods.

Adding the Extended Class

Create the following class:

   public Cache71SequenceDialect extends Cache71Dialect {
      public boolean supportsSequences() {
         return true;
      }
   }
Copy code to clipboard

Specify the fully qualified name of your new class in the dialect property of your hibernate.properties or hibernate.cfg.xml file (see the examples in “Hibernate Configuration”). For example, if your package was named mySeqDialect, the entry in hibernate.properties would be:

  hibernate.dialect  mySeqDialect.Cache71SequenceDialect
Copy code to clipboard

In hibernate.cfg.xml, the entry would be:

   <property name="dialect">
      mySeqDialect.Cache71SequenceDialect
   </property>
Copy code to clipboard
Installing and Using Sequence Dialect Support

To install Hibernate sequence dialect support, load the CacheSequences project into the namespace that your application will access:

  1. In Studio, change to the namespace your application will access.

  2. From the Studio menu, select Tools > Import Local...

  3. In the file dialog, open the CacheSequences.xml project file:

    <hibernate_root>/etc/CacheSequences.xml.

    Studio will load and compile the Caché InterSystems.Sequences class.

The sequence generator to be used is specified in the id property of your Hibernate mapping. Oracle-style sequences can be generated by specifying sequence or seqhilo. If native is specified, the identity generator will be used when Caché is the underlying database. For more information on these classes, see the Hibernate reference documentation (specifically, the id section in chapter 5, Basic O/R Mapping).

The following example demonstrates the use of a sequence generator in a Hibernate mapping:

   <id name="id" column="uid" type="long" unsaved-value="null">
      <generator class="seqhilo">
         <param name="sequence">EVENTS_SEQ</param>
         <param name="max_lo">0</param>
      </generator>
   </id>
Copy code to clipboard

The sequence classes maintain a table of counters that can be incremented by calling the stored procedure just before performing the insert. For example:

   call InterSystems.Sequences_GetNext("Name")
   // perform the insert here
Copy code to clipboard

You can also increment the table with a standard SQL statement. For example:

   SELECT InterSystems.Sequences_GetNext(sequencename)
      FROM InterSystems.Sequences
      WHERE Name='sequencename'
Copy code to clipboard

The table can be queried as table InterSystems.Sequences. The data is actually stored in global ^InterSystems.Sequences. You can make the sequences system-wide by mapping ^InterSystems.Sequences* to a location that is common to all your applications.