Skip to main content
Previous section

Hibernate Support

The InterSystems Hibernate Dialect is an implementation of the Hibernate dialect interface. Since every vendor’s implementation of SQL is slightly different, the dialect interface allows vendors to create custom Hibernate mappings for a specific database. Vendor-provided dialect implementations are distributed as part of Hibernate.

This chapter provides technical details about the InterSystems Hibernate Dialect. The following topics are discussed:

Hibernate and the InterSystems Hibernate Dialect

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.

The InterSystems Hibernate Dialect is an implementation of the Hibernate dialect interface. 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.

When to Use Hibernate

Hibernate provides the infrastructure to persist objects to relational tables. Essentially, it is a wrapper around JDBC that allows you to focus on working with objects while transparently handling conversion between objects and tables in SQL queries. Hibernate can be used in most environments, but it is not always the best option. Here are some considerations to bear in mind:

  • Hibernate is helpful when you have a complex but static object model. You must know what your data looks like and how the classes interact before you map them to your InterSystems IRIS table model.

  • Since Hibernate objects are cached, other applications should never interact with the data while Hibernate is accessing it. If you are working in an environment with real-time data that must remain accessible to other applications, you should consider XEP (see Persisting Java Objects with InterSystems XEP) as a possible alternative.

  • Hibernate is good for common CRUD operations with simple querying, but more complex queries may be easier to write, or more efficient, using JDBC directly.

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.

Requirements

The following software must be installed on your system:

  • InterSystems IRIS®

  • Hibernate 5.2 or 5.3. Hibernate can be downloaded from www.hibernate.org.

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

Directories

The instructions in this chapter refer to the following directories:

  • <install-dir> — the InterSystems IRIS installation directory. To locate <install-dir> in your instance of InterSystems IRIS, open the InterSystems terminal and issue the following command:

       write $system.Util.InstallDirectory()
    Copy code to clipboard

    See “Installation Directory” in the Installation Guide for system-specific information on the location of <install-dir>.

  • <hibernate_root> — your Hibernate installation directory.

System Settings

Make the following changes to your system:

  • intersystems-jdbc-3.0.0.jar File

    The intersystems-jdbc-3.0.0.jar file contains the InterSystems JDBC driver. If you haven't already done so, copy the appropriate version of intersystems-jdbc-3.0.0.jar from the default location to <hibernate_root>\lib.

  • 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 InterSystems dialect class.

The following five configuration properties are required:

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

       org.hibernate.dialect.InterSystemsIRISDialect
    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.

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

       com.intersystems.jdbc.IRISDriver
    Copy code to clipboard

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

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

  • password — Password for the InterSystems IRIS namespace (default is SYS).

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

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

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

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.InterSystemsIRISDialect
  hibernate.connection.driver_class com.intersystems.jdbc.IRISDriver
  hibernate.connection.url jdbc:IRIS://127.0.0.1:51773/USER/
  hibernate.connection.username _SYSTEM
  hibernate.connection.password SYS
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.InterSystemsIRISDialect
      </property>
      <property name="connection.driver_class">
        com.intersystems.jdbc.IRISDriver</property>
      <property name="connection.username">_SYSTEM</property>
      <property name="connection.password">SYS</property>
      <property name="connection.url">
        jdbc:IRIS://127.0.0.1:51773/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.

Dialect File Locations

The InterSystems Hibernate dialect consists of four files that should be located as follows

(where <hibernate> is hibernate-orm\hibernate-core\src\main\java\org\hibernate):

  • InterSystemsIRISDialect.java in <hibernate>\dialect\

  • IntersystemsIRISIdentityColumnSupport.java in <hibernate>\dialect\identity\

  • InterSystemsIRISSQLExceptionConversionDelegate.java in <hibernate>\exception\internal\

  • InterSystemsIRISJoinFragment.java in <hibernate>\sql\

If you do not already have these files, contact the InterSystems Worldwide Response Center (WRC) for download information.