HHH-10812 Adding documentation

This commit is contained in:
Gunnar Morling 2016-06-27 17:19:59 +02:00 committed by Steve Ebersole
parent 9ec9399ac4
commit 62b5cf6eac
2 changed files with 55 additions and 0 deletions

View File

@ -14,6 +14,7 @@ NOTE: This is still very much a work in progress. <<helping,Help>> is definitely
** For (semi-deprecated) bootstrapping of a SessionFactory using the legacy Configuration approach, see the <<bootstrap/LegacyBootstrapping.adoc#,Legacy Bootstrapping Guide>>
* For information on generated (non-identifier) values, see the <<generated/GeneratedValues.adoc#,Generated Values Guide>>
* For information on logging, see <<logging/Logging.adoc#,Logging Guide>>
* For information on how to use the latest version of Hibernate ORM on WildFly, see <<wildfly/Wildfly.adoc#,Using Hibernate ORM on Wildfly>>
* Others coming soon
== Tooling

View File

@ -0,0 +1,54 @@
= Updating Hibernate ORM within WildFly
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 works with JPA/Hibernate.
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 a ZIP file containing the required modules to update a WildFly installation to newer versions.
The module ZIP file is available from SourceForge and BinTray, alike the ZIP/TAR.GZ distributions (TODO: Add link).
As of Hibernate ORM 5.1.1, a ZIP file for upgrading WildFly 10 to that Hibernate version (from 5.0.x) is provided.
The general goal is to provide a ZIP file for bringing new versions of Hibernate ORM to the WildFly version current at the time of the Hibernate release.
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.
The module system of the application server uses what's called "slots" to differentiate between several versions of one module.
By default, slot "main" of the Hibernate ORM modules will be used to provide JPA support for given deployments (representing the Hibernate version coming with WildFly itself).
In order to use another slot, specify the following two property in the _persistence.xml_ file of your application:
[[wildfly-using-custom-hibernate-orm-version]]
.Using a specific version of Hibernate ORM
====
[source, XML]
----
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
version="2.1" >
<persistence-unit name="examplePu" transaction-type="JTA">
<!-- ... -->
<properties>
<property name="jboss.as.jpa.providerModule" value="org.hibernate:<%VERSION%>"/>
</properties>
<!-- ... -->
</persistence-unit>
</persistence>
----
====
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 as module slot, the modules from the ZIP file you unpacked last will be used.