Try what you’ll build

Adding dependencies between WAR and JAR modules
Assembling multiple modules into an EAR file
Aggregating the entire build
Developing the application

Updating the Java classes in different modules
Testing the multi-module application
Running the tests

Building the multi-module application
Nice work! Where to next?

Creating a multi-module application

30 minutes

You will learn how to build an application with multiple modules with Maven and Open Liberty.

Prerequisites:

Table of contents

What you’ll learn

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 Maven 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 Maven 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.

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

Copied to clipboard

git clone https://github.com/openliberty/guide-maven-multimodules.git
cd guide-maven-multimodules

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Before you begin, make sure you have all the necessary prerequisites.

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.

Try what you’ll build

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 Maven goal to build the application:

Copied to clipboard

cd finish
mvn install

To deploy your EAR application on Open Liberty, run the Maven liberty:run goal from the finish directory using the -pl flag to specify the ear project. The -pl flag specifies the project where the Maven goal runs.

Copied to clipboard

mvn -pl ear liberty:run

After you see the following message, your Liberty instance is ready:

The defaultServer server is ready to run a smarter planet.

When 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 liberty:stop goal using the -pl ear flag from the finish directory in another command-line session:

Copied to clipboard

mvn -pl ear liberty:stop

Adding dependencies between WAR and JAR modules

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 pom.xml file. Each module has its own pom.xml 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/POM file.

Copied to clipboard

war/pom.xml

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 plug-ins that are defined in the parent pom.xml file, without having to define them again in the child pom.xml files.

Assembling multiple modules into an EAR file

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 pom.xml file.

Replace the ear/POM file.

Copied to clipboard

ear/pom.xml

Set the basic configuration for the project and set the packaging element to ear.

The Java library module and the web module were added as dependencies. Specify a type of war for the web module. If you don’t specify this type for the web module, Maven looks for a JAR file.

The definition and configuration of the maven-ear-plugin plug-in were added to create an EAR file. Define the webModule module to be packaged into the EAR file. To customize the context root of the application, set the contextRoot element to /converter in the webModule. Otherwise, Maven 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 Liberty server.xml configuration file.

Copied to clipboard

ear/src/main/liberty/config/server.xml

You must configure the server.xml configuration file with the enterpriseApplication element to specify the location of your EAR application.

Aggregating the entire build

Because you have multiple modules, aggregate the Maven projects to simplify the build process.

Create a parent pom.xml file under the start directory to link all of the child modules together. A template is provided for you.

Replace the start/POM file.

Copied to clipboard

pom.xml

Set the basic configuration for the project. Set pom as the value for the packaging element of the parent pom.xml file.

In the parent pom.xml file, list all of the modules that you want to aggregate for the application.

Adding the maven-war-plugin, maven-compiler-plugin, and liberty-maven-plugin plug-ins allows each child module to inherit the plug-ins, so that you can use the these to develop the modules.

Developing the application

You can now develop the application and the different modules together in dev mode by using the Liberty Maven 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.

When you run Open Liberty in dev mode, dev mode listens for file changes and automatically recompiles and deploys your updates whenever you save a new change. Run the following goal to start Open Liberty in dev mode:

Copied to clipboard

mvn liberty:dev

After you see the following message, your Liberty instance is ready in dev mode:

**************************************************************
*    Liberty is running in dev mode.

Dev mode holds your command-line session to listen for file changes. Open another command-line session to continue, or open the project in your editor.

Updating the Java classes in different modules

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 the HeightsBean class in the war directory.

Copied to clipboard

war/src/main/java/io/openliberty/guides/multimodules/web/HeightsBean.java

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 the Converter class in the jar directory.

Copied to clipboard

jar/src/main/java/io/openliberty/guides/multimodules/lib/Converter.java

Change the getFeet method so that it converts from centimeters to feet, and the getInches method so that it converts from centimeters to inches. Update the sum, diff, product, and quotient functions so that they add, subtract, multiply, and divide 2 numbers respectively.

Now check out the application again at the http://localhost:9080/converter/ URL. Try entering a height in centimeters and see whether it converts correctly.

Testing the multi-module application

To test the multi-module application, add integration tests to the EAR project.

Create the integration test class in the ear directory.

Copied to clipboard

ear/src/test/java/it/io/openliberty/guides/multimodules/IT.java

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.

Running the tests

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.

Building the multi-module application

You have aggregated and developed the application. Now, you can run mvn install from the start directory to build all your modules. This command creates a JAR file in the jar/target directory, a WAR file in the war/target directory, and an EAR file that contains the WAR file in the ear/target directory.

Run the following command from the start directory to build the entire application:

Copied to clipboard

mvn install

Because the modules are independent, you can re-build them individually by running mvn install from the corresponding start directory for each module.

Or, run mvn -pl <child project> install from the start directory.

 1<?xml version='1.0' encoding='utf-8'?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0"
 3    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 4    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 5    http://maven.apache.org/xsd/maven-4.0.0.xsd">
 6
 8    <parent>
 9        <groupId>io.openliberty.guides</groupId>
10        <artifactId>guide-maven-multimodules</artifactId>
11        <version>1.0-SNAPSHOT</version>
12    </parent>
14
15    <modelVersion>4.0.0</modelVersion>
16
17    <groupId>io.openliberty.guides</groupId>
18    <artifactId>guide-maven-multimodules-war</artifactId>
19    <packaging>war</packaging>
20    <version>1.0-SNAPSHOT</version>
21    <name>guide-maven-multimodules-war</name>
22    <url>http://maven.apache.org</url>
23
24    <properties>
25        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
26        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
27        <maven.compiler.source>11</maven.compiler.source>
28        <maven.compiler.target>11</maven.compiler.target>
29    </properties>
30
31    <dependencies>
32        <!-- Provided dependencies -->
33        <dependency>
34            <groupId>jakarta.platform</groupId>
35            <artifactId>jakarta.jakartaee-api</artifactId>
36            <version>10.0.0</version>
37            <scope>provided</scope>
38        </dependency>
39        <dependency>
40            <groupId>org.eclipse.microprofile</groupId>
41            <artifactId>microprofile</artifactId>
42            <version>7.0</version>
43            <type>pom</type>
44            <scope>provided</scope>
45        </dependency>
46
48        <dependency>
49            <groupId>io.openliberty.guides</groupId>
50            <artifactId>guide-maven-multimodules-jar</artifactId>
51            <version>1.0-SNAPSHOT</version>
52        </dependency>
54
55    </dependencies>
56
57</project>58

  1<?xml version='1.0' encoding='utf-8'?>
  2<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
  3    http://maven.apache.org/xsd/maven-4.0.0.xsd">
  4
  5    <parent>
  6        <groupId>io.openliberty.guides</groupId>
  7        <artifactId>guide-maven-multimodules</artifactId>
  8        <version>1.0-SNAPSHOT</version>
  9    </parent>
 10
 11    <modelVersion>4.0.0</modelVersion>
 12
 14    <groupId>io.openliberty.guides</groupId>
 15    <artifactId>guide-maven-multimodules-ear</artifactId>
 16    <version>1.0-SNAPSHOT</version>
 18    <packaging>ear</packaging>
 21
 22    <properties>
 23        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 24        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
 25        <maven.compiler.source>11</maven.compiler.source>
 26        <maven.compiler.target>11</maven.compiler.target>
 27        <!-- Liberty configuration -->
 28        <liberty.var.http.port>9080</liberty.var.http.port>
 29        <liberty.var.https.port>9443</liberty.var.https.port>
 30    </properties>
 31
 32    <dependencies>
 33        <!-- web and jar modules as dependencies -->
 36        <dependency>
 37            <groupId>io.openliberty.guides</groupId>
 38            <artifactId>guide-maven-multimodules-jar</artifactId>
 39            <version>1.0-SNAPSHOT</version>
 40            <type>jar</type>
 41            <scope>provided</scope>
 42        </dependency>
 45        <dependency>
 46            <groupId>io.openliberty.guides</groupId>
 47            <artifactId>guide-maven-multimodules-war</artifactId>
 48            <version>1.0-SNAPSHOT</version>
 50            <type>war</type>
 52        </dependency>
 55
 56        <!-- For tests -->
 57        <dependency>
 58            <groupId>org.junit.jupiter</groupId>
 59            <artifactId>junit-jupiter</artifactId>
 60            <version>5.12.0</version>
 61            <scope>test</scope>
 62        </dependency>
 63    </dependencies>
 64
 65    <build>
 66        <finalName>${project.artifactId}</finalName>
 67        <plugins>
 69            <plugin>
 70                <groupId>org.apache.maven.plugins</groupId>
 71                <artifactId>maven-ear-plugin</artifactId>
 72                <version>3.3.0</version>
 73                <configuration>
 74                    <modules>
 76                        <webModule>
 77                            <groupId>io.openliberty.guides</groupId>
 78                            <artifactId>guide-maven-multimodules-war</artifactId>
 79                            <uri>/guide-maven-multimodules-war-1.0-SNAPSHOT.war</uri>
 80                            <!-- Set custom context root -->
 82                            <contextRoot>/converter</contextRoot>
 84                        </webModule>
 86                    </modules>
 87                </configuration>
 88            </plugin>
 90
 91            <!-- Since the package type is ear,
 92            need to run testCompile to compile the tests -->
 94            <plugin>
 95                <groupId>org.apache.maven.plugins</groupId>
 96                <artifactId>maven-compiler-plugin</artifactId>
 97                <executions>
 98                    <execution>
 99                        <phase>test-compile</phase>
101                        <goals>
102                            <goal>testCompile</goal>
103                        </goals>
105                    </execution>
106                </executions>
107            </plugin>
109
110            <!-- Plugin to run integration tests -->
111            <plugin>
112                <groupId>org.apache.maven.plugins</groupId>
113                <artifactId>maven-failsafe-plugin</artifactId>
114                <version>3.5.2</version>
115                <configuration>
116                    <systemPropertyVariables>
117                        <http.port>
118                            ${liberty.var.http.port}
119                        </http.port>
120                        <https.port>
121                            ${liberty.var.https.port}
122                        </https.port>
123                        <cf.context.root>/converter</cf.context.root>
124                    </systemPropertyVariables>
125                </configuration>
126            </plugin>
127        </plugins>
128    </build>
129
130</project>131

 1<server description="Sample Liberty server">
 2
 3    <featureManager>
 4        <platform>jakartaee-10.0</platform>
 5        <feature>pages</feature>
 6    </featureManager>
 7
 8    <variable name="http.port" defaultValue="9080" />
 9    <variable name="https.port" defaultValue="9443" />
10
12    <httpEndpoint host="*" httpPort="${http.port}"
13        httpsPort="${https.port}" id="defaultHttpEndpoint" />
14
16    <enterpriseApplication id="guide-maven-multimodules-ear"
17        location="guide-maven-multimodules-ear.ear"
18        name="guide-maven-multimodules-ear" />
21
22</server>23

 1<?xml version='1.0' encoding='utf-8'?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0"
 3    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 4    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 5    http://maven.apache.org/xsd/maven-4.0.0.xsd">
 6
 7    <modelVersion>4.0.0</modelVersion>
 8
11    <groupId>io.openliberty.guides</groupId>
13    <artifactId>guide-maven-multimodules</artifactId>
14    <version>1.0-SNAPSHOT</version>
16    <packaging>pom</packaging>
19
21    <modules>
22        <module>jar</module>
23        <module>war</module>
24        <module>ear</module>
25    </modules>
27
28    <build>
29        <pluginManagement>
30            <plugins>
32                <plugin>
33                    <artifactId>maven-war-plugin</artifactId>
34                    <version>3.4.0</version>
35                </plugin>
38                <plugin>
39                    <artifactId>maven-compiler-plugin</artifactId>
40                    <version>3.14.0</version>
41                </plugin>
43            </plugins>
44        </pluginManagement>
45        <plugins>
46            <!-- Enable liberty-maven plugin -->
48            <plugin>
49                <groupId>io.openliberty.tools</groupId>
50                <artifactId>liberty-maven-plugin</artifactId>
51                <version>3.11.2</version>
52            </plugin>
54        </plugins>
55    </build>
56</project>57

12package it.io.openliberty.guides.multimodules;
13
14import static org.junit.jupiter.api.Assertions.assertEquals;
15import static org.junit.jupiter.api.Assertions.assertTrue;
16
17import java.io.BufferedReader;
18import java.io.InputStreamReader;
19import java.net.HttpURLConnection;
20import java.net.URL;
21
22import org.junit.jupiter.api.Test;
23
24public class IT {
25    String port = System.getProperty("http.port");
26    String war = "converter";
27    String urlBase = "http://localhost:" + port + "/" + war + "/";
28
29    @Test
31    public void testIndexPage() throws Exception {
32        String url = this.urlBase;
33        HttpURLConnection con = testRequestHelper(url, "GET");
34        assertEquals(200, con.getResponseCode(), "Incorrect response code from " + url);
35        assertTrue(testBufferHelper(con).contains("Enter the height in centimeters"),
36                        "Incorrect response from " + url);
37    }
39
40    @Test
42    public void testHeightsPage() throws Exception {
43        String url = this.urlBase + "heights.jsp?heightCm=10";
44        HttpURLConnection con = testRequestHelper(url, "POST");
45        assertTrue(testBufferHelper(con).contains("3        inches"),
46                        "Incorrect response from " + url);
47    }
49
50    private HttpURLConnection testRequestHelper(String url, String method)
51                    throws Exception {
52        URL obj = new URL(url);
53        HttpURLConnection con = (HttpURLConnection) obj.openConnection();
54        // optional default is GET
55        con.setRequestMethod(method);
56        return con;
57    }
58
59    private String testBufferHelper(HttpURLConnection con) throws Exception {
60        BufferedReader in = new BufferedReader(
61                        new InputStreamReader(con.getInputStream()));
62        String inputLine;
63        StringBuffer response = new StringBuffer();
64        while ((inputLine = in.readLine()) != null) {
65            response.append(inputLine);
66        }
67        in.close();
68        return response.toString();
69    }
70
71}72