HHH-11489 Improve the documentation about upgrading WidFly with latest Hibernate ORM modules
This commit is contained in:
Sanne Grinovero
parent
54503bf7f4
commit
f2728836af
|
|
@ -234,7 +234,7 @@ task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {
|
||||||
backends "html5"
|
backends "html5"
|
||||||
separateOutputDirs false
|
separateOutputDirs false
|
||||||
options logDocuments: true
|
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
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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,
|
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.
|
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.
|
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).
|
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
|
== Where to download the modules from
|
||||||
(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.
|
|
||||||
|
|
||||||
The module system of the application server identifies modules using a name and a version.
|
The module ZIP files can be downloaded from Maven Central, to facilitate automatic unpacking during your build.
|
||||||
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:
|
.Maven identifier for the WildFly modules zip file
|
||||||
|
|
||||||
[[wildfly-using-custom-hibernate-orm-version]]
|
|
||||||
.Using a specific version of Hibernate ORM
|
|
||||||
====
|
====
|
||||||
[source, XML]
|
[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"
|
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
|
||||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
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"
|
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
|
||||||
version="2.1" >
|
version="2.1" >
|
||||||
|
|
||||||
<persistence-unit name="examplePu" transaction-type="JTA">
|
<persistence-unit name="examplePu">
|
||||||
|
|
||||||
<!-- ... -->
|
<!-- ... -->
|
||||||
|
|
||||||
<properties>
|
<properties>
|
||||||
<property name="jboss.as.jpa.providerModule" value="org.hibernate:<%VERSION%>"/>
|
<property name="jboss.as.jpa.providerModule" value="org.hibernate:{majorMinorVersion}"/>
|
||||||
</properties>
|
</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`.
|
Needless to say, this will affect the classpath of your application: if your single application declares multiple
|
||||||
Alternatively you can specify just the minor version, e.g. `5.1`.
|
persistence units, they should all make a consistent choice!
|
||||||
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.
|
This property is documented in the https://docs.jboss.org/author/display/WFLY10/JPA+Reference+Guide[WildFly JPA Reference Guide];
|
||||||
Note that you can have several micro updates of the same release family next to each other within a WildFly instance
|
you might want to check it out as it lists several other useful properties.
|
||||||
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.
|
== 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.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue