|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Learn how to build and test a simple web application using Gradle and Open Liberty.
You will learn how to build and test a simple web servlet application using the Gradle war plug-in and the Liberty Gradle plug-in.
The war plug-in compiles and builds the application code.
The liberty Gradle plug-in installs the Open Liberty runtime, creates a server, and installs the application to run and test.
The application displays a simple web page with a link. When you click that link, the application calls the servlet to return a simple response of Hello! Is Gradle working for you?.
One benefit of using a build tool like Gradle is that after you define the details of the project and any dependencies it has, Gradle automatically downloads and installs the dependencies.
Another benefit of using Gradle is that it can run repeatable, automated tests on the application. 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 because you can easily rerun the same tests each time the application is built. If the tests don’t pass after you’ve made a change to the application, the build fails, and you know that you introduced a regression that requires a fix to your code.
Using this guide, you will create a Gradle build definition file (build.gradle) for the web application project, and use it to build the application.
You will then create a simple, automated test, and configure Gradle to run it after building the application.
The web application that you will build using Gradle and Open Liberty is provided for you in the start directory so that you can focus on learning about Gradle.
The application uses the standard Gradle directory structure.
Using this directory structure saves you from customizing the build.gradle file later.
All the application source code, including the Open Liberty server configuration (server.xml), is in the start/src directory:
└── src
└── main
└── java
└── liberty
└── config
└── webapp
└── WEB-INFIf you don’t have Gradle Version 3 or higher installed, follow the instructions on the Gradle installation page for your operating system.
Configure the environment variables so that you can run the gradle command.
Test that Gradle is installed properly by running the following command in a command line:
gradle -vYou should see information about the Gradle installation similar to this example:
------------------------------------------------------------
Gradle 4.1
------------------------------------------------------------
Build time: 2017-08-07 14:38:48 UTC
Revision: 941559e020f6c357ebb08d5c67acdb858a3defc2
Groovy: 2.4.11
Ant: Apache Ant(TM) Version 1.9.6 compiled on June 29 2015
JVM: 1.8.0_144 (Oracle Corporation 25.144-b01)
OS: Mac OS X 10.12.6 x86_64You can also view the default tasks available by running the following command:
gradle tasksThe project configuration is defined in the Gradle settings and build files. You will create these project configurations one section at a time.
Gradle settings are used to instantiate and configure the project.
This sample uses the settings.gradle to name the project GradleSample.
Create ./settings.gradle:
link:finish/settings.gradle[role=include]This settings.gradle file isn’t required for a single-module Gradle project. Without this definition, by default, the project name is set the name of the folder in which it is contained (start for this example).
Create a build.gradle file in the start folder with the settings.gradle file and the src folder.
Let’s go through the parts of the build.gradle file so that you understand each part.
Configuration |
Purpose |
Plug-ins used |
The first part of the build file specifies the plug-ins required to build the project and some basic project configuration. |
buildscript |
Where to find plug-ins for download. |
repositories |
Where to find dependencies for download. |
dependencies |
Java dependencies that are required for compiling, testing, and running the application are included here. You can also define your Liberty runtime dependency in this section. |
ext |
Gradle extra properties extension for project level properties. |
liberty |
Configuration for the Liberty plug-in. |
war |
War plug-in configuration. |
test |
Unit test and integration test configuration. |
You will build the build.gradle file piece by piece.
Add this first section to your build file:
link:finish/build.gradle[role=include]This code snippet defines the war and liberty plug-ins that you want to use.
The war plug-in contains all the tasks to compile Java files, build the WAR file structure, and assemble the archive.
The liberty plug-in contains the tasks used to install the Liberty runtime and create and manage servers.
The group, version, and description define this sample project.
The compatibility and encoding settings are for Java.
Add the buildscript section to your build file:
link:finish/build.gradle[role=include]The buildscript section defines plug-in versions to use in the build and where to find them.
This guide uses version 2.1 of the liberty plug-in, which is available from the Maven Central Repository.
Add the repositories section to your build file:
link:finish/build.gradle[role=include]The repositories section defines where to find the dependencies that you are using in the build.
For this build, everything you need is in Maven Central.
Add the dependencies section to your build file:
link:finish/build.gradle[role=include]The dependencies section defines what is needed to compile and test the code.
This section also defines how to run the application.
The providedCompile dependencies are APIs that are needed to compile the application, but they do not need to be packaged with the application because Open Liberty provides their implementation at run time.
For example, the HelloServlet.java class depends on javax.servlet-api to compile, but since Open Liberty provides that API, it does not need to be packaged with your application.
The testCompile dependencies are needed to compile and run tests.
The liberty plug-in provides the libertyRuntime dependency definition that specifies the version of the Liberty runtime you want to use.
This project uses Open Liberty 17.0.0.4 or later.
Add the ext section to your build file:
link:finish/build.gradle[role=include]The Gradle extra properties extension allows you to add properties to a Gradle project. If you use a value more than once in your build file, you can simplify updates by defining it as a variable here and referring to the variable later in the build file. This project defines variables for the application name, ports, and the context-root.
Add the liberty section to your build file:
link:finish/build.gradle[role=include]The liberty extension configures the Liberty server, which includes the following settings:
Server attribute |
Purpose |
name |
The server name. |
configFile |
The server configuration file. |
bootstrapProperties |
Bootstrap properties that are written to the server’s |
packageLiberty |
Specifies to only package the |
So what’s not configured for the liberty plug-in?
By default, when the liberty and the war plug-ins are applied, the default WAR file is installed to the apps folder.
Omitting this definition is the same as including the following line:
apps = [war]You can also install applications to the dropins folder.
Also, by default, a loose application is installed to your Liberty server.
Instead of installing a WAR archive, an XML file (GradleSample.war.xml) is installed that describes the location of the application classes, resources, and libraries.
This is useful for development because you only need to recompile your code, rather than repackaging and redeploy your entire WAR file to see application updates live on the server.
If you want to turn off loose application support, add the following line:
looseApplication = falseAdd the war section to your build file:
link:finish/build.gradle[role=include]This configuration names the WAR file GradleSample.war without a version in the name.
One of the benefits of building an application with a build system like Gradle is that it can be configured to run a set of automated tests.
The war plug-in extends the Java plug-in, which provides test tasks.
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 that runs on the server (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.
The Gradle project is configured to start the server with the application installed before running the test. After running the test, the server is stopped.
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.
The integration tests are put in the it folder by convention.
Add the test section to your build file:
link:finish/build.gradle[role=include]This configures Gradle to run the integration tests in the */it/** folder.
The systemProperties configuration defines some variables needed by the test class.
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 Gradle build.gradle file, in case they need to change.
The systemProperties 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 EndpointIT.java test class uses these system variables to build 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! Is Gradle working for you?, 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.
Earlier you added some testCompile dependencies.
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 testCompile because the libraries are needed only during the Gradle test phase and do not need to be packaged with the application.
Now, during the build, Gradle installs the application and then runs any integration test classes in the it folder.
The directory structure of the project in the start folder should now look like this example:
└── build.gradle
├── settings.gradle
└── src
├── main
│ ├── java
│ ├── liberty
│ │ └── config
│ └── webapp
│ └── WEB_INF
└── test
└── javaWe show a few more Gradle tricks in this example with the openBrowser and the openTestReport tasks.
These tasks display your application and the test report in the default browser.
Add these browser tasks to your build file:
link:finish/build.gradle[role=include]The final Gradle magic to add is the task dependency directives.
These statements associate the war and java tasks to the liberty tasks to get proper task ordering.
Add these statements to your build file:
link:finish/build.gradle[role=include]You can now run the build command to build and test the application.
From the folder containing your build.gradle file, run the command:
gradle build -i
The -i option provides additional information on the command line.
The build takes a little longer than before the test existed, but expect to see the browser opened with the test summary displayed.
To 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 rerun the Gradle integration tests with a gradle integrationTest -i command, and check that the test fails.
The complete build.gradle file should now look like the following:
link:finish/build.gradle[role=include]You built and tested a web application project with an Open Liberty server using Gradle.
You can quickly create this project structure by using the Liberty App Accelerator and choose to create a Gradle project.