Learn how to build and test a simple web application using Maven and Open Liberty.
You will learn how to configure a simple web servlet application using Maven and the Liberty Maven plugin. When you compile and build the application code, Maven downloads and installs Open Liberty. If you run the application, Maven creates an Open Liberty server and runs the application on it. The application displays a simple web page with a link that, when clicked, calls the servlet to return a simple response of Hello! How are you today?.
One benefit of using Maven is that, once you have defined the details of the project and any dependencies it has, Maven automatically handles downloading and installing any and all of the dependencies.
Another benefit of using Maven is that it can run automated tests on the application after building it. You could, of course, test your application manually by starting a server and pointing a web browser at the application URL. Automated tests are a much better approach though because Maven can easily re-run the same tests each time it builds the application. If the tests don’t pass after you’ve made a change to the application, the build fails so you know that you need to fix your code.
You will create a Maven build definition file (pom.xml) for the web application project and use it to build the web application. You will then create a simple, automated test and configure Maven to run it after building the application.
The simple web application that we will build using Maven and Open Liberty is provided for you in the start directory so that you can focus on learning about Maven. The application uses the standard Maven directory structure. Using the standard directory structure saves you from customizing the pom.xml file later.
All the application source code, including the Open Liberty server configuration (server.xml), is in the src/main/liberty/config directory:
└── src
└── main
└── java
└── resources
└── webapp
└── liberty
└── config
Now you’re ready to install Maven (if you haven’t already). Download the binary zip or tar.gz file and then follow the installation instructions for your operating system to extract the ZIP file and add the bin directory (which contains the mvn command) to the PATH on your computer.
Test that Maven is installed by running the following command in a terminal:
mvn -v
If Maven is installed properly, you should see information about the Maven installation similar to this:
Apache Maven 3.5.0 (ff8f5e7444045639af65f6095c62210b5713f426; 2017-04-03T20:39:06+01:00) Maven home: /Applications/Maven/apache-maven-3.5.0 Java version: 1.8.0_131, vendor: Oracle Corporation Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_131.jdk/Contents/Home/jre Default locale: en_GB, platform encoding: UTF-8 OS name: "mac os x", version: "10.12.6", arch: "x86_64", family: "mac"
Before you can build the project, you define the Maven Project Object Model (POM) file, the pom.xml. Because the POM can look a bit daunting in full, we’ll create it a section at a time.
Create the pom.xml file in the current directory (at the same level as the src directory):
link:finish/pom.xml[role=include]The pom.xml file starts with a root <project /> element and <modelversion />, which is always set to 4.0.0. The <parent /> section of the POM specifies that Maven will use the Liberty Maven parent POM to build the project. This is the minimum you technically need for the POM to be valid. But it won’t do much with this project unless you give it a bit more information about your application.
We’ll now build up the rest of the pom.xml file, a section at a time in the space between the </parent> and </project> tags. Unless specified otherwise, add each of the sections of XML code beneath the previous one. The </project> tag must be the last thing in the pom.xml file.
A typical POM for a Liberty application contains the following sections:
-
Project coordinates: The identifiers for this application.
-
Repositories (
<repositories />): Defines the location of the Maven repository from which Maven will download Open Liberty packages during builds. This is a temporary section until Open Liberty’s first release and will not be required after that. -
Properties (
<properties />): Any properties for the project go here, including compilation details and any values that are referenced during compilation of the Java source code and generating the application. -
Dependencies (
<dependencies />): Any Java dependencies that are required for compiling, testing, and running the application are listed here. -
Build plugins (
<build />): Maven is modular and each of its capabilities is provided by a separate plugin. This is where you specify which Maven plugins should be used to build this project and any configuration information needed by those plugins.
We’ll start by adding the project coordinates of the sample application after the closing </parent> tag:
link:finish/pom.xml[role=include]The project coordinates describe the name and version of the application. The artifactId gives a name to the web application project, which is used to name the output files that are generated by the build (e.g. the WAR file) and the Open Liberty server that is created. You’ll notice that other fields in the pom.xml file use variables that are resolved by the artifactId field. This is so that you can update the name of the sample application, including files generated by Maven, in a single place in the pom.xml file. The value of the packaging field is war so that the project output artifact is a WAR file.
Add the details of the Maven repository from which Maven will download Open Liberty packages during a build (temporary until the first release of Open Liberty):
link:finish/pom.xml[role=include]Add the properties of the project:
link:finish/pom.xml[role=include]The first four properties in this section just define the encoding (UTF-8) and version of Java (Java 8) that Maven uses to compile the application source code.
The next four properties provide a single place to specify values that are used in multiple places throughout the application. For example, the testServerHttpPort value is used in both the server configuration (server.xml) file and will be used in the test class that you will add (EndpointIT.java) in the application itself. This means that you can easily change the port number that the server will run on without having to update the application code in multiple places.
The final two properties define the name and type of server package Maven uses to package the application with a Liberty server.
Add details of the dependency that the web application needs in order to compile:
link:finish/pom.xml[role=include]The HelloServlet.java class depends on javax.servlet-api to compile. Maven will download this dependency from the Maven Central repository using the groupId, artifactId, and version details that you provide here. The dependency is set to provided, which means that the API is in the server runtime and doesn’t need to be packaged by the application.
Configure the Maven plugins that build this project:
link:finish/pom.xml[role=include]The <build /> section gives details of the two plugins that Maven uses to build this project:
-
The Maven plugin for generating a WAR file as one of the output files.
-
The Liberty Maven plugin, which gives details of the name, version, and file type of Open Liberty runtime package which it will download from the public Maven repository.
In the liberty-maven-plugin plugin section, the <serverName /> field defines the name of the Liberty server that Maven creates. The <bootstrapProperties /> section provides the set of variables that the server.xml references. The <stripVersion /> field removes the version number from the name of the application (by default the version number of the application (1.0-SNAPSHOT) is appended to the application name). This means that the application URL remains the same even when the version number changes.
One of the benefits of building an application with Maven is that Maven can be configured to run a set of tests. You can write tests for the individual units of code outside of a running application server (unit tests), or you can write them to call the application server directly (integration tests). In this example you will create a simple integration test that checks that the web page opens and that the correct response is returned when the link is clicked.
When Maven runs the test, it starts a test server, runs the application, runs the test, and then stops the server.
Create the test class src/test/java/io/openliberty/guides/hello/it/EndpointIT.java:
link:finish/src/test/java/io/openliberty/guides/hello/it/EndpointIT.java[role=include]The test class name ends in IT to indicate that it contains an integration test. (Test classes with a name that ends in TEST are unit test classes.)
Configure Maven to run the integration test using the maven-failsafe-plugin by adding another <plugin /> section just before the closing </plugins> tag:
link:finish/pom.xml[role=include]The <systemPropertyVariables /> section defines some variables that the test class uses. The test code needs to know where to find the application that it is testing. While the port number and context root information can be hardcoded in the test class, it is better to specify it in a single place like the Maven pom.xml file because this information is also used by other files in the project. The <systemPropertyVariables /> section passes these details to the Java test program as a series of system properties, resolving the liberty.text.port and war.name variables.
The following lines in the Endpoint.java test class uses these system variables to build up the URL of the application:
link:finish/src/test/java/io/openliberty/guides/hello/it/EndpointIT.java[role=include]In the test class, after defining how to build the application URL, the @Test annotation indicates the start of the test method.
In the try block of the test method, an HTTP GET request to the URL of the application returns a status code. If the response to the request includes the string Hello! How are you today?, the test passes. If that string is not in the response, the test fails. The HTTP client then disconnects from the application.
link:finish/src/test/java/io/openliberty/guides/hello/it/EndpointIT.java[role=include]In the import statements of this test class, you’ll notice that the test has some new dependencies. Before the test can be compiled by Maven, you need to update the pom.xml to include these dependencies.
Add the following two <dependency /> elements after the existing dependency in the <dependencies /> section of the pom.xml:
link:finish/pom.xml[role=include]The Apache commons-httpclient and junit dependencies are needed to compile and run the integration test EndpointIT class. The scope for each of the dependencies is set to test because the libraries are needed only during the Maven build and do not needed to be packaged with the application.
Now, during the Maven build, Maven creates the WAR file that contains the web application and then runs any integration test classes (classes with names that end in IT) that it finds.
The directory structure of the project should now look like this:
└── src
├── main
│ └── java
│ └── resources
│ └── webapp
│ └── liberty
│ └── config
└── test
└── java
You can now run the command mvn install to rebuild the application, including the test you’ve added, run the test, and see that the test passes. The Maven build takes a little longer than before the test existed, but expect to see the following information in the output:
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running io.openliberty.guides.hello.it.EndpointIT
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.255 sec - in io.openliberty.guides.hello.it.EndpointIT
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0To see whether the test detects a failure, change the response string in the servlet src/main/java/io/openliberty/guides/hello/HelloServlet.java so that it doesn’t match the string that the test is looking for. Then re-run the Maven build and check that the test fails.
The complete pom.xml should now look like this:
link:finish/pom.xml[role=include]You built and tested a web application project with an Open Liberty server using Maven.
You can quickly create this project structure by using the Liberty App Accelerator accelerator or the Maven liberty-archetype-webapp archetype.