Hypersistence Optimizer Installation Guide

Installation Guide

Once you downloaded the release version, you need to unzip the package.

> unzip hypersistence-optimizer-1.3.0-pack.zip

After unzipping the setup package, you will get the following resource file structure:

Archive:  hypersistence-optimizer-1.3.0-pack.zip
   creating: hypersistence-optimizer-1.3.0/
   creating: hypersistence-optimizer-1.3.0/lib/
  inflating: hypersistence-optimizer-1.3.0/lib/hypersistence-optimizer-1.3.0-javadoc.jar
  inflating: hypersistence-optimizer-1.3.0/lib/hypersistence-optimizer-1.3.0-sources.jar
  inflating: hypersistence-optimizer-1.3.0/changelog.txt
  inflating: hypersistence-optimizer-1.3.0/LICENSE.txt
  inflating: hypersistence-optimizer-1.3.0/lib/hypersistence-optimizer-1.3.0.jar
  inflating: hypersistence-optimizer-1.3.0/maven-install.bat
  inflating: hypersistence-optimizer-1.3.0/maven-install.sh
  inflating: hypersistence-optimizer-1.3.0/README.txt

Installing the Maven dependency

Now, you need to install the Maven dependency to your local repository.

For Windows, use the maven-install.bat script. For Unix-based systems (e.g. Linux, Mac OS), use the maven-install.sh script.

> maven-install.bat

Now, the hypersistence-optimizer Maven dependency is installed to your local repository.

Adding the Maven dependency to your project

You need to add the hypersistence-optimizer Maven dependency to your project pom.xml configuration file:


The hypersistence-optimizer.version is a Maven property which you need to declare in the properties tag of your pom.xml configuration file:


After installing the Hypersistence Optimizer dependency, you need to proceed with the User Guide to see how you can configure and customize it.

Logging settings

By default, all events are logged using the Hypersistence Optimizer logger name. Based on the performance optimization event priority, Hypersistence Optimizer will trigger either an ERROR, WARN, or INFO log message. For this reason, it’s best to enable the INFO log level for the Hypersistence Optimizer logger name.

Logback logging setting

If you’re using Logback, you need to add the following logger entry to the Logback XML configuration file:

<logger name="Hypersistence Optimizer" level="info"/>

Log4j 2 logging setting

If you’re using Log4j 2, you need to add the following logger entry to the Log4j 2 configuration file:

<logger name="Hypersistence Optimizer" level="info">
    <appender-ref ref="Console"/>

Notice that the appender-ref XML element used the Console appender. You need to change that to whatever appender or appenders you have defined in your log configuration file.

JDK and Hibernate requirements

The compatibility matrix between Hibernate, JPA and Java versions looks as follows:

Hibernate JPA Java
5.4 2.2 Java 8 or above
5.3 2.2 Java 8 or above
5.2 2.1 Java 8 or above
5.1 2.1
  • Java 8 from 5.1.17 onwards
  • Java 7 from 5.1.14
  • Java 6 or above until 5.1.3
5.0 2.1 Java 6 or above
4.3 2.1 Java 6 or above
4.2 2.0 Java 6 or above
4.1 2.0 Java 6 or above
3.6 2.0 Java 6 or above
3.5 2.0 Java 6 or above
3.3 1.0 Java 6 or above

Therefore, you need to make sure that you are using the proper Java version based on what Hibernate is compiled with. Hypersistence Optimizer simply follows the Hibernate minimum Java requirement. So, if you’re using Hibernate 5.0, you can use Java 1.6 and the Hypersiste Optimizer will work just fine.

If you’re using an IBM JDK, you should also set the com.ibm.crypto.provider.DoRSATypeChecking JVM property to false as, by default, the IBM JDK does not allow you to decrypt the license key using the provided public key.


For more details, check out this StackOverflow thread.

Other than Hibernate, Hypersistence Optimizer does not require any other dependency. For logging, it can use either SLF4J, if you already configured it into your application or JBoss logging, which is required by Hibernate anyway.

Using an external Hypersistence Optimizer license file

Normally, you don’t need to specify any license file since Hypersitence Optimizer comes with an embedded license key. However, if you are using a managed environment (e.g., OSGI), which prevents loading the license file from the Hypersistence Optimizer jar, then you might want to set the license using an external URL:

new HypersistenceOptimizer(
    new JpaConfig(entityManagerFactory())
    .setLicenseFileUrl(new URL("file:///path/to/license/file"))

And, that’s pretty much what you need in order to install Hypersistence Optimizer.