Skip to content

Commit d5d68dc

Browse files
SanneSanne
committed
HHH-12316 Document usage of the new Feature Packs
1 parent 26bf33a commit d5d68dc

File tree

1 file changed

+226
-54
lines changed

1 file changed

+226
-54
lines changed

‎documentation/src/main/asciidoc/topical/wildfly/Wildfly.adoc

Lines changed: 226 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -7,85 +7,254 @@ The http://wildfly.org/[WildFly application server] includes Hibernate ORM as th
77
This means that you don't need to package Hibernate ORM with the applications you deploy on WildFly,
88
instead the application server will automatically enable Hibernate support if it detects that your application is using JPA.
99

10-
You can also benefit from these modules when not using JPA or JavaEE, to avoid including Hibernate ORM and all its
10+
You can also benefit from these modules when not using JPA, to avoid including Hibernate ORM and all its
1111
dependencies into your deployment.
1212
This will require activating the module explicitly using a `jboss-deployment-structure.xml` file or a Manifest entry:
13-
see https://docs.jboss.org/author/display/WFLY10/Class+Loading+in+WildFly[Class Loading in WildFly] for some examples.
13+
see https://docs.jboss.org/author/display/WFLY/Class+Loading+in+WildFly[Class Loading in WildFly] for some examples.
1414

15-
There may be times though where a newer version of Hibernate ORM is available than the one coming with a given WildFly release.
16-
For that case the Hibernate ORM project provides a ZIP file containing the required modules, so that each new version
17-
can also be included in WildFly. Such a module will not replace the existing Hibernate ORM module, but it will become an
18-
alternative option that your application can choose to use instead of the default version it includes.
15+
Often a newer version of Hibernate ORM is available than the one coming with a given WildFly release; to make sure
16+
you can enjoy the latest version of Hibernate on any reasonably recent WildFly edition we publish _WildFly feature packs_, these can be used with various WildFly provisioning tools to create a custom server with a different
17+
version of Hibernate ORM.
1918

20-
Our goal is to provide a module ZIP file targeted at the WildFly version current at the time of the Hibernate release
21-
(e.g. WildFly 10 for Hibernate ORM releases until 5.2.10, since Hibernate ORM 5.2.11 we provide modules for WildFly 11).
19+
== What is a WildFly feature pack
2220

23-
== Where to download the modules from
21+
WildFly is a runtime built on https://jboss-modules.github.io/jboss-modules/manual/[JBoss Modules]; this is a light weight and efficient modular classloader which allows the different components of a modern server to be defined as independent modules.
2422

25-
The module ZIP files can be downloaded from Maven Central, to facilitate automatic unpacking during your build.
23+
Hibernate ORM and its components are defined as one such module; this implies you can even have multiple different versions of an Hibernate ORM module in the same runtime while having their classpaths isolated from each other: you can add the very latest Hibernate ORM releases to WildFly without having to remove the existing copy.
2624

27-
.Maven identifier for the WildFly modules zip file
25+
This gives you the flexibility to use the latest version for one of your application with the peace of mind that you won't break other applications requiring a different version of Hibernate. We don't generally recommend to abuse this system but it's often useful to be able for example to upgrade and test one application at a time, rather than having to mandate a new version for multiple services and have to update them all in one shot.
26+
27+
A feature pack is a zip file containing some XML files which define the structure of the JBoss Module(s) and list the Java "jar" files which will be needed by identifying them via Maven coordinates.
28+
29+
This has some further benefits:
30+
31+
- A feature pack is very small as it's just a zipped file with some lines of XML.
32+
- In terms of disk space you can build a "thin" server which doesn't actually include a copy of your Maven artifacts but just loads the classes on demand from your local Maven cache.
33+
- You still have the option to build a "full" server so that it can be re-distributed without needing to copy a local Maven repository.
34+
- When using the provisioning tool you benefit from a composable approach, so N different packs can be combined to form a custom server.
35+
- Since the feature pack XML merely lists which artifacts are recommended (rather than including a binary copy) it is easy to override the exact versions; this is ideal to apply micro, urgent fixes.
36+
- A feature pack can declare transitive dependencies on other feature packs, so you will automatically be provided all non-optional dependencies of Hibernate ORM.
37+
38+
It is also interesting to highlight what it is not: differently than most build systems, the focus of JBoss Modules is not on how a project is built but how it should be run.
39+
40+
An important aspect is that runtime dependencies of a JBoss Module are *not transitive*: so for example if the latest Hibernate ORM requires Byte Buddy version 5 (as an example) while any other module that your application needs depends on Byte Buddy version 6 this will not be a problem.
41+
42+
Upgrading your applications could not be easier, as you won't have to ensure that all your dependencies are aligned to use the same versions.
43+
44+
45+
== How to get the latest Hibernate ORM feature pack for WildFly
46+
47+
The feature pack can be downloaded from Maven Central, to facilitate automatic unpacking during your build.
48+
Such a feature pack is released whenever any new version of Hibernate ORM is released.
49+
50+
.Maven identifier for the WildFly feature pack
2851

2952
====
3053
[source, XML]
3154
[subs="verbatim,attributes"]
3255
----
3356
<groupId>org.hibernate</groupId>
34-
<artifactId>hibernate-orm-modules</artifactId>
57+
<artifactId>hibernate-orm-jbossmodules</artifactId>
3558
<version>{fullVersion}</version>
36-
<classifier>wildfly-11-dist</classifier>
37-
<type>zip</type>
3859
----
3960
====
4061

41-
Once downloaded, extract the contents of the ZIP file into the _modules_ directory of your WildFly installation.
62+
Typically you won't download this file directly but you will use either a Maven plugin or a Gradle plugin to build the custom WildFly server.
63+
64+
== Create a Provisioning Configuration File
65+
66+
You will need a small XML file to define which feature packs you want to assemble.
4267

43-
.Example Maven build step to prepare WildFly with custom Hibernate ORM modules for integration tests
68+
The following example will create a full WildFly server but also include a copy of the latest Hibernate ORM modules:
4469

70+
71+
.Example Provisioning Configuration File
4572
====
4673
[source, XML]
4774
[subs="verbatim,attributes"]
4875
----
76+
<server-provisioning xmlns="urn:wildfly:server-provisioning:1.1" copy-module-artifacts="true">
77+
<feature-packs>
78+
<feature-pack
79+
groupId="org.hibernate"
80+
artifactId="hibernate-orm-jbossmodules"
81+
version="${hibernate-orm.version}" />
82+
<feature-pack
83+
groupId="org.wildfly"
84+
artifactId="wildfly-feature-pack"
85+
version="${wildfly.version}" />
86+
</feature-packs>
87+
</server-provisioning>
88+
----
89+
====
90+
91+
Of course should you wish your custom server to have more features you can list additional feature packs.
92+
93+
It is also possible to build a "thin" server by not setting the _copy-module-artifacts_ flag, or you can further customize and filter out things you want removed.
94+
95+
See https://github.com/wildfly/wildfly-build-tools[the README of the WildFly Build Tools project] on Github for more details.
96+
97+
Next you can use either the https://github.com/wildfly/wildfly-build-tools[Maven plugin] or the https://plugins.gradle.org/plugin/org.wildfly.build.featurepack[Gradle plugin] to actually create a fresh copy of your custom server.
98+
99+
== Maven users: invoke the WildFly Provisioning Plugin
100+
101+
Assuming the previous Provisioning Configuration File is saved as `server-provisioning.xml`, you will just have to refer the plugin to it, pick an output directory name and bing the plugin to the build lifecycle.
102+
103+
.Example Maven Provisioning
104+
====
105+
[source, XML]
106+
----
107+
<build>
108+
<plugins>
109+
<plugin>
110+
<groupId>org.wildfly.build</groupId>
111+
<artifactId>wildfly-server-provisioning-maven-plugin</artifactId>
112+
<executions>
113+
<execution>
114+
<id>server-provisioning</id>
115+
<goals>
116+
<goal>build</goal>
117+
</goals>
118+
<phase>compile</phase>
119+
<configuration>
120+
<config-file>server-provisioning.xml</config-file>
121+
<server-name>wildfly-custom</server-name>
122+
</configuration>
123+
</execution>
124+
----
125+
====
126+
127+
==== JPA version override
128+
129+
With WildFly 12 being built with JavaEE7 in mind, it ships the JPA 2.1 API.
130+
131+
Hibernate ORM 5.3 requires JPA 2.2, and it is not possible at this time to replace the JPA API using the Maven provisioning plugin so you'll have to apply a "WildFly patch" as well.
132+
133+
A WildFly patch can be applied from the WildFly CLI; here we show how to automate it all with Maven plugins.
134+
135+
.Example Maven script to patch the JPA version in WildFly:
136+
====
137+
[source, XML]
138+
----
139+
<plugin>
140+
<artifactId>maven-dependency-plugin</artifactId>
141+
<executions>
142+
<execution>
143+
<id>fetch-jpa-patch</id>
144+
<phase>process-test-resources</phase>
145+
<goals>
146+
<goal>copy</goal>
147+
</goals>
148+
<configuration>
149+
<artifactItems>
150+
<artifactItem>
151+
<groupId>org.hibernate.javax.persistence</groupId>
152+
<artifactId>hibernate-jpa-api-2.2-wildflymodules</artifactId>
153+
<classifier>wildfly-12.0.0.Final-patch</classifier>
154+
<version>1.0.0.Beta2</version>
155+
<type>zip</type>
156+
<outputDirectory>${project.build.directory}</outputDirectory>
157+
<overWrite>true</overWrite>
158+
<destFileName>hibernate-jpa-api-2.2-wildflymodules-patch.zip</destFileName>
159+
</artifactItem>
160+
</artifactItems>
161+
</configuration>
162+
</execution>
163+
</executions>
164+
</plugin>
49165
<plugin>
50-
<artifactId>maven-dependency-plugin</artifactId>
51-
<executions>
52-
<execution>
53-
<id>unpack</id>
54-
<phase>pre-integration-test</phase>
55-
<goals>
56-
<goal>unpack</goal>
57-
</goals>
58-
<configuration>
59-
<artifactItems>
60-
<artifactItem>
61-
<groupId>org.wildfly</groupId>
62-
<artifactId>wildfly-dist</artifactId>
63-
<version>${wildflyVersion}</version>
64-
<type>zip</type>
65-
<overWrite>true</overWrite>
66-
<outputDirectory>
67-
${project.build.directory}/wildfly-node1
68-
</outputDirectory>
69-
</artifactItem>
70-
<artifactItem>
71-
<groupId>org.hibernate</groupId>
72-
<artifactId>hibernate-orm-modules</artifactId>
73-
<version>${hibernateVersion}</version>
74-
<classifier>wildfly-11-dist</classifier>
75-
<type>zip</type>
76-
<overWrite>true</overWrite>
77-
<outputDirectory>
78-
${project.build.directory}/wildfly-node1/wildfly-${wildflyVersion}/modules
79-
</outputDirectory>
80-
</artifactItem>
81-
</artifactItems>
82-
</configuration>
83-
</execution>
84-
</executions>
166+
<groupId>org.wildfly.plugins</groupId>
167+
<artifactId>wildfly-maven-plugin</artifactId>
168+
<executions>
169+
<execution>
170+
<id>apply-wildfly-jpa22-patch-file</id>
171+
<phase>pre-integration-test</phase>
172+
<goals>
173+
<goal>execute-commands</goal>
174+
</goals>
175+
<configuration>
176+
<offline>true</offline>
177+
<jbossHome>${jbossHome.provisionedPath}</jbossHome>
178+
<!-- The CLI script below will fail if the patch was already applied in a previous build -->
179+
<fail-on-error>false</fail-on-error>
180+
<commands>
181+
<command>patch apply --override-all ${project.build.directory}/hibernate-jpa-api-2.2-wildflymodules-patch.zip</command>
182+
</commands>
183+
</configuration>
184+
</execution>
185+
</executions>
85186
</plugin>
86187
----
87188
====
88189

190+
== Gradle users: invoke the WildFly Provisioning plugin
191+
192+
A Gradle plugin is also available, and in this case it will take just a couple of lines.
193+
194+
Remember when creating a "thin server": the WildFly classloader will not be able to load jars from the local Gradle cache: this might trigger a second download as it looks into local Maven repositories exclusively.
195+
Especially if you are developing additional feature packs using Gradle, make sure to publish them into a Maven repository so that WildFly can load them.
196+
197+
Follows a full Gradle build script; in contrast to the previous Maven example which is incomplete to keep it short, is a fully working build script. Also it won't require to apply additional patches to replace the JPA version.
198+
199+
.Example Gradle Provisioning
200+
====
201+
[source, Groovy]
202+
----
203+
plugins {
204+
id "org.wildfly.build.provision" version '0.0.6'
205+
}
206+
207+
repositories {
208+
mavenLocal()
209+
mavenCentral()
210+
maven {
211+
name 'jboss-nexus'
212+
url "http://repository.jboss.org/nexus/content/groups/public/"
213+
}
214+
}
215+
216+
provision {
217+
//Optional destination directory:
218+
destinationDir = file("wildfly-custom")
219+
220+
//Update the JPA API:
221+
override( 'org.hibernate.javax.persistence:hibernate-jpa-2.1-api' ) {
222+
groupId = 'javax.persistence'
223+
artifactId = 'javax.persistence-api'
224+
version = '2.2'
225+
}
226+
configuration = file( 'wildfly-server-provisioning.xml' )
227+
//Define variables which need replacing in the provisioning configuration!
228+
variables['wildfly.version'] = '12.0.0.Final'
229+
variables['hibernate-orm.version'] = '5.3.0.Final'
230+
}
231+
----
232+
====
233+
234+
you could paste this into a new file named `build.gradle` in an empty directory, then invoke:
235+
236+
gradle provision
237+
238+
and you'll have a full WildFly 12.0.0.Final server generated in the `wildfly-custom` subdirectory, including a copy of Hibernate ORM version 5.3.0.Final (in addition to the any other version that WildFly normally includes).
239+
240+
241+
==== A note on repositories:
242+
243+
mavenLocal()::
244+
strictly not necessary but will make your builds much faster if you run it more than once.
245+
jboss-nexus::
246+
This additional repository is required. Most components of WildFly are available in Maven Central but there are some occasional exceptions.
247+
248+
==== The JPA version override
249+
250+
The JPA API is a fundamental component of the application server as it is used to integrate with various other standards; at this stage while the feature packs offer some degree of composability it is not yet possible
251+
to have additional, independent copies of the JPA API: it needs to be replaced.
252+
253+
Hibernate ORM 5.3.0 requires JPA 2.2, yet WildFly 12 ships with JPA version 2.1. Luckily this provisioning tool is also able to override any artifact resolution.
254+
255+
Of course when future versions of WildFly will be based on JPA 2.2, this step might soon no longer be necessary.
256+
257+
89258
== WildFly module identifiers: slots and conventions
90259

91260
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.
@@ -135,18 +304,21 @@ In order to use a different module other than the default _org.hibernate:main_ s
135304
Needless to say, this will affect the classpath of your application: if your single application declares multiple
136305
persistence units, they should all make a consistent choice!
137306

138-
This property is documented in the https://docs.jboss.org/author/display/WFLY10/JPA+Reference+Guide[WildFly JPA Reference Guide];
307+
This property is documented in the https://docs.jboss.org/author/display/WFLY/JPA+Reference+Guide[WildFly JPA Reference Guide];
139308
you might want to check it out as it lists several other useful properties.
140309

141310
== Limitations of using the custom WildFly modules
142311

143-
When using these modules you're going to give up on some of the integration which the application server
144-
normally automates.
312+
When using the custom modules provided by the feature packs you're going to give up on some of the integration which the application server normally automates.
145313

146314
For example enabling an Infinispan 2nd level cache is straight forward when using the default Hibernate ORM
147315
module, as WildFly will automatically setup the dependency to the Infinispan and clustering components.
148316
When using these custom modules such integration will no longer work automatically: you can still
149317
enable all normally available features but these will require explicit configuration, as if you were
150318
running Hibernate in a different container, or in no container.
151319

320+
You might be able to get a matching feature pack from the Infinispan or Ehcache projects, you can create a module yourself (after all it's just a simple XML file), or you can just add such additional dependencies in your application as in the old days: modules and feature packs give you some advantages but good old-style jars are also still a viable option.
321+
322+
Needless to say, those users not interested in having the very latest versions can just use the versions integrated in WildFly and benefit from the library combinations carefully tested by the WildFly team.
323+
152324

0 commit comments

Comments
 (0)