HHH-11489 Improve the documentation about upgrading WidFly with latest Hibernate ORM modules

This commit is contained in:
Sanne Grinovero 2017-02-14 17:05:55 +00:00
parent 54503bf7f4
commit f2728836af
2 changed files with 156 additions and 23 deletions

View File

@ -234,7 +234,7 @@ task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {
backends "html5"
separateOutputDirs false
options logDocuments: true
attributes icons: 'font', experimental: true, 'source-highlighter': 'prettify'
attributes icons: 'font', experimental: true, 'source-highlighter': 'prettify', majorMinorVersion: rootProject.hibernateMajorMinorVersion, fullVersion: rootProject.hibernateFullVersion
}

View File

@ -1,27 +1,114 @@
= Updating Hibernate ORM within WildFly
= Using latest Hibernate ORM within WildFly
== Hibernate ORM within WildFly
The http://wildfly.org/[WildFly application server] includes Hibernate ORM as the default JPA provider out of the box.
The http://wildfly.org/[WildFly application server] comes with Hibernate as the default JPA provider out of the box.
This means that you don't need to package Hibernate ORM with the applications you deploy on WildFly,
instead the application server will automatically enable Hibernate support if it detects that your application is using JPA.
You can also benefit from these modules when not using JPA or JavaEE, to avoid including Hibernate ORM and all its
dependencies into your deployment.
This will require activating the module explicitly using a `jboss-deployment-structure.xml` file or a Manifest entry:
see https://docs.jboss.org/author/display/WFLY10/Class+Loading+in+WildFly[Class Loading in WildFly] for some examples.
There may be times though where a newer version of Hibernate ORM is available than the one coming with a given WildFly release.
For that case the Hibernate ORM project provides ZIP files containing the required modules to update a WildFly installation to newer versions of Hibernate when they are released.
For that case the Hibernate ORM project provides a ZIP file containing the required modules, so that each new version
can also be included in WildFly. Such a module will not replace the existing Hibernate ORM module, but it will become an
alternative option that your application can choose to use instead of the default version it includes.
Our goal is to provide a module ZIP file targeted at the WildFly version current at the time of the Hibernate release (e.g. WildFly 10 for Hibernate 5.1.x and 5.2.x).
The module ZIP files are available from https://sourceforge.net/projects/hibernate/files/hibernate-orm/[SourceForge] and https://bintray.com/hibernate/bundles/hibernate-orm[BinTray], alike the full ZIP/TAR.GZ distributions.
Once downloaded, extract the contents of the ZIP file into the _modules_ directory of your WildFly installation
(shut down the application server before, should it be running).
Note that the Hibernate ORM modules coming with WildFly will remain untouched,
i.e. you can switch between the original version and the new version from the ZIP file as needed as a matter of configuration.
== Where to download the modules from
The module system of the application server identifies modules using a name and a version.
By default, the module _org.hibernate:main_ will be used to provide JPA support for given deployments (_main_ representing the Hibernate version coming with WildFly itself).
In order to use another version specify the identifier of the Hibernate ORM module to use via the following property in the _persistence.xml_ file of your application:
The module ZIP files can be downloaded from Maven Central, to facilitate automatic unpacking during your build.
.Maven identifier for the WildFly modules zip file
[[wildfly-using-custom-hibernate-orm-version]]
.Using a specific version of Hibernate ORM
====
[source, XML]
[subs="verbatim,attributes"]
----
<groupId>org.hibernate</groupId>
<artifactId>hibernate-orm-modules</artifactId>
<version>{fullVersion}</version>
<classifier>wildfly-10-dist</classifier>
<type>zip</type>
----
====
Once downloaded, extract the contents of the ZIP file into the _modules_ directory of your WildFly installation.
.Example Maven build step to prepare WildFly with custom Hibernate ORM modules for integration tests
====
[source, XML]
[subs="verbatim,attributes"]
----
<plugin>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>unpack</id>
<phase>pre-integration-test</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.wildfly</groupId>
<artifactId>wildfly-dist</artifactId>
<version>${wildflyVersion}</version>
<type>zip</type>
<overWrite>true</overWrite>
<outputDirectory>
${project.build.directory}/wildfly-node1
</outputDirectory>
</artifactItem>
<artifactItem>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-orm-modules</artifactId>
<version>${hibernateVersion}</version>
<classifier>wildfly-10-dist</classifier>
<type>zip</type>
<overWrite>true</overWrite>
<outputDirectory>
${project.build.directory}/wildfly-node1/wildfly-${wildflyVersion}/modules
</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
----
====
== WildFly module identifiers: slots and conventions
Note that the Hibernate ORM modules coming with WildFly will remain untouched: you can switch between the original version and the new version from the ZIP file as needed as a matter of configuration. Different applications can use different versions.
The application server identifies modules using a name and a _slot_.
By default, the module _org.hibernate:main_ will be used to provide JPA support for given deployments: _main_ is the default slot and represents the copy of Hibernate ORM coming with WildFly itself.
By convention all modules included with WildFly use the "main" slot, while the modules released by the Hibernate project
will use a slot name which matches the version, and also provide an alias to match its "major.minor" version.
Our suggestion is to depend on the module using the "major.minor" representation, as this simplifies rolling out bugfix
releases (micro version updates) of Hibernate ORM without changing application configuration (micro versions are always expected to be backwards compatible and released as bugfix only).
For example if your application wants to use the latest version of Hibernate ORM version {majorMinorVersion}.x it should declare to use the module _org.hibernate:{majorMinorVersion}_. You can of course decide to use the full version instead for more precise control, in case an application requires a very specific version.
== Switch to a different Hibernate ORM slot
In order to use a different module other than the default _org.hibernate:main_ specify the identifier of the module you wish to use via the `jboss.as.jpa.providerModule` property in the _persistence.xml_ file of your application, as in the following example.
[[wildfly-using-custom-hibernate-orm-version]]
.Using an alternative module slot of Hibernate ORM
====
[source, XML]
[subs="verbatim,attributes"]
----
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -29,12 +116,12 @@ In order to use another version specify the identifier of the Hibernate ORM modu
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
version="2.1" >
<persistence-unit name="examplePu" transaction-type="JTA">
<persistence-unit name="examplePu">
<!-- ... -->
<properties>
<property name="jboss.as.jpa.providerModule" value="org.hibernate:<%VERSION%>"/>
<property name="jboss.as.jpa.providerModule" value="org.hibernate:{majorMinorVersion}"/>
</properties>
<!-- ... -->
@ -44,10 +131,56 @@ In order to use another version specify the identifier of the Hibernate ORM modu
----
====
For `<%VERSION%>` specify the version of the module ZIP you downloaded, e.g. `5.1.1.Final`.
Alternatively you can specify just the minor version, e.g. `5.1`.
That way you can update your WildFly server with further micro updates of the same Hibernate ORM release family as they are released,
without having to adapt your _persistence.xml_ upon each micro update.
Note that you can have several micro updates of the same release family next to each other within a WildFly instance
and switch between them by means of the properties shown above.
If you are specifying just the minor version, the modules from the ZIP file you unpacked last will be used.
Needless to say, this will affect the classpath of your application: if your single application declares multiple
persistence units, they should all make a consistent choice!
This property is documented in the https://docs.jboss.org/author/display/WFLY10/JPA+Reference+Guide[WildFly JPA Reference Guide];
you might want to check it out as it lists several other useful properties.
== Avoiding outdated Javassist versions from WildFly
Since Hibernate ORM version 5.2, it requires a more recent version of Javassist than the one provided by WildFly 10.
Unfortunately the JPA subsystem of WildFly will expose its Javassist version to any JPA application even if you override
the module using the above mentioned `jboss.as.jpa.providerModule` property.
To avoid this problem use a `jboss-deployment-structure.xml` to explicitly demand to not get the WildFly copy of
javassist. This will allow Hibernate ORM to use the Javassist version provided by its own module, which will contain
the recommended versions.
.WildFly configuration file to avoid the wrong Javassist version
====
[source, XML]
[subs="verbatim,attributes"]
----
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">
<deployment>
<exclusions>
<module name="org.javassist" />
</exclusions>
</deployment>
</jboss-deployment-structure>
----
====
This file needs to be included in your deployment, in the top level archive.
The exact position depends on the deployment kind: for example when deploying a `WAR` file, include it in `WEB-INF`;
other common deployment archives will expect this resource to be found in `META-INF`.
See https://docs.jboss.org/author/display/WFLY10/Class+Loading+in+WildFly[Class Loading in WildFly] for more details
about using a custom `jboss-deployment-structure.xml`.
== Limitations of using the custom WildFly modules
When using these modules you're going to give up on some of the integration which the application server
normally automates.
For example enabling an Infinispan 2nd level cache is straight forward when using the default Hibernate ORM
module, as WildFly will automatically setup the dependency to the Infinispan and clustering components.
When using these custom modules such integration will no longer work automatically: you can still
enable all normally available features but these will require manual configuration, as if you were
running Hibernate in a different container, or in no container.