Using the new InterSystems IRIS Hibernate 6 Dialect for a Springboot Project

Hibernate is the most popular framework to do ORM (Object Relational Mapping) projects. With Hibernate a software can use the main DBMS in the market, including the capability to change the database vendor any time, without source code impact. This is possible because the Hibernate supports dialects. Each database product has a different dialect that can be assigned into a configuration file. So, if a software is using Oracle and is looking to evolve to InterSystems IRIS, just change the configuration file with connection and dialect information. If your software needs to be prepared to use database indicated by your client, the Hibernate is the solution to you.

Is there any InterSystems IRIS dialect for the new Hibernate 6?

Currently is not any official dialect to use IRIS with the new Hibernate 6. To resolve this issue, Dmitry Maslennikov proposed an idea in the excellent Ideas Portal (https://ideas.intersystems.com/ideas/DPI-I-372) and I implemented it.
If you do this tutorial, you will see the idea and this new dialect of IRIS in action and working.

What you need to do this tutorial

To do this tutorial you need:
1.    An IRIS instance running (if you don’t have one, you can get it on https://openexchange.intersystems.com/package/ObjectScript).
2.    Spring Tools installed (download it on https://spring.io/tools). Choose Eclipse version for this tutorial.
3.    Java JDK version 17 (download it on https://jdk.java.net/archive/). Choose Java 17 for this tutorial.
4.    All source code for this tutorial: https://github.com/yurimarx/iris-java-tools/tree/main/springboot-sample.

Tutorial steps

1.    Open the Spring Tool Suite (STS) and choose a valid workspace path (any folder) and click Launch:

2.    Click the Create new Spring Starter Project link:

3.    This wizard will create a new Spring project. Fill the fields with these values:
•    Service URL: https://start.spring.io
•    Type: Maven (it is a package manager like the NPM, ZPM or IPM)
•    Packaging: Jar (type of executable for the compiled project)
•    Java Version: 17 or 20 (for this tutorial I selected version 17)
•    Language: Java
•    Group: com.tutorial (domain of the project for Maven)
•    Artifact: iris-tutorial (name of the project for Maven)
•    Version: 0.0.1-SNAPSHOT (version of the project for Maven)
•    Description: IRIS Tutorial
•    Package: com.tutorial.iris (root package for the project)

4.    Click Next.
5.    Choose the following dependencies for your project:

6.    Click Finish to create your project.
7.    Open your pom.xml file and include 2 new dependencies (for IRIS dialect and for IRIS JDBC driver) and 1 repository (necessary because the InterSystems IRIS JDBC driver is not published into a public maven repository).

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.1.1</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.tutorial</groupId>
	<artifactId>tutorial-dialect</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>tutorial-dialect</name>
	<description>Tutorial for IRIS Hibernate 6 Dialect</description>
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-hateoas</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.data</groupId>
			<artifactId>spring-data-rest-hal-explorer</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-configuration-processor</artifactId>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>io.github.yurimarx</groupId>
			<artifactId>hibernateirisdialect</artifactId>
			<version>1.1.0</version>
		</dependency>
		<dependency>
			<groupId>com.intersystems</groupId>
			<artifactId>intersystems-jdbc</artifactId>
			<version>3.7.1</version>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
	<repositories>
		<repository>
			<id>InterSystems IRIS DC Git Repository</id>
			<url>
				https://github.com/intersystems-community/iris-driver-distribution/blob/main/JDBC/JDK18</url>
			<snapshots>
				<enabled>true</enabled>
				<updatePolicy>always</updatePolicy>
			</snapshots>
		</repository>
	</repositories>
</project>

8.    Go to the application.properties file (src > main > java > resources folder) and set connection and dialect properties with these values:

spring.datasource.username=_SYSTEM
spring.datasource.url=jdbc:IRIS://localhost:1972/USER
spring.datasource.password=SYS
spring.jpa.properties.hibernate.default_schema=Example
spring.jpa.hibernate.ddl-auto=update
spring.datasource.driver-class-name=com.intersystems.jdbc.IRISDriver
spring.jpa.properties.hibernate.temp.use_jdbc_metadata_defaults = false
spring.jpa.database-platform=io.github.yurimarx.hibernateirisdialect.InterSystemsIRISDialect
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

9.    Create a new persistent class (click right button on project > New > Class):

10.    Fill the following fields to create the class:
•    Package: com.tutorial.iris.model
•    Name: Product

11.    Click Finish to create the class.
12.    Develop the Product persistent class (class with values persisted in a SQL table) with this source code:

package com.tutorial.dialect.model;

import java.util.Date;

import com.fasterxml.jackson.annotation.JsonFormat;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import jakarta.persistence.Temporal;
import jakarta.persistence.TemporalType;

@Entity
@Table(name = "Product")
public class Product {

	
	@Id
    @GeneratedValue (strategy = GenerationType.IDENTITY)
    private Long id;
	
	private String name;
	
	private String description;
	
	private Double height;
	
	private Double width;
	
	private Double weight;
	
	@Column(name="releasedate")
	@Temporal(TemporalType.DATE)
	@JsonFormat(pattern = "yyyy-MM-dd")
	private Date releaseDate;

	public Long getId() {
		return id;
	}

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

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getDescription() {
		return description;
	}

	public void setDescription(String description) {
		this.description = description;
	}

	public Double getHeight() {
		return height;
	}

	public void setHeight(Double height) {
		this.height = height;
	}

	public Double getWidth() {
		return width;
	}

	public void setWidth(Double width) {
		this.width = width;
	}

	public Double getWeight() {
		return weight;
	}

	public void setWeight(Double weight) {
		this.weight = weight;
	}

	public Date getReleaseDate() {
		return releaseDate;
	}

	public void setReleaseDate(Date releaseDate) {
		this.releaseDate = releaseDate;
	}

}

13.    Create an Interface repository for CRUD operations to the Product class (click right the project > New > Interface):

14.    Fill the values for the interface and click Finish:
•    Package: com.tutorial.iris.repository
•    Name: ProductRepository

15.    Click Finish to create the interface.
16.    Develop the ProductRepository (a CRUD repository implements save, delete, find, find one and update functions) Interface (src > main > java > com > tutorial > dialect > repository folder ) with this source code:

package com.tutorial.dialect.repository;

import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

import com.tutorial.dialect.model.Product;

@Repository
public interface ProductRepository extends CrudRepository<Product, Long> {

}

17.    Now, using the HAL browser from Springboot, is possible test CRUD functions in a web screen.
18.    Be sure to run an IRIS instance on localhost, port 1972 with user _SYSTEM and password SYS (or change the application.properties for other connections values).
19.    Run the application (click right the project > Run As > Spring boot app).
20.    On the console you can see the log indicating the application start:

21.    Go to your browser and type http://localhost:8080. See the HAL browser:

22.    Click plus button for products endpoint to create a new product:

23.    Fill the following values to create a new product and click Go button to confirm:

24.    A new product was persisted:

Check the new row on IRIS (table product on USER namespace)

Test other operations, check in the database and enjoy!

I would like thanks @Dmitry Maslennikov for your advanced support and for help me to improve this new Dialect