Hibernate and solidDB

News


Abstract

This article describes how to get started using Hibernate with IBM solidDB. It also includes the solidDB dialect for Hibernate (SolidSQLDialect.jar), as well as instructions on how to build and run a sample application.

Content



1 Introduction
Hibernate is an open source persistence and query framework that provides object-relational mapping of POJOs (Plain Old Java Objects) to relational database tables, as well as data query and retrieval capabilities. Hibernate enables you to write database applications without writing SQL statements.

The mapping between objects and the solidDB database is facilitated with a solidDB dialect for Hibernate (included at the end of this article). The dialect enables the Hibernate library to communicate with solidDB. It contains information about the mapping of Java types to SQL types and the functions the solidDB database supports with Hibernate. In general, a Java class maps to a database table and a Java type maps to an SQL data type.

Hibernate eases migration between different databases: you can write an application for a database that will in principle work with all databases supported by Hibernate, that is, with any database that provides a dialect.


2 Using Hibernate with solidDB

To use hibernate with solidDB, you first configure your environment so that Hibernate can connect to solidDB. Next you need to create mappings to define the correlation between Java objects and database tables. You can then use the Hibernate API to fully utilize the features available to the applications.

The sections below highlight the main steps for setting up Hibernate with solidDB. For a more detailed description of how to build Hibernate applications, see the documentation provided at http://www.hibernate.org/ or explore the sample application described in section Sample application below.

2.1 Configuring your environment

  1. Add the following to the build path of your application:
    - Hibernate jar files
    - SolidSQLDialect.jar
    - SolidDriver2.0.jar


  2. Define the configuration properties for Hibernate to connect to solidDB:

    You need to provide at least the properties shown in the table below.
    Property Value
    connection.url solidDB JDBC URL

    Syntax:
    jdbc:solid://<hostname>:<port>

    Example:
    jdbc:solid://localhost:2315
    connection.username database user name
    connection.password database password
    connection.driver_class solid.jdbc.SolidDriver
    dialect org.hibernate.dialect.SolidSQLDialect

    The connection property elements contain the necessary configuration for the JDBC connection. The dialect property element specifies that Hibernate generates a SQL variant specific to solidDB.

    You can define the properties in three different ways:
    A. XML configuration file
    Typically the properties are provided in an XML configuration file.
    By default, the method configure() or configure(String filename) attemps to read a file named hibernate.cfg.xml. You can also specify a different file name.

    Example:
    <property name="connection.url">jdbc:solid://localhost:2315/dba</property>
    <property name="connection.username">dba</property>
    <property name="connection.password">dba</property>
    <property name="connection.driver_class">solid.jdbc.SolidDriver</property>
    <property name="dialect">org.hibernate.dialect.SolidSQLDialect</property>

    B. Configuration class
    The configuration properties can also be specified using Java methods.

    Example:
           Configuration conf = new Configuration().configure();
           conf.setProperty("hibernate.dialect", "org.hibernate.dialect.SolidSQLDialect");
           conf.setProperty("hibernate.connection.url", "jdbc:solid://localhost:2315/dba/dba");
           conf.setProperty("hibernate.connection.username", "dba");
           conf.setProperty("hibernate.connection.password", "dba");
           conf.setProperty("hibernate.connection.driver_class", "solid.jdbc.SolidDriver");

    C. Program arguments

    The configuration properties can also be passed as JVM arguments to the application.

    Example:
    -Dhibernate.dialect="org.hibernate.dialect.SolidSQLDialect"
    -Dhibernate.connection.url="jdbc:solid://localhost:2315/dba/dba"
    -Dhibernate.connection.username="dba"
    -Dhibernate.connection.password="dba"
    -Dhibernate.connection.driver_class="solid.jdbc.SolidDriver"

2.2 Creating mappings
Mappings are used to link the Plain Old Java Objects (POJOs) with the database tables and the Java datatypes with the SQL datatypes.

You can define a mapping between a POJO and a database table in two ways:

    A. XML file
    The mapping file tells Hibernate which tables in the database it has to access and which columns in that table it should use. The mapping file is referenced from the XML configuration file or with the Configuration.addResource method.

    B. Hibernate annotations
    Annotations define the mappings of the POJOs to database types inside the POJO class. With the mapping information compiled into the application, there is no chance of missing an XML configuration file.

    The annotations in the POJO class files define the relationship between the object and the database table in one place. However, with the mapping information in the Java classes, a change to the structure of the mappings will require a rebuild of the application. This means that you might need to modify your existing classes for your application to work with Hibernate.

    Note:
    • Hibernate annotations are supported only from Java 5 onwards.
    • The annotations library must be downloaded separately.


Example POJO
The XML file and annotation examples below use the following POJO for demonstrating how the mappings are defined:

public class Customer {
  private long customerID;
  private String customerName;
 
  public long getId() {
    return customerID;
  }

  public String getUsername() {
    return customerName;
  }

  public void setId(long id) {
    this.customerID = id;
  }

  public void setUsername(String u) {
    this.customerName = u;
  }

}

2.2.1 Using XML file mapping

1. Create a mapping file for each table.
    POJO classes are associated with database tables using class elements. Other elements define mappings between the variables of the object and the columns they map to. You may specify also other information in the mapping file, such as, the column datatype.

    Example ( customer.hbm.xml):

    <hibernate-mapping>
        <class name="test.Customer" table="CUSTOMERS">
         <id name="id" type="long" column="customerID" >
         <generator class="assigned"/>
        </id>
        <property name="customerName ">
           <column name="CUSTOMERNAME" />
        </property>
       </class>
      </hibernate-mapping>
    In this example, an id is associated with the POJO. The id is the primary key for the table and it is a constraint on the column “ID”. The primary key is assigned by the application. (The primary key can also be created, for example, with sequence methods.)
    2. For each mapping file, add a reference to it in the configuration file ( hibernate.cfg.xml) using the element
      <mapping resource=”mapping_filename”>.

      Example:
      <mapping resource="customer.hbm.xml"/>
      If the XML configuration file is not used, specify the file name using Configuration.addResource(“mapping_filename”).


    2.2.2 Using annotations

    Note: To use annotations, your environment must include the Hibernate annotations libraries.
    1. Create the mappings inside the POJO class.
    2. Add references to the mapping classes in the configuration file (hibernate.cfg.xml) using the element
      <mapping class="class_name"/>.
      Example:
      • The POJO below contains the annotations mapping the POJO to the database.
        import javax.persistence.Column;
        import javax.persistence.Entity;
        import javax.persistence.Id;
        import javax.persistence.Table;

        @Entity
        @Table(name = "CUSTOMERS")
        public class Customer {
           @Id
           @Column(name = "CUSTOMERID")
           private long customerID;
           @Column(name = "CUSTOMERNAME")
           private String customerName;

           public long getId() {
              return customerID;
           }

           public String getUsername() {
              return customerName;
           }

           public void setId(long id) {
              this.customerID = id;
           }

           public void setUsername(String u) {
              this.customerName = u;
           }

        }
      • The following line in the hibernate.cfg.xml file references the mapping file:

        <mapping class="test.Customer"/>


    3 Sample application

    From V6.5 Fix Pack 2 onwards, the solidDB package includes a sample application that demonstrates how to use solidDB with Hibernate. The sample includes source and build files for an application that creates a connection between Hibernate and solidDB, creates a table called CUSTOMER, and inserts data into the table.


    3.1 Contents
    The Hibernate sample is available in the samples\hibernate directory in the solidDB installation directory. For example, after a default installation in Windows environments, the sample is located in the following directory:
    C:\Program Files\IBM\solidDB\solidDB6.5\samples\hibernate

    The sample includes the following components:

    <solidDB_installation>\samples\hibernate\

    • build.xml - Ant build file (alternative to makefile)
    • makefile - makefile for starting the solidDB database and executing the sample script
    • runme - batch file for running the sample    
    • run\ - solidDB working directory where the database will be created
      • solid.ini - solidDB configuration file
      • solideval.lic - solidDB evaluation license file
    • src\ - source file directory
      • hibernate.cfg.xml - configuration file for hibernate
      • customer.cfg.xml - Hibernate mapping file that defines the mapping between the Java class and the database table
      • main\ - Java application directory
        • Customer.java - Java Class to be mapped to the database table
        • Main.java - the application's main class


    The sample also requires the solidDB dialect for Hibernate ( SolidSQLDialect.jar). The dialect is attached to this article (see section Attachment: solidDB dialect for Hibernate). The dialect jar file is also available in the jdbc directory in the solidDB installation directory (V6.5 Fix Pack 2 onwards), for example:
    C:\Program Files\IBM\solidDB\solidDB6.5\jdbc

    3.2 Prerequisites
    To run the sample, you need working installations of the following software components, including all necessary PATH and CLASSPATH settings:
    • solidDB 6.5
    • Make utility (platform specific)
    • JDK 1.6.0_14
    • Hibernate 3.5.1
      Note:
      The default Hibernate package might not include slf4j-jdk.jar. The missing file is available for download as part of the slf4j-1.5.8 package at http://www.slf4j.org/dist/slf4j-1.5.8.zip

      Copy slf4j-jdk.jar, for example, to the \lib\required\ directory in your Hibernate environment.

    3.3 Running the sample

    1. In the makefile, set the following variables to point to the corresponding jar libraries in your environment.
    • hibernate-home (the directory that contains the below listed jar files)
    • common-collections.jar
    • dom4j.jar
    • javassist.jar
    • jta.jar
    • slf4j-api.jar
    • slf4j-jdk.jar*
    • hibernate3.jar*
      *In default Hibernate installation, these files are not in the same directory as the other ones; copy them to same directory as the other jars or use absolute paths instead of the hibernate-home variable.

    2. Run the sample by executing runme in the \samples\hibernate directory.


    The sample performs the following operations:
    1. Starts solidDB that is listening to "tcp 2315".
    2. Creates a solidDB database in the 'run' directory with
      username: dba
      password: dba
      default catalog: dba
    3. Builds the sample application.
    4. Connects to solidDB using Hibernate.
    5. Creates a table CUSTOMER and inserts data into it.
    6. Shuts down solidDB.

    3.4 Hibernate setup for the sample
    • The hibernate.cfg.xml configuration file is used for defining the following configuration properties for solidDB:
      solidDB JDBC connection string (URL)
      <property name="connection.url">jdbc:solid://localhost:2315</property>

      Username and password for the solidDB database
      <property name="connection.username">dba</property>
       <property name="connection.password">dba</property>

      solidDB JDBC Driver class
      <property name="connection.driver_class">solid.jdbc.SolidDriver</property>

      solidDB Hibernate Dialect
       <property name="dialect">org.hibernate.dialect.SolidSQLDialect</property>

      Do not print Hibernate SQL operations taking place
      <property name="hibernate.show_sql">false</property>

      Automatically create the table for the object
      <property name="hbm2ddl.auto">create</property>
    • The customer.cfg.xml mapping file is used for defining the mapping between the POJO and the database table CUSTOMER.


    4 Attachment: solidDB dialect for Hibernate

    • The attached version of the solidDB dialect supports Hibernate 3.6.1.
    • The solidDB Universal Cache SQL passthrough functionality is not supported with Hibernate.

    SolidSQLDialect.jar

    Rate this page:

    (0 users)Average rating

    Add comments

    Document information


    More support for:

    IBM solidDB

    Software version:

    6.5

    Operating system(s):

    AIX, HP-UX, Linux, Solaris, Windows

    Reference #:

    1440246

    Modified date:

    2011-08-29

    Translate my page

    Machine Translation

    Content navigation