Skip to content

EAR: add a profile for provisioning the server #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WolfgangHG wants to merge 2 commits into
base: main
Choose a base branch
from
Open

EAR: add a profile for provisioning the server #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0886b49
EAR: add a profile for provisioning the server
WolfgangHG Apr 27, 2025
72e7d56
EAR provisioning: avoid false warning when creating project from arch…
WolfgangHG Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/maven.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,16 @@ jobs:
echo "* Jakarta EE EAR Archetype" >> $GITHUB_STEP_SUMMARY

cd wildfly-jakartaee-ear-archetype/testing

./runtest_provision.sh $ARCHETYPE_VERSION
echo " * :white_check_mark: Provisioned Server" >> $GITHUB_STEP_SUMMARY

./runtest_managed.sh $ARCHETYPE_VERSION
echo " * :white_check_mark: Managed Tests" >> $GITHUB_STEP_SUMMARY

./runtest_provisioned.sh $ARCHETYPE_VERSION
echo " * :white_check_mark: Provisioned Tests" >> $GITHUB_STEP_SUMMARY

$JBOSS_HOME/bin/standalone.sh &
until `$JBOSS_HOME/bin/jboss-cli.sh -c ":read-attribute(name=server-state)" 2> /dev/null | grep -q running`; do
sleep 1
Expand Down
12 changes: 12 additions & 0 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,8 @@
<version.ejb.plugin>3.2.1</version.ejb.plugin>
<version.antrun.plugin>3.2.0</version.antrun.plugin>
<version.archetype.plugin>3.4.1</version.archetype.plugin>
<version.jar.plugin>3.4.2</version.jar.plugin>
<version.install.plugin>3.1.4</version.install.plugin>

<maven.compiler.release>17</maven.compiler.release>

Expand Down Expand Up @@ -161,6 +163,16 @@
<artifactId>maven-antrun-plugin</artifactId>
<version>${version.antrun.plugin}</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>${version.jar.plugin}</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<version>${version.install.plugin}</version>
</plugin>
<!--This plugin is needed for building the archetypes, but not used inside the archetypes. -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
Expand Down
14 changes: 11 additions & 3 deletions wildfly-jakartaee-ear-archetype/README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ WildFly archetype for blank EAR project

This archetype creates a blank EAR project with EJB and Web module.
It is prepared for running Arquillian unit tests.
Optionally, it can provision a WildFly server.
More details can be found in the file "src/main/resources/archetype-resources/README.txt", which is end-user doc and added to the resulting project.

[[newwildflyversion]]
Expand All @@ -31,12 +32,19 @@ $ mvn archetype:generate -DgroupId=my.project.org -DartifactId=sample-jakartaee-

[[testing]]
==== Test the archetype
After having built the archetype, check whether both profiles "arq-remote" and "arq-managed" work. This is done by using scripts found in the directory "testing".
After having built the archetype, check whether all four profiles "arq-remote", "arq-managed", "provision" and "arq-provisioned" work. This is done by using scripts found in the directory "testing".

The four profiles are executed as part of the Github CI

* Profile "arq-managed": set variable JBOSS_HOME, then execute "runtest_managed.bat/.sh <archetypeVersion>" (replace "<archetypeVersion>" with the current archetype version)
* Profile "arq-remote": start WildFly server, then execute "runtest_remote.bat/.sh <archetypeVersion>" (replace "<archetypeVersion>" with the current archetype version)
* Profile "provision": execute "runtest_provision.bat/.sh <archetypeVersion>" (replace "<archetypeVersion>" with the current archetype version)
* Profile "arq-provisioned": execute "runtest_provisioned.bat/.sh <archetypeVersion>" (replace "<archetypeVersion>" with the current archetype version)

Both files create a project from the archetype (in "testing/arq-managed" or "testing/arq-remote"), copy an Arquillian unit test class and an EJB in this project, then build and deploy it to WildFly and execute
the test using the Arquillian profile "arq-managed" or "arq-remote").
The three "arq-....bat/.sh" files create a project from the archetype (in "testing/arq-managed", "testing/arq-remote" or "testing/arq-provisioned"),
copy an Arquillian unit test class and an EJB into this project, then build and deploy it to WildFly and execute
the test using the Arquillian profile "arq-managed", "arq-remote" or "arq-provisioned").

After the test is executed, check the server log for error outputs. In case of success, the outputs "Test is invoked..." and "doTest is invoked..." will be printed in the server console.

The "provison.bat/.sh" files just builds the project and provisions a server.
3 changes: 2 additions & 1 deletion wildfly-jakartaee-ear-archetype/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@
<packaging>maven-archetype</packaging>

<name>WildFly Archetypes: Jakarta EE EAR Webapp</name>
<description>An archetype that generates a starter Jakarta EE project for JBoss WildFly. The project is an EAR, with an EJB-JAR and WAR. It is prepared for Arquillian driven unit tests.</description>
<description>An archetype that generates a starter Jakarta EE project for JBoss WildFly. The project is an EAR, with an EJB-JAR and WAR. It is prepared for Arquillian driven unit tests.
Optionally, a "ready to run your app" provisioned WildFly server can be created using WildFly Glow.</description>

<build>
<resources>
Expand Down
120 changes: 120 additions & 0 deletions wildfly-jakartaee-ear-archetype/src/main/resources-filtered/archetype-resources/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
<module>ejb</module>
<module>web</module>
<module>ear</module>
<module>integration-tests</module>
</modules>

<properties>
Expand All @@ -38,6 +39,8 @@
<version.ejb.plugin>${version.ejb.plugin}</version.ejb.plugin>
<version.failsafe.plugin>${version.failsafe.plugin}</version.failsafe.plugin>
<version.war.plugin>${version.war.plugin}</version.war.plugin>
<version.jar.plugin>${version.jar.plugin}</version.jar.plugin>
<version.install.plugin>${version.install.plugin}</version.install.plugin>

<!-- maven-compiler-plugin -->
<maven.compiler.release>${maven.compiler.release}</maven.compiler.release>
Expand Down Expand Up @@ -261,6 +264,123 @@
</plugins>
</build>
</profile>

<profile>
<!-- This profile will build the project and create a provisioned WildFly server in "target/server" of the ear project.
The provisioned server contains the ear application of this project.
The profile will not execute arquillian tests.
Run with: mvn clean verify -provision -->
<id>provision</id>
<build>
<plugins>
<!-- The WildFly Maven plugin is executed during the "package" goal and provisions a WildFly server. -->
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<version>\${version.wildfly.maven.plugin}</version>
<configuration>
<discover-provisioning-info>
<version>\${version.wildfly.bom}</version>
<!-- "persistence.xml" uses "java:comp/DefaultDataSource".
We tell Glow to create a H2 database similar to the one defined in the full WildFly download. -->
<add-ons>
<add-on>h2-database:default</add-on>
</add-ons>
</discover-provisioning-info>
</configuration>
<executions>
<execution>
<goals>
<!-- The "goal" must be "package" here so that the server is created. -->
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>\${version.failsafe.plugin}</version>
<configuration>
<!--Don't execute arquillian tests: -->
<skipTests>true</skipTests>
</configuration>
</plugin>
</plugins>
</build>
</profile>

<profile>
<!-- An optional Arquillian testing profile that executes tests in the WildFly instance the was created by the "provisioning" profile.
The provisioned server does not contain the ear application of this project, so that Arquillian can deploy the application enriched with server side tests.
This profile will start a new WildFly / JBoss EAP instance, and execute the test, shutting it down when done.
Run with: mvn clean verify -Parq-provisioned -->
<id>arq-provisioned</id>
<dependencies>
<dependency>
<groupId>org.wildfly.arquillian</groupId>
<artifactId>wildfly-arquillian-container-managed</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<!-- The WildFly Maven plugin is executed during the "package" goal and provisions a WildFly server. -->
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<version>${version.wildfly.maven.plugin}</version>
<configuration>
<discover-provisioning-info>
<version>\${version.wildfly.bom}</version>
<!-- "persistence.xml" uses "java:comp/DefaultDataSource".
We tell Glow to create a H2 database similar to the one defined in the full WildFly download. -->
<add-ons>
<add-on>h2-database:default</add-on>
</add-ons>
</discover-provisioning-info>
<!--Don't add the ear application as deployment to the provisioned server: -->
<skipDeployment>true</skipDeployment>
<!--Use a name that differs from the server name of the "provision" profile in order to avoid conflicts if this profile was run before
and a provisioned server already exists in the default location that contains the deployment.
The server is created in a subdir in "target". -->
<provisioningDir>server_arquillian</provisioningDir>
</configuration>
<executions>
<execution>
<goals>
<!-- The "goal" must be "package" here so that the server is created. -->
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>\${version.failsafe.plugin}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- Configuration for Arquillian: -->
<systemPropertyVariables>
<!-- Defines the container qualifier in "arquillian.xml" -->
<arquillian.launch>provisioned</arquillian.launch>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
</profile>

</profiles>

</project>
17 changes: 17 additions & 0 deletions wildfly-jakartaee-ear-archetype/src/main/resources/META-INF/maven/archetype-metadata.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,23 @@
</fileSet>
</fileSets>
</module>
<module id="integration-tests" dir="integration-tests" name="integration-tests">
<fileSets>
<fileSet filtered="true" packaged="true" encoding="UTF-8">
<directory>src/test/java</directory>
<!-- Same workaround: the directory contains files, so include all java files. -->
<includes>
<include>**/*.java</include>
</includes>
</fileSet>
<fileSet filtered="true" encoding="UTF-8">
<directory>src/test/resources</directory>
<includes>
<include>**/*.xml</include>
</includes>
</fileSet>
</fileSets>
</module>
<module id="ear" dir="ear" name="ear">
<fileSets>
<fileSet filtered="true" encoding="UTF-8">
Expand Down
71 changes: 57 additions & 14 deletions wildfly-jakartaee-ear-archetype/src/main/resources/archetype-resources/README.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ a persistence unit "${rootArtifactId}PersistenceUnit" which uses the JakartaEE d
In production environment, you should define a database in WildFly config and point to this database
in "persistence.xml".

If you change the datasource name and use provisioning (profile "provision" or "arq-provisioned", see below),
you have to update the provisioning config.

If you don't use entity beans, you can delete "persistence.xml".
==========================

Expand All @@ -23,13 +26,50 @@ The web application is prepared for Jakarta Faces 4.0 by bundling an empty "face
In case you don't want to use Jakarta Faces, simply delete this file and "src/main/webapp/beans.xml".
==========================

Provisioning:
The project defines two profiles "provision" and "arq-provisioned" that create a provisioned WildFly server (in "target/server" or "target/server_arquillian")
by auto discovering features necessary to run this application.

The profile "provision" is meant to build a server that contains this enterprise application as deployment.
The profile "arq-provisioned" also builds a server, then runs the arquillian tests. This profile does not add the deployment, so that the arquillian
tests can deploy the app themselves enriched with additional test classes.

As "persistence.xml" uses the datasource "java:comp/DefaultDataSource", Glow must be configured to create
the datasource in the WildFly server config. Currently, the default H2 datasource is configured:

<add-ons>
<add-on>h2-database:default</add-on>
</add-ons>

If you change the datasource name in "persistence.xml" or want to use a different datasource, you have to change the Glow configuration
so that it creates the necessary snippets in the WildFly config.

When using a provisioned server, you would probably deploy the app as root application, as the server provides only one application -
no need to have a context path.
You could achieve this by changing the configuration of the "maven-ear-plugin" in "ear/pom.xml", see
https://maven.apache.org/plugins/maven-ear-plugin/examples/customizing-context-root.html
This will register the web application to the context root.
==========================

Testing:
This sample is prepared for running JUnit5 unit tests with the Arquillian framework.

The configuration can be found in "${rootArtifactId}/pom.xml":

Three profiles are defined:
-"default": no integration tests are executed.
The test code is contained in a separate module "integration_tests".
There are two reasons to do so:
Reason 1:
The Arquillian tests pick the ear file, add additional server side test classes and deploy this modified ear. By
placing the tests in their own module, they are run after the ear project was built and thus
can grab the resulting ear file.
Reason 2:
When executing the profile "arq_provisioned", Arquillian deploys the test ear file to the provisioned server.
This server is created when the ear project is built, so the tests have to be run after the project was built.
It is not possible to place test code in the ear project. So they are placed in a separate module that is built
after the ear project build.

Five profiles are defined:
-"default" and "provision": no integration tests are executed.
-"arq-remote": you have to start a WildFly server on your machine. The tests are executed by deploying
the application to this server.
Here the "maven-failsafe-plugin" is enabled so that integration tests can be run.
Expand All @@ -39,21 +79,24 @@ Three profiles are defined:
Instead of using this environment variable, you can also define the path in "arquillian.xml".
Here the "maven-failsafe-plugin" is enabled so that integration tests can be run.
Run maven with these arguments: "clean verify -Parq-managed"
-"arq-provisioned": the tests are executed by deploying the application to the
server that is created during the provisioning step (in "target/server").

The Arquillian test runner is configured with the file "src/test/resources/arquillian.xml"
(duplicated in EJB and WEB project, depending where your tests are placed).
The profile "arq-remote" uses the container qualifier "remote" in this file.
The profile "arq-managed" uses the container qualifier "managed" in this file.

The Arquillian test runner is configured with the file "integration-tests/src/test/resources/arquillian.xml":
-The profile "arq-remote" uses the container qualifier "remote" in this file.
-The profile "arq-managed" uses the container qualifier "managed" in this file.
-The profile "arq-provisioned" uses the container qualifier "provisioned" in this file, which sets
JBOSS_HOME to "../ear/target/server_arquillian" (note the relative path, as we have to move from the "integration_tests"
project to the "ear" project, where the provisioned server is placed).

Unit tests can be added to EJB project and/or to Web project.
Unit tests can be added to the "integration-tests" module, the EJB project and/or to the Web project.

The web project contains an integration test "SampleIT" which shows how to create the deployable EAR file using the ShrinkWrap API.
The "integration-tests" project contains an integration test "SampleIT" which shows how to create the deployable EAR file using the ShrinkWrap API.
You can delete this test file if no tests are necessary.

Why integration tests instead of the "maven-surefire-plugin" testrunner?
The Arquillian test runner deploys the EAR file to the WildFly server and thus you have to build it yourself with the ShrinkWrap API.
The goal "verify" (which triggers the maven-surefire-plugin) is executed later in the maven build lifecyle than the "test" goal so that the target
artifacts ("${rootArtifactId}-ejb.jar" and "${rootArtifactId}-web.war") are already built. You can build
the final EAR by including those files. The "maven-surefire-plugin" is executed before the JAR/WAR files
are created, so those JAR/WAR files would have to be built in the "@Deployment" method, too.
Basically, you can run Arquillian tests using the "maven-surefire-plugin". But due to the structure of the project,
this does not work here. The project provides several profiles, each defines a different way for Arquillian to connect to a WildFly server and
deploy the test application. The "default" profile thus does not have any Arquillian configuration.
As it also does not attach the "maven-failsafe-plugin" to any goal, no integration tests are executed and Arquillian is not invoked.
The "maven-surefire-plugin" test execution is automatically activated, and those test would fail here as no server for Arquillian is configured.
Loading