Hibernate

Overview

This chapter describes the concept and features of Hibernate, and how to download and use Hibernate.

What is Hibernate?

Hibernate is an ORM (Object Relational Mapping) framework that enables programmers to use DBMS more conveniently. Hibernate maps the relationship between DBMS tables and Java objects to help persistence logic processing. That is, using Hibernate, it is possible to execute DML for CRUD (INSERT, SELECT, UPDATE, DELETE) to the DBMS by mapping the DBMS table and Java Persistence Object (JavaBean).

The following figure illustrates the architecture of Hibernate.

For more detailed information about the architecture of Hibernate, please refer to the site below.

http://www.hibernate.org

Downloading Hibernate

In order to use Hibernate, the jar file related to Hibernate is required, and this jar file can be downloaded from http://hibernate.org/orm/releases/5.4. When the downloaded file is unzipped, there are several directories. In particular, there are various jar files in the sub-directory of the lib directory, and use these files to integrate with Hibernate.

For this document, Hibernate 5.4.8 version was used and the directory name where this version was extracted is 'hibernate-release-5.4.8.Final'.

Sample Creation using Hibernate

Hibernate-configuration XML file and hibernate-mapping XML file must be created to integrate with DBMS using Hibernate.

• hibernate-configuration XML: Definition file for connection information to interwork with DBMS and for dialects to use unique features.
• hibernate-mapping XML: Definition file for mapping between Java Persistence Object and DBMS Table.

This chapter describes how to create a hibernate-configuration XML file, hibernate-mapping XML file, and how to execute DML by using these files in an application.

For details on how to create the sample program, please refer to the appendix.

Creating hibernate-mapping file

The hibernate-mapping XML file is a configuration file containing between DBMS table and Java Object.

The following is an example of creating a hibernate-mapping XML file that defines the mapping between person table and Person class.

• Use the <class> tag to specify the Java class, DBMS table, and <property> tag mappings of the table's columns and the corresponding Java variables.
• Depending on the Hibernate version, the sequence object must define the param name as sequence_name or sequence.

For more information about each tag, please refer to http://www.hibernate.org.

Creating hibernate-configuration file

The hibernate-configure file is a file that sets up a variety of connection information for DBMS connections, a dialect class for using unique functions, and a hibernate-mapping file.

The following is an example of a hibernate-configuration file.

• <session-factory> tag
  This sets the DBMS connection information and specifies the dialect class name appropriate for the DBMS to connect tot he dialect property
• <mapping resource> tag
  This specifies hibernate-mapping files.

For more information about each tag, please refer to http://www.hibernate.org.

Writing Application

If the Session object is used in the application, DML can be executed on the DBMS table in conjunction with the mapping object, and the method is as follows.

1. Retrieve the SessionFactory object with the hibernate-configuration file.
2. Retrieve the Session object with the SessionFactory object.
3. Call the method corresponding to each DML of the Session object.

The following is an application to insert, select, update, get, and delete the person table of the DBMS.

• First, read the hibernate-configuration file to retrieve the SessionFactory object.
  SessionFactory sessionFactory = new Configuration().configure("Hibernate.cfg.xml").buildSessionFactory()
• Then, retrieve Session object with the SessionFactory object.
  Session session = sessionFactory.openSession();
• Then, each method of the Session class corresponding to each DML is called.
  session.save()
  session.update()
  session.delete()
  session.get()
  session.createCriteria()

For more information about each tag, please refer to http://www.hibernate.org.

Integrating Altibase with Hibernate

To integrate Altibase with Hibernate, the Altibase JDBC driver must be configured and the dialect class for Altibase in the hibernate-configuration file must be specified.

This chapter describes how to include the AltibaseDialect class specific to Altibase in the Hibernate jar file, how to get the Altibase JDBC driver, how to configure the JDBC driver, and how to configure dialect in the hibernate-configuration file. In addition, this chapter also describes how to use the FailOver function and how to integrate several versions of Altibase.

Adding AltibaseDialect class to Hibernate jar file

DBMS vendors can provide non-standard SQL to its characteristics.

Hibernate provides a dialect class to execute non-standard SQL statements, but a dialect class for Altibase is not provided by default.

Altibase specific dialect class must be used in the deployed Hibernate jar file to use various non-standard SQL (limit clause, sequence syntax, etc.) provided by Altibase.

The dialect class for Altibase is provided with the following URL.

https://github.com/ALTIBASE/hibernate-orm/blob/master/ALTIBASE_DIALECT_PORTING.md

To download the AltibaseDialect class and related files for the Hibernate version and include them in the Hibernate jar file is as follows.

1. Unzip the Hibernate jar file.

2. Deploy and compile the AltibaseDialect.java, AltibaseLimitHandler.java, and SequenceInformationExtractorAltibaseDatabaseImpl.java files that are distributed in the directory where you unzipped the Hibernate jar.

3. Create a Hibernate jar containing the AltibaseDialect class.
4. Use the hibernate-core-x.x.x.Final.jar file created above as a Hibernate jar file.

How to get the Altibase JDBC Driver

The JDBC driver provided by Altibase is the Altibase.jar file. This file is located in the $ALTIBASE_HOME/lib directory on the server where Altibase is installed.

Starting from the Altibase version 5, two files are provided in the $ALTIBASE_HOME/lib directory, Altibase.jar file and jar file with major version specified such as Altibase5.jar.

The Altibase.jar is a general JDBC driver file, and the Altibase5.jar is the JDBC driver file used when integrating Altibase version 5 and other versions together. Therefore, the Altibase.jar file is used when linking with one Altibase server or multiple Altibases of the same version.

Before using the Altibase JDBC driver, the user must check the compatibility between the Altibase server and the Altibase JDBC driver. The user can check the compatibility by comparing the communication protocol version of the Altibase server with the communication protocol (CMP) version of the Altibase JDBC driver.

• How to check the Altibase JDBC driver version

  
  

• How to check the communication protocol version of the Altibase server

How to configure the JDBC driver

To use the Altibase JDBC driver, add the Altibase.jar file to the classpath or place it in the appropriate directory of the web server.

If the user is developing using the Eclipse, the user can add the Altibase JDBC to the project as follows.

Project – JRE System Library [J2SE-1.5]-Properties – Installed JREs – Click jre among the items – Edit – Add External JARs to add Altibase.jar.

Setting dialect in hibernate-configuration file to integrate with Altibase

Use the <property> tag of <sessionFactory> in hibernate-configuration file to specify connection information and dialect class to integrate with Altibase.

At this time, each defined property is as follows.

The following is an example of configuring Altibase connection information in the hibernate-configuration file.

• Set 4 properties for connecting to the Altibase server.
  connection.driver_class
  connection.url
  connection.username
  connection.password 
• Specify the Altibase Dialect class in the dialect property.
• Configure Person.hbm.xml file, hibernate-mapping file.

To run the AltibaseConnection project above, Hibernate related jar file and Altibase.jar file are required.

Connection using FailOver

FailOver is supported as of ALTIBASE 5.3.3. To use the FailOver function, set the FailOver related property in the connection.url property of the hibernate-configuration file.

The following is an example of connecting to the Altibase server using FailOver.

The FailOver related properties defined in the connection url part specified in the above file are as follows.

To execute the FailoverSample project above, the same jar files as the 'Setting dialect in hibernate-configuration file to integrate with Altibase' section are required.

Simultaneous connect to 2 Altibase versions

Starting with the Altibase version 5, the JDBC driver for Altibase version 5 is provided so that two or more versions can be connected simultaneously in one application. With this driver, the user can access two versions of Altibase between Altibase V5-Altibase V7, Altibase V5-Altibase V6.

In order to distinguish it from the existing Altibase.jar, Altibase5.jar dedicated to Altibase version 5 is required, and each version is provided in the form of specifying the major version in a file. Also, the JDBC driver class name specified in the connection.driver_class property of the hibernate-configuration file must be specified as Altibase5.jdbc.driver.AltibaseDriver for Altibase version 5 instead of the existing Altibase.jdbc.driver.AltibaseDriver.

In order to integrate with other versions of Altibase in Hibernate, create hibernate-configuration files for each version separately and read each hibernate-configuration file from the application.

Please note that, in this case, the application must first load Altibase5.jdbc.driver.AltibaseDriver and then Altibase.jdbc.driver.AltibaseDriver.

The following are examples of loading the drivers of two versions of Altibase using Altibase.jar and Altibase5.jar files.

Ex) Hibernate.Altibase5.cfg.xml file of MultiVersionConnection

Ex) Hibernate.Altibase7.cfg.xml file of MultiVersionConnection

Ex) PersonApp.java file of MultiVersionConnection

In the example of PersonApp.java above, you can see that Altibase5.jdbc.driver.AltibaseDriver is used as connection.driver_driver_class to load Altibase5.jdbc.driver.AltibaseDriver before Altibase.jdbc.driver.AltibaseDriver.

Please note that the driver for Altibase 5 must be loaded first.

Hibernate, Spring, Altibase Integration

To integrate with the Altibase server, the user can connect by specifying connection information and dialect in the configuration of Hibernate, or by specifying a dataSource in Spring.

This chapter describes how to integrate with the Altibase server using these two methods.

When setting dataSource in Spring

The following process is required to use Hibernate and Spring together.

1. Create dataSource for DBMS integration in Spring's applicationContext.xml file. For more detailed information on setting the dataSource, please refer to the "ALTIBASE_Spring_Linking Guide" document.
2. Specify Hibernate's sessionFactory bean in applicationContext.xml file. At this time, specify the dataSource set in No. 1 in <property name="dataSource">, hibernate-mapping files in <property name-"mapping-resource>, and <property name="hibernate Properties"> defines properties related to Hibernate.
3. In the applicationContext.xml file, set each DAO bean to refer to the SessionFactory bean.
4. The session object is obtained with the SessionFactory object set in the DAO class, and methods corresponding to each DML are called.
   
   

The following is an example of specifying dataSource and sessionFactory bean in applicationContext.xml file.

Required jar files for Spring integration

In order to execute the above example SpringAltibaseConnection1 project, not only the jar files needed in the part of 'Setting dialect in hibernate-configuration file to integrate with Altibase', but also spring related jar files are needed.

For the detailed directory location of the jar file, refer to 『ALTIBASE_Spring_Integration Guide』.

In case of setting access information in Hibernate property

When connecting by specifying connection properties to Hibernate in the Hibernate+Spring environment, the following process is required.

1. Assign Hibernate's SessionFactory bean in applicationContext.xml file.
   Then, specify hibernate-mapping files in <property name='mapping-resource"> and connection related information and dialect class in <property name="hibernate Properties" tag.
2. Set each DAO bean to refer to the sessionFactory bean.
3. The Session object is obtained with the SessionFactory object set in the DAO class, and methods corresponding to each DML are called.

The following is an example of setting the connection properties in Hibernate and integrate with Altibase.

Required jar files

In order to execute the SpringAltibaseConnection2 example, jar files from 'When setting dataSource in Spring' are required.

Using Altibase's ConnectionPool

Altibase's ConnectionPool can be used by using the ABConnectionPoolDataSource class provided by Altibase.

If it is a Hibernate + Spring integration environment, define dataSource bean by using ABConnectionPoolDataSource class in Spring applicationContext.xml file. However, Altibase's ConnectionPool cannot be used if only Hibernate is used without interworking with Spring.

For details on using Altibase's ConnectionPool, refer to the document 『ALTIBASE_Spring_Integration Guide』.

Required jar files

In order to execute the AltibaseConnectionPool example, jar files from 'When setting dataSource in Spring' are required.

Considerations when integrating Hibernate 

This chapter describes considerations when integrating Altibase in Hibernate.

Transaction management in Hibernate

When processing a transaction in Hibernate, simply call the beginTransaction() method of the Session class in the application and then call the commit()/rollback() method of the Transaction class.

When calling beginTransaction() method, setAutoCommit(false) is automatically called, and the transaction is maintained. Then when the commit()/rollback() method is called, the corresponding transaction is terminated.

Processing LOB data

In order to process LOB in Hibernate, in case of CLOB in <property> tag which defines mapping of column and variable in hibernate-mapping file, define as type=“org.hibernate.type.StringClobType”, sql-type=”clob”, and , in the case of BLOB, type= “org.hibernate.type. PrimitiveByteArrayBlobType”, sql-type=”blob” must be defined.

If this is failed to comply, incorrect data may be inserted or incorrect data may be queried due to the length limitation. Or, an error such as invalid length may occur.

The following is an example of defining <property> for CLOB and BLOB type data.

When handling LOBs, please consider that Altibase must manage the transaction after changing the autocommit mode to false to process LOB data.

When calling the beginTransaction() method of Session during Hibernate integrating, setAutoCommit(false) is automatically performed, so the beginTransaction() methods must be called before processing the LOB.

In the case of integrating Hibernate and Spring together, it is recommended to call beginTransaction() method in Java application because false may not be applied to aucocommit even if the transaction is managed in Spring.

If the beginTransaction() method is not called, the following errors can occur.

1. When querying LOB data
   null value is returned, or errors such as“java.sql.SQLException: [0]:LobLocator can not span the transaction 101858625.” occurs.
2. When inserting LOB data
   “Java.sql.SQLException: [0]: Connection is in autocommit mode. One can not operate on LOB datas with autocommit mode on.” error occurs.

The following is an example of processing LOB in Hibernate.

Required jar files

In order to execute the above LobSample project, jar files such from "Setting dialect in hibernate-mapping file to integrate with Altibase" are required.

Calling Procedure/Function

Because Stored Procedure/Function calls created in DBMS in Hibernate are not supported, CallableStatement should be used as in the case of calling in general JDBC after getting the Connection object with the Session object.

The following is an example of calling the stored procedure/function.

Ex) ProcedureSample Procedure/Function creation statement

Ex)  ProcedureApp.java of ProcedureSample

Required jar files

In order to execute the ProcedureSample, jar files such from "Setting dialect in hibernate-mapping file to integrate with Altibase" are required.

Executing NativeSQL

Among SQL statements, MOVE statement is only provided by Altibase. The way to execute the specialized function provided by a specific DBMS is as follows.

1. Create the nativeSQL statement in hibernate-mapping file.
2. In the application, get the Query object by calling the getNamedQuery() method of the session object.
3. Call the method that executes each SQL statement of the Query object (ex. executeUpdate(), list(), etc.)

The following is an example of executing the MOVE statement.

Ex) NativeSQL.hbm.xml file of NativeSQL

Ex) NativeSQLApp.jave of NativeSQL

Required jar files

In order to execute the NativeSQL example, jar files such from "Setting dialect in hibername-mapping file and integrate with Altibase" are required.

Appendix

Based on the AltibaseConnection example, this appendix describes how to integrate with Altibase in Hibernate in detail.

In the example, the development tool uses Eclipse.

Creating DBMS table and sequence

The following tables and sequences are created in the DBMS.

Creating project

Create a project called AltibaseConnection in Eclipse.

1. Click Menu - File - New - Java Project
2. Project name: Enter AltibaseConnection
3. Click the Finish button

Creating hibernate-mapping file

Create a hibernate-mapping file that defines mapping information between person table and Person class of DBMS.

1. Right-click on the AltibaseConnection project-src directory and click New-File.
2. Create Person.hbm.xml in File name:.

Create the following in the Person.hbm.xml file.

The columns of the person table and the variables of the Person class are respectively mapped with the <property> tag.

Because Java's boolean type is not a type supported by DBMS, a column was created as a type of CHAR(1) to store as 0 (false) or 1 (true).

Creating hibernate-configuration file

Create a hibernate-configuration file that defines the dialect to access the Altibase server.

1. Right-click on the AltibaseConnection project-src directory and click New-File
2. Create Hibernate.cfg.xml in File name:.

Creating application

1. Create a Person class that is a DO object for the person table.
   1. Right-click on the src directory of the AltibaseConnection project and click New-Class.
   2. Enter examples.doman in Package: and Person in Name:.

Create the following in the Person.java file.

  2. Write a main program that executes DML in DBMS

1. 1. Right-click in the src directory of the AltibaseConnection project and click New - Class. 
   2. Enter PersonApp in Name

Create the following in the PersonApp.java file.

Adding required jar files

Add the Altibase.jar and hibernate related jar files.

Right-click on the AltibaseConnection project and click Properties – Java Build Path – Click Add External JARS in Libraries to add the required jar files.

Running the application

Run the AltibaseConnection project.

After clicking the AltibaseConnection project, Run from the menu or click the Run button.

Reference documents

1. Altibase Development Guide
2. JBoss Integration Guide for Altibase
3. TOMCAT Integration Guide for Altibase
4. WEBLOGIC Integration Guide for Altibase
5. WebSphere Integration Guide for Altibase
6. Spring Integration Guide for Altibase
7. iBatis Integration Guide for Altibase