docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Persisting Java Objects with InterSystems IRIS XEP  /  Using the InterSystems Hibernate Dialect


Persisting Java Objects with InterSystems IRIS XEP
Using the InterSystems Hibernate Dialect
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Java Persistence Architecture (JPA) is the recommended persistence technology for complex object hierarchies in Java projects. InterSystems currently supports JPA 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 include a high performance, customized InterSystems 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 InterSystems IRIS. The instructions assume that the correct versions of both InterSystems IRIS 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 InterSystems dialect class.
The following five configuration properties are required:
A typical entry in hibernate.properties would contain the following lines (change url, username, and password as appropriate for your system)):
  hibernate.dialect org.hibernate.dialect.ISCDialect
  hibernate.connection.driver_class com.intersys.jdbc.CacheDriver
  hibernate.connection.url jdbc:Cache://127.0.0.1:1972/USER/
  hibernate.connection.username _SYSTEM
  hibernate.connection.password SYS
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.ISCDialect
      </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 InterSystems Hibernate dialect:
Support for Sequences
The base class for InterSystems dialects is ISCDialect 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 ISCSequenceDialect extends ISCDialect {
      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.ISCSequenceDialect
In hibernate.cfg.xml, the entry would be:
   <property name="dialect">
      mySeqDialect.ISCSequenceDialect
   </property>
Installing and Using Sequence Dialect Support
To install Hibernate sequence dialect support, load the InterSystems.Sequences project into the namespace that your application will access and compile the 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 InterSystems IRIS 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.