Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
You will learn how to build an application with multiple modules with Gradle and Open Liberty.
A Jakarta Platform, Enterprise Edition (Jakarta EE) application consists of modules that work together as one entity. An enterprise archive (EAR) is a wrapper for a Jakarta EE application, which consists of web archive (WAR) and Java archive (JAR) files. To deploy or distribute the Jakarta EE application into new environments, all the modules and resources must first be packaged into an EAR file.
In this guide, you will learn how to:
-
establish a dependency between a web module and a Java library module,
-
use Gradle to package the WAR file and the JAR file into an EAR file so that you can run and test the application on Open Liberty, and
-
use Liberty Gradle plug-in to develop a multi-module application in dev mode without having to prebuild the JAR and WAR files. In dev mode, your changes are automatically picked up by the running Liberty instance.
You will build a unit converter application that converts heights from centimeters into feet and inches. The application will request the user to enter a height value in centimeters. Then, the application processes the input by using functions that are found in the JAR file to return the height value in imperial units.
Access partial implementation of the application from the start
folder. This folder includes a web module in the war
folder, a Java library in the jar
folder, and template files in the ear
folder. However, the Java library and the web module are independent projects, and you will need to complete the following steps to implement the application:
-
Add a dependency relationship between the two modules.
-
Assemble the entire application into an EAR file.
-
Aggregate the entire build.
-
Test the multi-module application.
The finish
directory in the root of this guide contains the finished application. Give it a try before you proceed.
To try out the application, first go to the finish
directory and run the following gradle goal to build the War and Jar application:
cd finish ./gradlew clean libertyPackage
To deploy your EAR application on Open Liberty, run the gradle libertyRun
goal from the finish directory .
./gradlew clean libertyRun
Once the Liberty instance is running, you can find the application at the following URL: http://localhost:9080/converter/
After you are finished checking out the application, stop the Open Liberty instance by pressing CTRL+C
in the command-line session where you ran the Liberty. Alternatively, you can run the libertyStop
task from the finish
directory in another command-line session:
You can run the clean
task from the finish
directory as well, which will internally call libertyStop
:
./gradlew libertyStop
To use a Java library in your web module, you must add a dependency relationship between the two modules.
As you might have noticed, each module has its own build.gradle
file. Each module has its own build.gradle
file because each module is treated as an independent project. You can rebuild, reuse, and reassemble every module on its own.
Navigate to the start
directory to begin.
Replace the war/build file.
war/build.gradle
war/build.gradle
link:finish/war/build.gradle[role=include]
The added dependency
element is the Java library module that implements the functions that you need for the unit converter.
Although the parent/child
structure is not normally needed for multi-module applications, adding it helps us to better organize all of the projects. This structure allows all of the child projects to make use of the plugins that are defined in the parent build.gradle
file, without having to define them again in the child build.gradle
files.
To deploy the entire application on Open Liberty, first package the application. Use the EAR project to assemble multiple modules into an EAR file.
Navigate to the ear
folder and find a template build.gradle
file.
Replace the ear/build file.
ear/build.gradle
ear/build.gradle
link:finish/ear/build.gradle[role=include]
Apply the liberty
and ear
plugin to configure the project as ear
The war
project is added as a Project dependency and webModule
is specified in deployment descriptor to provide context path as /converter
If no context path is specified, gradle automatically uses the WAR file artifactId ID as the context root for the application while generating the application.xml file.
To deploy and run an EAR application on an Open Liberty instance, you need to provide a Liberty’s server.xml
configuration file.
Create the Libertyserver.xml
configuration file.ear/src/main/liberty/config/server.xml
server.xml
link:finish/ear/src/main/liberty/config/server.xml[role=include]
You must configure the server.xml
configuration file with the enterpriseApplication
element to specify the location of your EAR application.
Because you have multiple modules, aggregate the gradle projects to simplify the build process.
settings.gradle
is used to specify multiple modules
Replace the start/settings file.
settings.gradle
start/settings.gradle
link:finish/settings.gradle[role=include]
Include all project directories
Create a parent build.gradle
file under the start
directory to link all of the child modules together. A template is provided for you.
Replace the start/build file.
build.gradle
start/build.gradle
link:finish/build.gradle[role=include]
Set the basic configuration
for the project. Apply gradle-java-plugin
to all sub projects. This allows each child module to inherit the plug-ins, so that you can use the these to develop the modules.
You can now develop the application and the different modules together in dev mode by using the Liberty gradle plug-in. To learn more about how to use dev mode with multiple modules, check out the Documentation.
Navigate to the start
directory to begin.
To deploy your EAR application on Open Liberty and start in dev mode, run the gradle libertyDev
goal from the start directory .
./gradlew clean libertyRun
Update the HeightsBean
class to use the Java library module that implements the functions that you need for the unit converter.
Navigate to the start
directory.
Replace theHeightsBean
class in thewar
directory.war/src/main/java/io/openliberty/guides/multimodules/web/HeightsBean.java
HeightsBean.java
link:finish/war/src/main/java/io/openliberty/guides/multimodules/web/HeightsBean.java[role=include]
The getFeet(cm)
invocation was added to the setHeightFeet
method to convert a measurement into feet.
The getInches(cm)
invocation was added to the setHeightInches
method to convert a measurement into inches.
You can check out the running application by going to the http://localhost:9080/converter/ URL.
Now try updating the converter so that it converts heights correctly, rather than returning 0.
Replace theConverter
class in thejar
directory.jar/src/main/java/io/openliberty/guides/multimodules/lib/Converter.java
Converter.java
link:finish/jar/src/main/java/io/openliberty/guides/multimodules/lib/Converter.java[role=include]
Change the getFeet
method so that it converts from centimetres to feet, and the getInches
method so that it converts from centimetres to inches. Update the sum
, diff
, product
and quotient
functions so that they add, subtract, multiply, and divide 2 numbers respectively.
Now revisit the application at the http://localhost:9080/converter/ URL. Try entering a height in centimetres and see if it converts correctly.
To test the multi-module application, add integration tests to the EAR project.
Create the integration test class in theear
directory.ear/src/test/java/it/io/openliberty/guides/multimodules/IT.java
IT.java
link:finish/ear/src/test/java/it/io/openliberty/guides/multimodules/IT.java[role=include]
The testIndexPage
tests to check that you can access the landing page.
The testHeightsPage
tests to check that the application can process the input value and calculate the result correctly.
Because you started Open Liberty in dev mode, press the enter/return key to run the tests.
You will see the following output:
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.multimodules.IT
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.712 sec - in it.io.openliberty.guides.multimodules.IT
Results :
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
When you are done checking out the service, exit dev mode by pressing CTRL+C
in the command-line session where you ran the Liberty.
You aggregated and developed the application. Now, you can run ./gradlew clean libertyPackage
once from the start
directory and it will automatically build all your modules. This command creates a JAR file in the jar/build
directory, a WAR file in the war/build
directory, and an EAR file that contains the JAR and WAR files in the ear/build
directory.
Run the following command from the start directory to build the entire application:
./gradlew clean libertyPackage
Since the modules are independent, you can re-build them individually by running ./gradlew clean build
from the corresponding start
directory for each module.
Or, run ./gradlew <child project>:build
from the start directory.
You built and tested a multi-module Java application for unit conversion with gradle on Open Liberty.