The Hibernate Types library gives you extra types that are not supported by the Hibernate ORM core.
The project name was changed from Hibernate Types to Hypersistence Utils because the scope
of the project is much broader now, offering Spring utilities as well.
For this reason, when migrating from the Hibernate Types 2.x to Hypersistence Utils 3.x,
you will need to follow these steps:
com.vladmihalcea.hibernate
to io.hypersistence.utils.hibernate
.com.vladmihalcea.spring
to io.hypersistence.utils.spring
.That’s it!
The Hypersistence Utils project gives you general-purpose utilities for both Spring and Hibernate.
The main advantage of this project is that it supports a broad range of Hibernate versions, spanning from Hibernate ORM 6.5, 6.4, 6.3 to 6.2, 6.1, 6.0, 5.6, and Hibernate 5.5.
Depending on the Hibernate version you are using, you need to add the following dependency:
<dependency>
<groupId>io.hypersistence</groupId>
<artifactId>hypersistence-utils-hibernate-63</artifactId>
<version>3.8.2</version>
</dependency>
<dependency>
<groupId>io.hypersistence</groupId>
<artifactId>hypersistence-utils-hibernate-62</artifactId>
<version>3.8.2</version>
</dependency>
<dependency>
<groupId>io.hypersistence</groupId>
<artifactId>hypersistence-utils-hibernate-60</artifactId>
<version>3.8.2</version>
</dependency>
<dependency>
<groupId>io.hypersistence</groupId>
<artifactId>hypersistence-utils-hibernate-55</artifactId>
<version>3.8.2</version>
</dependency>
The Hypersistence Utils project defines a list of optional dependencies that you will have to declare explicitly in your project in order to use them.
The reason why all these dependencies are optional, like Guava, Jackson, or PostgreSQL JDBC Driver, is that not all projects may need them.
Moreover, the dependency version is extremely important because, from time to time, security issues may be discovered that get fixed in newer versions.
So, relying on this library to supply you with the dependency versions is a very dangerous thing to do.
For instance, there have been 65 security issues discovered in the Jackson Data Bind library this project is heavily relying on.
To avoid risking security issues, you need to take the responsibility of constantly upgrading all the dependencies that you are using along with the Hypersistence Utils library.
If you are using JSON Types, then you might be interested in setting the following dependencies based on your Hibernate version:
<dependency>
<groupId>com.fasterxml.jackson.module</groupId>
<artifactId>jackson-module-jakarta-xmlbind-annotations</artifactId>
<version>${jackson-module-jakarta-xmlbind-annotation}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson-databind.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.module</groupId>
<artifactId>jackson-module-jaxb-annotations</artifactId>
<version>${jackson-module-jaxb-annotation}</version>
</dependency>
If you are mapping a Range
using Guava, then you have to provide the Guava dependency explicitly:
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>${guava.version}</version>
</dependency>
If you are mapping a MonetaryAmount
, then you have to provide the Moneta dependency explicitly:
<dependency>
<groupId>org.javamoney</groupId>
<artifactId>moneta</artifactId>
<version>${moneta.version}</version>
<type>pom</type>
</dependency>
If you are mapping a PostgreSQL-specific column type (e.g., inet
, hstore
, array
, interval
), then you have to provide the PostgreSQL dependency explicitly:
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>${postgresql.version}</version>
</dependency>
The JsonType
allows you to map JSON column types, no matter if you’re using Oracle,
SQL Server, PostgreSQL or MySQL.
If you’re using Hibernate 6, you can map any JSON column to Map
, List
, POJO, String
, or JsonNode
entity property:
@Type(JsonType.class)
private Map<String, String> properties = new HashMap<>();
If you’re using Hibernate 5, you can either provide the fully-qualified name of the Hibernate Type:
@Type(type = "io.hypersistence.utils.hibernate.type.json.JsonType")
Or, you can add the following mapping to your package-info.java
class in the same package where your JPA entities are located:
@TypeDef(
name = "json", typeClass = JsonType.class
)
package io.hypersistence.optimizer;
import io.hypersistence.utils.hibernate.type.json.JsonType;
import org.hibernate.annotations.TypeDef;
Later, you can map the Map
, List
, POJO, String
, or JsonNode
entity properties to JSON columns like this:
@Type(type = "json")
private Map<String, String> properties = new HashMap<>();
For more details, check out this article.
When mapping a JSON column type to a
POJO
,List<POJO>
orMap<String, POJO>
, you need to make sure that thePOJO
type overrides the defaultequals
andhashCode
methods and implements them according to the JSON object content.Otherwise, the Hibernate dirty checking mechanism may trigger unexpected UPDATE statements. Check out the #134 issue for more details.
When using Oracle, you have several options:
JsonType
that can work with the JSON
, VARCHAR
, or BLOB
column types,columnDefinition
attribute of the JPA @Column
annotation.JsonStringType
to map a VARCHAR2
column type storing JSON.JsonBlobType
to map a BLOB
column type storing JSON.For more details, check out this article.
When using SQL Server, you can use the generic JsonType
or the JsonStringType
to map an NVARCHAR
column type storing JSON.
For more details, check out this article.
When using PostgreSQL, you can use the generic JsonType
or the JsonBinaryType
to map both jsonb
and json
column types.
For more details, check out this article.
When using MySQL, you can use the generic JsonType
or the JsonStringType
to map the json
column type.
For more details, check out this article.
JsonNode
to a JSON columnNo Dialect mapping for JDBC type: 1111
issue when mixing JSON types with native SQL queriescolumn is of type jsonb but expression is of type record
or bytea
issueList
with JPA and HibernateDuration
with HibernateMonetaryAmount
with JPA and Hibernatejava.time.YearMonth
to DATE or INTEGER columnjava.time.Year
and java.time.Month
with JPA and HibernateCharacter
to nullable CHAR columnImmutableType
utility to simplify UserType
implementationsfindAll
Anti-Pattern@Retry
annotation to automatically retry on failureThe BaseJpaRepository
is a much better alternative to the default Spring Data JpaRepository
because it does not provide a findAll
method or a save
method that makes no sense in JPA terminology.
To use the BaseJpaRepository
utility, make sure that you provide the repositoryBaseClass
attribute in the @EnableJpaRepositories
configuration to reference the BaseJpaRepositoryImpl
from the Hypersistence Utils project:
@Configuration
@EnableJpaRepositories(
value = "your.repository.package",
repositoryBaseClass = BaseJpaRepositoryImpl.class
)
public class JpaConfiguration {
...
}
The your.repository.package
is the Java package of your Spring repositories.
While the BaseJpaRepository
is to be preferred, in case you need to use the default JpaRepository
, then you can at least extend the HibernateRepository
as well to deprecate the methods that may cause problems.
To use the HibernateRepository
, make sure that you include the io.hypersistence.utils.spring.repository
package in your @EnableJpaRepositories
configuration:
@Configuration
@EnableJpaRepositories(
value = {
"io.hypersistence.utils.spring.repository",
"your.repository.package",
...
}
)
public class JpaConfiguration {
...
}
The your.repository.package
is the Java package of your Spring repositories.
ClassImportIntegrator
- How to write a compact DTO projection query with JPAListResultTransformer
- The best way to use a Hibernate ResultTransformerMapResultTransformer
- How to return a Map result from a JPA or Hibernate querySQLExtract
- How to get the SQL query from JPQL or JPA CriteriaQueryStackTraceLogger
- How to find the source of an SQL query generated by HibernateThis project is Free, as in Libre, not Gratis.
There is no free-of-charge support. Only the source code and the binaries are available for free.
If you need assistance with a given issue, you will need to purchase either the Coaching Basic or the Coaching Pro programs.
Besides the Paid support options, you have the option of providing your own fix. For that, here’s what you need to do:
However, due to lack of time, I will review the submitted Pull Requests from time to time, so you may need to wait several months until the Pull Request is reviewed and integrated.
Imagine having a tool that can automatically detect if you are using JPA and Hibernate properly. No more performance issues, no more having to spend countless hours trying to figure out why your application is barely crawling.
Imagine discovering early during the development cycle that you are using suboptimal mappings and entity relationships or that you are missing performance-related settings.
More, with Hypersistence Optimizer, you can detect all such issues during testing and make sure you don’t deploy to production a change that will affect data access layer performance.
Hypersistence Optimizer is the tool you’ve been long waiting for!
If you are interested in on-site training, I can offer you my High-Performance Java Persistence training,
which can be adapted to one, two or three days of sessions. For more details, check out my website.
If you want me to review your application and provide insight into how you can optimize it to run faster,
then check out my consulting page.
If you want the fastest way to learn how to speed up a Java database application, then you should definitely enroll in my High-Performance Java Persistence video courses.
Or, if you prefer reading books, you are going to love my High-Performance Java Persistence book as well.
The project uses Maven Toolchains as different modules are compiled and tested using different Java versions.
Hypersistence Utils 6 requires Java 11 while the other modules are compiled with Java 8.
To see how to configure Maven Toolchains, check out this article.
The project uses various database systems for integration testing, and you can configure the JDBC connection settings using the
DatasourceProvider
instances (e.g., PostgreSQLDataSourceProvider
), and the project uses Testcontainers to bootstrap a Docker container
with the required Oracle, SQL Server, PostgreSQL, or MySQL instance on demand.
If you are a regular contributor, it’s advisable to set up the required database locally or use the Docker Compose configuration provided in the
docker
folder,
as bootstrapping the containers on demand is slower, and your tests are going to take longer to run.
If you want to fix an issue or add support for a new feature, please provide the associated integration test case that proves the improvement is working as expected.