Red Hat

In Relation To

The Hibernate team blog on everything data.

You asked for it, we deliver: Hibernate Search 5.7.0.Final, with support for Hibernate ORM 5.2.8, is out! And of course, like previous versions, it features experimental support for Elasticsearch integration (even with some improvements).

Stuck on an older ORM version? Don’t worry, we also released a bugfix version for 5.6, namely 5.6.1.Final.

Hibernate Search 5.7.0.Final is only compatible with Hibernate ORM 5.2.3 and later. There isn’t any version of Hibernate Search compatible Hibernate ORM 5.2.0 to 5.2.2.

If you need to use Hibernate ORM 5.0.x or 5.1.x and cannot upgrade, please use Hibernate Search 5.6.1.Final.

What’s new on 5.7 since the candidate release?

Below are the main changes since the candidate release.

If you are looking for advice on how to migrate, please refer to the migration guide.

For a full list of changes since 5.7.0.CR1, please see the release notes. For a full list of changes since 5.6.0.Final, please see this list of tickets on our JIRA instance.

General improvements

  • HSEARCH-2574: when it makes sense, you can now repeat Hibernate Search annotations on a single attribute/method. For example, if you want to add two index fields on the same title attribute, you can write:

        @Field(analyzer = @Analyzer(definition = "myAnalyzer")
        @Field(name = "title_sort", analyzer = @Analyzer(definition = "myAnalyzerForSort")
        private String title;

    Thus you don’t have to use the composite annotations (@Fields) anymore. But of course, those are still available.

  • HSEARCH-2588: some methods in the Sort DSL allowed to specify the sort field type explicitly, which was useful when sorting on fields added through custom field bridges. We improved support for MetadataProvidingFieldBridge, so that you now only need to implement this interface on your custom field bridges, and won’t need anything special when using the sort DSL anymore. As a result, the byField(String, SortField.Type) and andByField(String, SortField.Type) methods in the sort DSL have been deprecated.

  • HSEARCH-2587: an NPE could occur when using the Sort DSL to sort on embedded (@IndexedEmbedded) fields; this is now fixed.

  • HSEARCH-2576: unnecessary memory allocations within queries have been removed, resulting in better query throughput.

  • And several improvements for other solutions integrating Hibernate Search, like HSEARCH-2597, HSEARCH-2561, HSEARCH-2418 or HSEARCH-2585.

Elasticsearch-specific improvements

  • HSEARCH-2453: Elasticsearch authentication is now fully implemented: there are dedicated username and password properties so that you don’t need to embed the credentials in the URL anymore.

  • HSEARCH-2593: when using automatic node discovery on Elasticsearch, a scheme (HTTP or HTTPS) cannot be detected automatically for newly discovered nodes; by default it is HTTP. You can now customize this to use HTTPS instead: just add hibernate.search.default.elasticsearch.discovery.default_scheme https to your configuration.

  • HSEARCH-2590: queries using pagination could allocate too much memory in certain circumstances; this is now fixed.

What’s new on 5.6?

5.6.1.Final contains exclusively backported fixes from 5.7. You can see a full list of changes since 5.6.0.Final in the release notes.

What’s next?

We’re now focusing on the next two big improvements:

  • support for Elasticsearch 5 without losing support for Elasticsearch 2 (HSEARCH-2434, HSEARCH-2581). This will be in a 5.8 release.

  • streamlining our APIs, in particular to better fit remote indexing services (like Elasticsearch), but also to support Lucene 6. Due to the breaking changes this requires, we will include these changes in a new major release, Hibernate Search 6.0.

How to get these releases

All versions are available on Hibernate Search’s web site.

Ideally use a tool to fetch it from Maven central; these are the coordinates:

<dependency>
   <groupId>org.hibernate</groupId>
   <artifactId>hibernate-search-orm</artifactId>
   <version>5.7.0.Final</version>
</dependency>

To use the experimental Elasticsearch integration you’ll also need:

<dependency>
   <groupId>org.hibernate</groupId>
   <artifactId>hibernate-search-elasticsearch</artifactId>
   <version>5.7.0.Final</version>
</dependency>

Downloads from Sourceforge are available as well.

Feedback, issues, ideas?

To get in touch, use the following channels:

JBoss Community Asylum - Validating Beans 2.0

Posted by    |       |    Tagged as asylum git

This time Emmanuel and Andrew sits down with Gunnar to talk about Beans Validation 2.0.

Episode 43 - Show notes and podcast.

Enjoy!

The MySQL Dialect refactoring

Posted by    |       |    Tagged as Discussions Hibernate ORM

Starting with Hibernate ORM 5.2.8, MariaDB gets its own Hibernate dialects.

Why?

While working on the new MariaDB Dialects, I realized that the MySQL Dialects would benefit from simplifying the version hierarchy.

Previously, the MySQL Dialects used to looks like that:

MySQL Dialects before refactoring, align=

As you can see, because of the various MySQL storage engines (e.g. MyISAM and InnoDB), the class hierarchy has diverged in multiple branches. Once we integrated Hibernate Spatial, the MySQL Dialects have become even more convoluted.

For this reason, we created the HHH-11473 Jira issue, which is fixed in Hibernate 5.2.9.

How do we stand now?

After refactoring, the MySQL Dialects look as follows:

MySQL Dialects after refactoring, align=

The following Dialects have been deprecated, therefore, they were not added to the class diagram above:

MySQLMyISAMDialect

Use MySQLDialect instead, as well as the hibernate.dialect.storage_engine=myisam Environment Variable or System Property.

MySQLInnoDBDialect

Use MySQLDialect instead, as well as the hibernate.dialect.storage_engine=innodb Environment Variable or System Property.

MySQL5InnoDBDialect

Use MySQL5Dialect instead, as well as the hibernate.dialect.storage_engine=innodb Environment Variable or System Property.

MySQL57InnoDBDialect

Use MySQL57Dialect instead.

MySQL5InnoDBSpatialDialect

Use MySQL5SpatialDialect instead, as well as the hibernate.dialect.storage_engine=innodb Environment Variable or System Property.

MySQL56InnoDBSpatialDialect

Use MySQL56SpatialDialect which defaults to InnoDB by default.

The MySQLStorageEngine abstraction encapsulates the difference between various storage engines, By delegating this responsibility to a new abstraction, the MySQL Dialect hierarchy got a lot simpler.

Traditionally, MySQL used the non-transactional MyISAM storage engine, and this is the default storage engine for all Dialects that are older than MySQL55Dialect. From MySQL55Dialect onwards, the InnoDB storage engine is used by default.

You can always override the default storage engine by providing the hibernate.dialect.storage_engine Environment Variable or System Property. Unlike other Hibernate configuration properties, this one must not be provided via persistence.xml because the Dialect is bootstrapped prior to the configuration management mechanism.

Conclusion

The deprecated Dialects will be available for a while, but they will surely be removed in a future version of Hibernate, so you better use the new ones instead. This refactoring is useful for two reasons. First, supporting MySQL 8.0 requires a single Dialect, not two. Second, it’s easier for our users as well since the choice is much more straightforward now since there is only one Dialect associated to a given MySQL version.

Hibernate Community Newsletter 4/2017

Posted by    |       |    Tagged as Discussions Hibernate ORM

Welcome to the Hibernate community newsletter in which we share blog posts, forum, and StackOverflow questions that are especially relevant to our users.

Looking for your feedback

We are looking for your feedback in about Hibernate bootstrap in cloud environments. Check out this article for more details. If you have any idea or proposal, don’t hesitate to use the comments section below the aforementioned article.

Articles

Sometimes, it’s easy to miss the basic concepts, and relational databases are no different. Check out this article about how does a relational database work.

We released dedicated Dialects for MariaDB, so you don’t have to use the MySQL-specific Dialects when working with MariaDB.

Integration testing is of paramount importance when building an enterprise application. However, many projects rely on in-memory databases (e.g. H2, HSQLDB) for testing, while in production they use Oracle, SQL Server, PostgreSQL or MySQL. In this article, you’ll find how you can run integration tests faster using tmpfs and Docker.

If you’re using JCache through Spring, Hibernate, and Ehcache, this article explains how you can prevent spontaneous cache creation.

Emmanouil Gkatziouras wrote two articles about Hibernate and Hazelcast as a 2nd-level caching provider:

Russ Thomas wrote https://sqljudo.wordpress.com/2014/12/29/what-every-dba-and-swe-should-know-about-ef/[a comprehensive list of ORM Anti-Patterns. Although the article was written for Entity Framework, the tups apply to JPA or Hibernate.

For our Portuguese readers, Rhuan Henrique Rocha da Silva wrote an article about the meaning of mappedBy in JPA and Hibernate.

Thorben Janssen wrote an article about adding Full-Test Search capabilities to a Hibernate application.

Questions and answers

Eighth bug-fix release for ORM 5.2

Posted by    |       |    Tagged as Hibernate ORM Releases

The Eighth bug-fix release for Hibernate ORM 5.2 has just been published. It is tagged at https://github.com/hibernate/hibernate-orm/releases/tag/5.2.8

The complete list of changes can be found here (or here for people without a Hibernate Jira account).

For information on consuming the release via your favorite dependency-management-capable build tool, see http://hibernate.org/orm/downloads/

The release bundles can be obtained from SourceForge or BinTray.

MariaDB Dialects

Posted by    |       |    Tagged as Discussions Hibernate ORM

Starting with Hibernate ORM 5.2.8, MariaDB gets its own Hibernate dialects.

About MariaDB

MariaDB is a MySQL fork that emerged in 2009 as a drop-in replacement for MySQL. While for a while, MariaDB and MySQL offered similar functionalities, with time, both MariaDB and MySQL have diverged.

For this reason, we created the HHH-11457 issue, which is fixed in the Hibernate ORM 5.2.8.

Dialect variants

For the moment, you can use one of the following two options:

MariaDBDialect

which is the base class for all MariaDB dialects and it works with any MariaDB version

MariaDB53Dialect

which is intended to be used with MariaDB 5.3 or newer versions

In time, we will add new Dialects based on newer capabilities introduced by MariaDB.

Connection properties

While to connect to a MySQL application, the connection properties look as follows:

  • 'db.dialect' : 'org.hibernate.dialect.MySQL57InnoDBDialect',

  • 'jdbc.driver': 'com.mysql.jdbc.Driver',

  • 'jdbc.user' : 'hibernate_orm_test',

  • 'jdbc.pass' : 'hibernate_orm_test',

  • 'jdbc.url' : 'jdbc:mysql://127.0.0.1/hibernate_orm_test'

For MariaDB, the connection properties look like this:

  • 'db.dialect' : 'org.hibernate.dialect.MariaDB53Dialect',

  • 'jdbc.driver': 'org.mariadb.jdbc.Driver',

  • 'jdbc.user' : 'hibernate_orm_test',

  • 'jdbc.pass' : 'hibernate_orm_test',

  • 'jdbc.url' : 'jdbc:mariadb://127.0.0.1/hibernate_orm_test'

While the URL includes the mariadb database identifier, the MariaDB53Dialect supports Time and Timestamp with microsecond precision, just like MySQL57InnoDBDialect.

Conclusion

If you are using MariaDB, it’s best to use the MariaDB-specific Dialects from now on since it’s much easier to match the MariaDB version with its appropriate Hibernate Dialect.

It is not every day that we announce the first release of a new major version of Hibernate Validator. And today is one of those days: the first alpha of Hibernate Validator 6 has just been released.

Hibernate Validator 6 is going to be the Reference Implementation of Bean Validation 2.0. That’s why we coordinated the releases of the first alphas of these two projects.

It is also a playground used to validate future enhancements of the Bean Validation specification so feedback on the subjects presented here is very welcome!

Note that Hibernate Validator 6 requires JDK 8 or above.

What’s new

New group id

First, starting from 6, the new home of Hibernate Validator is org.hibernate.validator (it used to be org.hibernate).

For instance, the Maven coordinates of this version are:

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.0.Alpha1</version>
</dependency>

We published relocation artifacts to make the transition more smooth. Examine the output of your build, if you see messages like "[WARNING] The artifact org.hibernate:hibernate-validator:jar:6.0.0.Alpha1 has been relocated to org.hibernate.validator:hibernate-validator:jar:6.0.0.Alpha1", you are still using the old GAV coordinates and should upgrade to the new ones.

Also make sure to not depend on 5.x and 6.x at the same time (as the group ids are different, the dependency resolution algorithm of your build tool fails to detect that these are two versions of the same logical artifact).

Java 8 goodness

As we now target Java 8 and above, we benefit from the language improvements:

  • all Bean Validation and Hibernate Validator constraints can be used in type use context (e.g. List<@NotBlank String>);

  • all the annotations that could be repeated with a List container are now marked @Repeatable.

Implementation of the new features of the spec

Earlier this week, Gunnar presented on the Bean Validation website the new features introduced in Early Draft 1 of Bean Validation 2.0. They are implemented in Hibernate Validator 6.0.0.Alpha1 so you can already play with them and give us your feedback.

Nested type use constraints and nested cascaded validation

There are some things where Hibernate Validator goes beyond the Early Draft 1 of the spec.

Typically, with Hibernate Validator, type use constraints may be used even on nested types. And so may cascaded validation.

public class Order {

        private Map<@NotNull @Valid Product, @Size(min = 1) List<@NotNull @Valid OrderLine>> lines;

}

In the above example, Hibernate Validator is going to:

  • validate the @NotNull constraint on Product;

  • cascade the validation to Products;

  • validate that for a Product, the list of OrderLines contains at least one element;

  • validate that the lists do not contain any null element;

  • cascade the validation to OrderLines.

As mentioned above, the nested part is new in Hibernate Validator and is not part of the spec yet. If you think it should go in, raise your hand and participate to the discussions. Expect some interesting discussions soon on what the nodes of the property path should look like in the case of nested types validation.

Lambda based constraint definition

We started to explore how lambdas could be integrated into Hibernate Validator and the first outcome of it is lambda based constraint definition. Using the programmatic API, you can define a constraint without writing a ConstraintValidator:

HibernateValidatorConfiguration configuration = Validation
    .byProvider( HibernateValidator.class )
    .configure();

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
    .constraintDefinition( ValidPassengerCount.class )
        .validateType( Bus.class )
            .with( b -> b.getSeatCount() >= b.getPassengers().size() );

Note that the programmatic API is not part of the specification so, for now, this part is specific to our implementation.

Validation of Duration

In Hibernate Validator 6, we are able to validate a lot more java.time classes and Marko recently introduced support for Duration.

Here is an example of what you can do with it:

public class TrainingSession {
    [...]

    @DurationMin(hours = 1, minutes = 30)
    @DurationMax(days = 1, inclusive = false)
    private Duration duration;

    [...]
}

Again, let us know if you think this feature should go into the spec.

Getting 6.0.0.Alpha1

To get the release with Maven, Gradle etc. use the GAV coordinates org.hibernate.validator:{hibernate-validator|hibernate-validator-cdi|hibernate-validator-annotation-processor}:6.0.0.Alpha1. As mentioned earlier, the group id has been changed to org.hibernate.validator.

Alternatively, a distribution bundle containing all the bits is provided on SourceForge (TAR.GZ, ZIP).

Feedback, issues, ideas?

To get in touch, use the usual channels:

What’s next?

Bean Validation 2.0 and Hibernate Validator 6 are still under active development. We will release new alphas on a regular basis.

Recently, the team has been discussing improvements around Hibernate (ORM) usage within cloud based apps and microservices. In particular the fundamental assumption that things will break regularly on these platforms and that services should be resilient to failures.

The problem

In microservices or cloud architectures, services are started in different orders (usually beyond your control). It is possible for the app using Hibernate ORM to be started before the database. At the moment, Hibernate ORM does not like that and will explicitly fail (exception) if it can’t connect to the database.

Another related concern is to consider what is happening if the database is stopped for a while after the app running Hibernate ORM has started and resume working shortly after.

Solution 1: Hibernate waits and retries at boot time

Some users have asked us to delay and retry the connection process in case the database is not present at boot time. That would work and solve the bootstrap problem. It would not solve the database gone while running the app but here at least you have your transaction and the error propagation mechanism covering you. Plus at development time, the boot time problem gone would be quite nice already.

I understand that this is probably a quick win to implement this, but better be sure of the problem before adding that feature. It feels to me that Hibernate ORM bootstrap is not the ideal area to fix that problem. But at the end of the day if it helps enough, it would be worth it.

We are exploring that option and considering alternatives and that’s where we need your feedback.

Wait and retry vs platform notification

In this blog post, I mention the wait and retry approach. It can be replaced by a notification from the cloud platform when a service is up / down.

This avoids the regular polling process at the cost of having to rely on various integrations from various cloud platforms.

Solution 1.b: The connection pool waits and retries

It probably would be better if the connection pool Hibernate ORM uses, implements that logic but there are more than one connection pool Hibernate supports. That’s a minor variation on solution 1.

Solution 2: Hibernate boots in non-functioning mode

If Hibernate ORM cannot connect to the datasbase, it continues its bootstrap process. If an EntityManager is asking for a connection while the database is still unavailable, a well defined exception is raised. To not flood the system, a wait and retry system for connection checking would be in place to only try a few times even when lots of EntityManager are requested.

There are some subtle difficulties here on concurrency and on the fact that we use info from the bootstrap connection to configure Hibernate ORM. The most visible option guessed from the connection is the dialect to use. On the other hand, stopping the app boot process while waiting and retrying like solution 1 proposes is probably not without its challenges.

The exception raised by Hibernate ORM upon DB inaccessibility needs to be treated properly by the application (framework) being used. Like a global try catch that moves the application in degraded mode or propagating the execution error to the client (e.g. HTTP error 500). It might even be helpful if Hibernate ORM was exposing the not ready status via an explicit API.

This could be tied to a health check from the cloud platform. The application would report the not ready but trying status via a /health endpoint that the orchestrator would use.

On database connection breaking

There are many reasons for failing to connect to a database:

  1. Host unreachable

  2. DB server denying access temporarily (e.g. load)

  3. Incorrect port setting

  4. Incorrect credentials

  5. And many more

Should the system go into the wait and retry mode for cases 3, 4, 5? Or should it refuse to deploy?

Solution 3: the smart app (framework)

Another solution is for the app to have a smart overall bootstrap logic. It tries to eagerly start but if a Hibernate ORM connection error occurs, only the inbound request framework is started. It will regularly try and boot and in the mean time return HTTP 500 errors or similar.

This requires an app framework that could handle that. It embeds circuit breaker logic in the app and can better react to specific errors. I wonder how common such frameworks are though.

This is in spirit the same solution as solution 2 except it is handled at the higher level of the app (framework) vs Hibernate ORM.

Solution 4: the cloud / MSA platform restart the apps

An arguably better solution would be for the cloud platform to handle these cases and restart apps that fail to deploy in these situations. It likely requires some kind of service dependency management and a bit of smartness from the cloud infra. The infrastructure would upon specific error code thrown at boot time, trigger a wait and retry deployment logic. There is also a risk of a dependency circularity leading to a never starting system.

I guess not all cloud infra offer this and we would need an alternative solution. OpenShift let’s you express dependencies to make sure a given service is started before another. The user would have to declare that dependency of course.

Solution 5: proxy!

Another solution is to put proxies either before the app inbound requests and/or between the app and the database. Proxy is the silver bullet that lots for cloud platforms uses to solve world hunger in the digital universe.

How many proxies and routing logic does it take to serve a "Hello world!" in the cloud?
Who proxies the proxies?

:)

This approach has the advantage of not needing customized apps or libraries. The inconvenience is more intermediary points between your client and the app or data.

If the proxy is before the application, then it needs a health check or a feedback from the boot system to wait and retry the re-deployment of the application on a regular basis. I’m again not certain cloud infrastructures offer all of this infrastructure.

If the proxy is between Hibernate ORM and the database (like HAProxy for MySQL), you’re still facing some timeout exception on the JDBC side. Which means the application will fail to boot. But at least, the proxy could implement the wait and retry logic.

My questions to you

Do you have any input on this subject:

  • what’s your opinion?

  • what’s your experience when deploying cloud apps?

  • any alternative solution you have in mind?

  • any resource you found interesting covering this subject?

  • would you benefit from solution 1?

  • would you benefit from solution 2?

Any feedback to help us think this problem further is what we need :)

Hibernate OGM 5.1 CR 1 is out

Posted by    |       |    Tagged as Hibernate OGM Releases

Good news!

The first candidate release for Hibernate OGM 5.1 is out.

Compared to 5.1 Beta3, this release upgrades Hibernate Search to version 5.5.6.Final and supports MongoDB aggregate operation in native queries.

You can find all the details in the 5.1.0.CR1 changelog.

If you need to upgrade from a version before 5.0, you can find help on the migration notes.

Hibernate Search 5.5.6.Final

Hibernate Search transparently indexes your data and offers fast full-text and geolocation search.

This version supports Elasticsearch.

This means that now you can use Hibernate OGM to do CRUD operations on your favourite NoSQL database while having it also transparently synchronize to an Elasticsearch cluster.

If you are not familiar with Hibernate Search you can find all the details about the latest stable version in the official blog.

Aggregation in MongoDB

MongoDB native queries now support the aggregation operation syntax.

For example, this is now a valid native query:

String nativeQuery = "db.Poem.aggregate(["
                  + "{ '$match': "
                        + "{'$or': ["
                                 + "{'author': { '$regex': 'Oscar.*', '$options': 'i'}}, "
                                 + "{ 'name': { '$regex': 'Po.*'} }"
                        + "]}}, "
                  + "{ '$sort' : { 'name' : -1 } }"
                  + "])";

List<Poem> poems = (List<Poem>) em.createNativeQuery( nativeQuery, Poem.class ).getResultList();

Where can I get it?

You can get the required core library using the following Maven coordinates:

  • org.hibernate.ogm:hibernate-ogm-core:5.1.0.CR1

and these are the backends currently available for 5.1.0.CR1:

  • Cassandra: org.hibernate.ogm:hibernate-ogm-cassandra:5.1.0.CR1

  • CouchDB: org.hibernate.ogm:hibernate-ogm-couchdb:5.1.0.CR1

  • Infinispan

    • Embedded: org.hibernate.ogm:hibernate-ogm-infinispan:5.1.0.CR1

    • Remote: org.hibernate.ogm:hibernate-ogm-infinispan-remote:5.1.0.CR1

  • Ehcache: org.hibernate.ogm:hibernate-ogm-ehcache:5.1.0.CR1

  • MongoDB: org.hibernate.ogm:hibernate-ogm-mongodb:5.1.0.CR1

  • Neo4j: org.hibernate.ogm:hibernate-ogm-neo4j:5.1.0.CR1

  • Redis: org.hibernate.ogm:hibernate-ogm-redis:5.1.0.CR1

Alternatively, you can download archives containing all the binaries, source code and documentation from Sourceforge.

What’s next?

We are going to clean up the documentation and release 5.1 Final.

After that, we will focus on Hibernate OGM 5.2 which will support Hibernate ORM 5.2

How can I get in touch?

You can find us through the following channels:

We are looking forward to hear your feedback!

Building Multi-Release JARs with Maven

Posted by    |       |    Tagged as Discussions

Java 9 comes with a new feature very useful to library authors: multi-release JARs (JEP 238).

A multi-release JAR (MR JAR) may contain multiple variants of one and the same class, each targeting a specific Java version. At runtime, the right variant of the class will be loaded automatically, depending on the Java version being used.

This allows library authors to take advantage of new Java versions early on, while keeping compatibility with older versions at the same time. If for instance your library performs atomic compare-and-set operations on variables, you may currently be doing so using the sun.misc.Unsafe class. As Unsafe has never been meant for usage outside the JDK itself, Java 9 comes with a supported alternative for CAS logics in form of var handles. By providing your library as an MR JAR, you can benefit from var handles when running on Java 9 while sticking to Unsafe when running on older platforms.

In the following we’ll discuss how to create an MR JAR using Apache Maven.

Structure of a Multi-Release JAR

Multi-Release JARs contain several trees of class files. The main tree is at the root of the JAR, whereas version-specific trees are located under META-INF/versions, e.g. like this:

JAR root
- Foo.class
- Bar.class
+ META-INF
   - MANIFEST.MF
   + versions
      + 9
         - Bar.class

Here the Foo and the Bar class from the JAR root will be used on Java runtimes which are not aware of MR JARs (i.e. Java 8 and earlier), whereas Foo from the JAR root and Bar from META-INF/versions/9 will be used under Java 9 and later. The JAR manifest must contain an entry Multi-Release: true to indicate that the JAR is an MR JAR.

Example: Getting the Id of the Current Process

As an example let’s assume we have a library which defines a class providing the id of process (PID) it is running in. PIDs shall be represented by a descriptor comprising the actual PID and a String describing the provider of the PID:

src/main/java/com/example/ProcessIdDescriptor.java
package com.example;

public class ProcessIdDescriptor {

    private final long pid;
    private final String providerName;

    // constructor, getters ...
}

Up to Java 8, there is no easy way to obtain the id of the running process. One rather hacky approach is to parse the return value of RuntimeMXBean#getName() which is "pid@hostname" in the OpenJDK / Oracle JDK implementation. While that behavior is not guaranteed to be portable across implementations, let’s use it as the basis for our default ProcessIdProvider:

src/main/java/com/example/ProcessIdProvider.java
package com.example;

public class ProcessIdProvider {

    public ProcessIdDescriptor getPid() {
        String vmName = ManagementFactory.getRuntimeMXBean().getName();
        long pid = Long.parseLong( vmName.split( "@" )[0] );
        return new ProcessIdDescriptor( pid, "RuntimeMXBean" );
    }
}

Also let’s create a simple main class for displaying the PID and the provider it was retrieved from:

src/main/java/com/example/Main.java
package com.example;

public class Main {

    public static void main(String[] args) {
        ProcessIdDescriptor pid = new ProcessIdProvider().getPid();

        System.out.println( "PID: " + pid.getPid() );
        System.out.println( "Provider: " + pid.getProviderName() );
    }
}

Note how the source files created so far are located in the regular src/main/java source directory.

Now let’s create another variant of ProcessIdDescriptor based on Java 9’s new ProcessHandle API, which eventually provides a portable way for obtaining the current PID. This source file is located in another source directory, src/main/java9:

src/main/java9/com/example/ProcessIdProvider.java
package com.example;

public class ProcessIdProvider {

    public ProcessIdDescriptor getPid() {
        long pid = ProcessHandle.current().getPid();
        return new ProcessIdDescriptor( pid, "ProcessHandle" );
    }
}

Setting up the build

With all the source files in place, it’s time to configure Maven so an MR JAR gets built.

Three steps are required for that. The first thing is to compile the additional Java 9 sources under src/main/java9. I hoped I could simply set up another execution of the Maven compiler plug-in for that, but I could not find a way which only would compile src/main/java9 but not the ones from src/main/java for second time.

As a work-around, the Maven Antrun plug-in can be used for configuring a second javac run just for the Java 9 specific sources:

pom.xml
...
<properties>
    <java9.sourceDirectory>${project.basedir}/src/main/java9</java9.sourceDirectory>
    <java9.build.outputDirectory>${project.build.directory}/classes-java9</java9.build.outputDirectory>
</properties>
...
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-antrun-plugin</artifactId>
            <executions>
                <execution>
                    <id>compile-java9</id>
                    <phase>compile</phase>
                    <configuration>
                        <tasks>
                            <mkdir dir="${java9.build.outputDirectory}" />
                            <javac srcdir="${java9.sourceDirectory}" destdir="${java9.build.outputDirectory}"
                                classpath="${project.build.outputDirectory}" includeantruntime="false" />
                        </tasks>
                    </configuration>
                    <goals>
                        <goal>run</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
    ...
</build>
...

This uses the target/classes directory (containing the class files emitted by the default compilation) as the classpath, allowing to refer to classes common for all Java versions supported by our MR JAR, e.g. ProcessIdDescriptor. The compiled classes go into target/classes-java9.

The next step is to copy the compiled Java 9 classes into target/classes so they will later be put to the right place within the resulting JAR. The Maven resources plug-in can be used for that:

pom.xml
...
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-resources</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}/META-INF/versions/9</outputDirectory>
                <resources>
                    <resource>
                        <directory>${java9.build.outputDirectory}</directory>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>
...

This will copy the Java 9 class files from target/classes-java9 to target/classes/META-INF/versions/9.

Finally, the Maven JAR plug-in needs to be configured so the Multi-Release entry is added to the manifest file:

pom.xml
...
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <configuration>
        <archive>
            <manifestEntries>
                <Multi-Release>true</Multi-Release>
                <Main-Class>com.example.Main</Main-Class>
            </manifestEntries>
        </archive>
        <finalName>mr-jar-demo.jar</finalName>
    </configuration>
</plugin>
...

And that’s it, we got everything together to build a multi-release JAR. Trigger the build via mvn clean package (using Java 9) to create the JAR in the target directory.

In order to take a look whether the JAR contents is alright, list its contents via jar -tf target/mr-jar-demo.jar. You should see the following:

...
com/example/Main.class
com/example/ProcessIdDescriptor.class
com/example/ProcessIdProvider.class
META-INF/versions/9/com/example/ProcessIdProvider.class
...

Eventually, let’s execute the JAR via java -jar target/mr-jar-demo.jar and examine its output. When using Java 8 or earlier, you’ll see the following:

PID: <some pid>
Provider: RuntimeMXBean

Whereas on Java 9, it’ll be this:

PID: <some pid>
Provider: ProcessHandle

I.e. the ProcessIdProvider class from the JAR root will be used on Java 8 and earlier, and the one from META-INF/versions/9 on Java 9.

Conclusion

While javac, jar, java and other JDK tools already support multi-release JARs, build tools like Maven still need to catch up. Luckily, it can be done using some plug-ins for the time being, but it’s my hope that Maven et al. will provide proper support for creating MR JARs out of the box some time soon.

Others have been thinking about the creation of MR JARs, too. E.g. check out this post by my colleague David M. Lloyd. David uses a separate Maven project for the Java 9 specific classes which are then copied back into the main project using the Maven dependency plug-in. Personally, I prefer to have all the sources within one single project, as I find that a tad simpler, though it’s not without quirks either. Specifically, if you have both, src/main/java and src/main/java9, configured as source directories within your IDE, you’ll get an error about the duplicated class ProcessIdProvider. This can be ignored (you might also remove src/main/java9 as a source directory from the IDE if you don’t need to touch it), but it may be annoying to some.

One could think about having the Java 9 classes in another package, e.g. java9.com.example and then using the Maven shade plug-in to relocate them to com.example when building the project, though this seems quite a lot of effort for a small gain. Ultimately, it’d be desirable if IDEs also added support for MR JARs and multiple compilations with different source and target directories within a single project.

Any feedback on this or other approaches for creating MR JARs is welcome in the comments section below. The complete source code of this blog post can be found on GitHub.

back to top