Using Caché with JDBC
Using the Caché Hibernate Dialect
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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:
System Settings
Make the following changes to your system:
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:
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
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>
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:
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;
      }
   }
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
In hibernate.cfg.xml, the entry would be:
   <property name="dialect">
      mySeqDialect.Cache71SequenceDialect
   </property>
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:
    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>
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
You can also increment the table with a standard SQL statement. For example:
   SELECT InterSystems.Sequences_GetNext(sequencename)
      FROM InterSystems.Sequences
      WHERE Name='sequencename'
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.