Building a web application with Gradle

duration 15 minutes

Prerequisites:

Learn how to build and test a simple web application using Gradle and Open Liberty.

What you’ll learn

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.

Learn more about Gradle on the official Gradle website.

Getting started

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

git clone https://github.com/openliberty/guide-gradle-intro.git
cd guide-gradle-intro

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

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

Creating 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-INF

Testing Gradle

If you do not have Gradle installed, make sure that the JAVA_HOME environment variable is set, or that the Java application can run. Running the Gradle Wrapper automatically installs Gradle. To learn more about the Gradle Wrapper, see the Gradle Wrapper documentation.

Ensure that you are in the start directory. Test that Gradle is installed properly by running the following command:

gradlew.bat -v
./gradlew -v

You should see information about the Gradle installation similar to this example:

------------------------------------------------------------
Gradle 5.6.3
------------------------------------------------------------

Build time:   2019-10-18 00:28:36 UTC
Revision:     bd168bbf5d152c479186a897f2cea494b7875d13

Kotlin:       1.3.41
Groovy:       2.5.4
Ant:          Apache Ant(TM) version 1.9.14 compiled on March 12 2019
JVM:          1.8.0_144 (Oracle Corporation 25.144-b01)
OS:           Mac OS X 10.15.1 x86_64

You can also view the default tasks available by running the following command:

gradlew.bat tasks
./gradlew tasks

Configure your project

settings.gradle

1rootProject.name = 'GradleSample'

build.gradle

  1// tag::war[]
  2apply plugin: 'war'
  3// end::war[]
  4// tag::liberty[]
  5apply plugin: 'liberty'
  6// end::liberty[]
  7
  8sourceCompatibility = 1.8
  9targetCompatibility = 1.8
 10tasks.withType(JavaCompile) {
 11    options.encoding = 'UTF-8'
 12}
 13
 14// configure liberty-gradle-plugin
 15// tag::buildscript[]
 16buildscript {
 17    repositories {
 18        // tag::buildmaven[]
 19        mavenCentral()
 20        // end::buildmaven[]
 21    }
 22    dependencies {
 23        // tag::liberty-dependency[]
 24        classpath 'io.openliberty.tools:liberty-gradle-plugin:3.0'
 25        // end::liberty-dependency[]
 26    }
 27}
 28// end::buildscript[]
 29
 30// tag::repositories[]
 31repositories {
 32    // tag::maven[]
 33    mavenCentral()
 34    // end::maven[]
 35}
 36// end::repositories[]
 37
 38// tag::dependencies[]
 39dependencies {
 40    // provided dependencies
 41    // tag::providedcompile[]
 42    providedCompile 'jakarta.platform:jakarta.jakartaee-api:8.0.0'
 43    providedCompile 'org.eclipse.microprofile:microprofile:3.3'
 44    // end::providedcompile[]
 45
 46    // test dependencies
 47    // tag::testimplementation[]
 48    // tag::junit[]
 49    testImplementation 'org.junit.jupiter:junit-jupiter:5.6.2'
 50    // end::junit[]
 51    // tag::commons[]
 52    testImplementation 'commons-httpclient:commons-httpclient:3.1'
 53    // end::commons[]
 54    // end::testimplementation[]
 55}
 56// end::dependencies[]
 57
 58// tag::ext[]
 59ext  {
 60    liberty.server.var.'default.http.port' = '9080'
 61    liberty.server.var.'default.https.port' = '9443'
 62    liberty.server.var.'app.context.root' = project.name
 63}
 64// end::ext[]
 65
 66// tag::openbrowser[]
 67task openBrowser {
 68    description = 'Open browser to the running application'
 69    doLast {
 70        String port = liberty.server.var.'default.http.port'
 71        String context = liberty.server.var.'app.context.root'
 72        String URL = "http://localhost:" + port + "/" + context + "/" + "servlet"
 73        java.awt.Desktop.desktop.browse URL.toURI()
 74        java.awt.Desktop.desktop.browse file("$buildDir/reports/tests/test/index.html").toURI()
 75    }
 76}
 77// end::openbrowser[]
 78
 79// tag::tests[]
 80test {
 81    // tag::junitplatform[]
 82    useJUnitPlatform()
 83    // end::junitplatform[]
 84    testLogging {
 85        events 'passed', 'skipped', 'failed', 'standardOut'
 86        exceptionFormat 'full'
 87    }
 88    // tag::systemproperty[]
 89    // tag::httpport[]
 90    systemProperty 'http.port', liberty.server.var.'default.http.port'
 91    // end::httpport[]
 92    // tag::contextroot[]
 93    systemProperty 'context.root',  liberty.server.var.'app.context.root'
 94    // end::contextroot[]
 95    // end::systemproperty[]
 96}
 97// end::tests[]
 98
 99// tag::depends[]
100test.dependsOn 'libertyStart'
101test.finalizedBy(openBrowser)
102clean.dependsOn 'libertyStop'
103// end::depends[]

The 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 the Gradle settings file.
settings.gradle

This settings.gradle file isn’t required for a single-module Gradle project. Without this definition, by default, the project name is set as the name of the folder in which it is contained (start for this example).

Let’s go through 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.

ext

Gradle extra properties extension for project level properties.

test

Unit test and integration test configuration.

Create the build file.
build.gradle

The first section of code 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 compatibility and encoding settings are for Java.

The buildscript section defines plug-in versions to use in the build and where to find them. This guide uses the liberty plug-in, which is available from the Maven Central Repository.

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.

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. The testImplementation dependencies are needed to compile and run tests.

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 ports and the context-root.

Running the application

Start Open Liberty in development mode, which starts the Open Liberty server and listens for file changes:

./gradlew libertyDev

After you see the following message, your application server in development mode is ready.

Press the Enter key to run tests on demand.

The development mode holds your command prompt to listen for file changes. You need to open another command prompt to continue, or simply open the project in your editor.

Navigate your browser to the http://localhost:9080/GradleSample/servlet URL to access the application. The servlet returns a simple response of Hello! Is Gradle working for you?.

Testing the web application

EndpointIT.java

 1// tag::copyright[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2020 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - initial API and implementation
11 *******************************************************************************/
12// end::copyright[]
13package io.openliberty.guides.hello.it;
14// tag::import[]
15import static org.junit.jupiter.api.Assertions.*;
16import org.junit.jupiter.api.Order;
17import org.junit.jupiter.api.BeforeAll;
18import org.junit.jupiter.api.Test;
19import org.apache.commons.httpclient.HttpClient;
20import org.apache.commons.httpclient.HttpStatus;
21import org.apache.commons.httpclient.methods.GetMethod;
22// end::import[]
23// tag::endpointit[]
24public class EndpointIT {
25    private static String URL;
26
27    @BeforeAll
28    // tag::init[]
29    public static void init() {
30        String port = System.getProperty("http.port");
31        String context = System.getProperty("context.root");
32        URL = "http://localhost:" + port + "/" + context + "/" + "servlet";
33        System.out.println("URL: " + URL);
34    }
35    // end::init[]
36
37    // tag::test[]
38    @Test
39    // end::test[]
40    public void testServlet() throws Exception {
41        HttpClient httpClient = new HttpClient();
42        GetMethod httpGetMethod = new GetMethod(URL);
43        // tag::try[]
44        try {
45            int actualStatusCode = httpClient.executeMethod(httpGetMethod);
46            int expectedStatusCode = HttpStatus.SC_OK;
47            assertEquals(expectedStatusCode, actualStatusCode, "HTTP GET failed");
48            String response = httpGetMethod.getResponseBodyAsString(1000);
49            assertTrue(response.contains("Hello! Is Gradle working for you?"),
50                    "Unexpected response body");
51        } finally {
52            httpGetMethod.releaseConnection();
53        }
54        // end::try[]
55    }
56}
57//end::endpointit[]

build.gradle

  1// tag::war[]
  2apply plugin: 'war'
  3// end::war[]
  4// tag::liberty[]
  5apply plugin: 'liberty'
  6// end::liberty[]
  7
  8sourceCompatibility = 1.8
  9targetCompatibility = 1.8
 10tasks.withType(JavaCompile) {
 11    options.encoding = 'UTF-8'
 12}
 13
 14// configure liberty-gradle-plugin
 15// tag::buildscript[]
 16buildscript {
 17    repositories {
 18        // tag::buildmaven[]
 19        mavenCentral()
 20        // end::buildmaven[]
 21    }
 22    dependencies {
 23        // tag::liberty-dependency[]
 24        classpath 'io.openliberty.tools:liberty-gradle-plugin:3.0'
 25        // end::liberty-dependency[]
 26    }
 27}
 28// end::buildscript[]
 29
 30// tag::repositories[]
 31repositories {
 32    // tag::maven[]
 33    mavenCentral()
 34    // end::maven[]
 35}
 36// end::repositories[]
 37
 38// tag::dependencies[]
 39dependencies {
 40    // provided dependencies
 41    // tag::providedcompile[]
 42    providedCompile 'jakarta.platform:jakarta.jakartaee-api:8.0.0'
 43    providedCompile 'org.eclipse.microprofile:microprofile:3.3'
 44    // end::providedcompile[]
 45
 46    // test dependencies
 47    // tag::testimplementation[]
 48    // tag::junit[]
 49    testImplementation 'org.junit.jupiter:junit-jupiter:5.6.2'
 50    // end::junit[]
 51    // tag::commons[]
 52    testImplementation 'commons-httpclient:commons-httpclient:3.1'
 53    // end::commons[]
 54    // end::testimplementation[]
 55}
 56// end::dependencies[]
 57
 58// tag::ext[]
 59ext  {
 60    liberty.server.var.'default.http.port' = '9080'
 61    liberty.server.var.'default.https.port' = '9443'
 62    liberty.server.var.'app.context.root' = project.name
 63}
 64// end::ext[]
 65
 66// tag::openbrowser[]
 67task openBrowser {
 68    description = 'Open browser to the running application'
 69    doLast {
 70        String port = liberty.server.var.'default.http.port'
 71        String context = liberty.server.var.'app.context.root'
 72        String URL = "http://localhost:" + port + "/" + context + "/" + "servlet"
 73        java.awt.Desktop.desktop.browse URL.toURI()
 74        java.awt.Desktop.desktop.browse file("$buildDir/reports/tests/test/index.html").toURI()
 75    }
 76}
 77// end::openbrowser[]
 78
 79// tag::tests[]
 80test {
 81    // tag::junitplatform[]
 82    useJUnitPlatform()
 83    // end::junitplatform[]
 84    testLogging {
 85        events 'passed', 'skipped', 'failed', 'standardOut'
 86        exceptionFormat 'full'
 87    }
 88    // tag::systemproperty[]
 89    // tag::httpport[]
 90    systemProperty 'http.port', liberty.server.var.'default.http.port'
 91    // end::httpport[]
 92    // tag::contextroot[]
 93    systemProperty 'context.root',  liberty.server.var.'app.context.root'
 94    // end::contextroot[]
 95    // end::systemproperty[]
 96}
 97// end::tests[]
 98
 99// tag::depends[]
100test.dependsOn 'libertyStart'
101test.finalizedBy(openBrowser)
102clean.dependsOn 'libertyStop'
103// end::depends[]

HelloServlet.java

 1// tag::copyright[]
 2/*******************************************************************************
 3 * Copyright (c) 2017, 2020 IBM Corporation and others.
 4 * All rights reserved. This program and the accompanying materials
 5 * are made available under the terms of the Eclipse Public License v1.0
 6 * which accompanies this distribution, and is available at
 7 * http://www.eclipse.org/legal/epl-v10.html
 8 *
 9 * Contributors:
10 *     IBM Corporation - initial API and implementation
11 *******************************************************************************/
12 // end::copyright[]
13package io.openliberty.guides.hello;
14
15import java.io.IOException;
16
17import javax.servlet.ServletException;
18import javax.servlet.annotation.WebServlet;
19import javax.servlet.http.HttpServlet;
20import javax.servlet.http.HttpServletRequest;
21import javax.servlet.http.HttpServletResponse;
22
23@WebServlet(urlPatterns="/servlet")
24public class HelloServlet extends HttpServlet {
25    private static final long serialVersionUID = 1L;
26
27    protected void doGet(HttpServletRequest request, HttpServletResponse response)
28        throws ServletException, IOException {
29        // tag::responsestring[]
30        response.getWriter().append("Hello! Is Gradle working for you?\n");
31        // end::responsestring[]
32    }
33
34    protected void doPost(HttpServletRequest request, HttpServletResponse response)
35        throws ServletException, IOException {
36        doGet(request, response);
37    }
38}

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.

Create the EndpointIT test class.
src/test/java/io/openliberty/guides/hello/it/EndpointIT.java

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.

The test section in your build file is added by the Java plug-in, and the useJUnitPlatform() line configures Gradle to add JUnit 5 support.

The systemProperty 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 systemProperty lines passes these details to the test JVMs as a series of system properties, resolving the http.port and context.root variables.

The init() method in the EndpointIT.java test class uses these system variables to build the URL of the application.

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.

In the import statements of this test class, you’ll notice that the test has some new dependencies. Earlier you added some testImplementation dependencies. The Apache commons-httpclient and org.junit.jupiter dependencies are needed to compile and run the integration test EndpointIT class.

The scope for each of the dependencies is set to testImplementation because the libraries are needed only during the Gradle test phase and do not need to be packaged with the application.

Now, the created WAR file contains the web application, and development mode can run any integration test classes that it finds. Integration test classes are classes with names that end in IT.

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
         └── java

A few more pieces

We show a few more Gradle tricks in this example with the openBrowser task. This task displays your application and the test report in the default browser.

The final Gradle magic to add is the task dependency directives. The dependency directives organizes task execution. In this case, the test task is set to run after the server is started, and the openBrowser task is executed after the test task is finalized.

Running the tests

Since you started Open Liberty in development mode at the start of the guide, press the enter/return key to run the tests. You will see that the browser opened up the test summary page, which ran one successful test.

To see whether the test detects a failure, change the response string in the src/main/java/io/openliberty/guides/hello/HelloServlet.java file so that it doesn’t match the string that the test is looking for. Then rerun the Gradle test to automatically restart and retest your application to check to see if the test fails.

When you are done checking out the service, exit development mode by pressing CTRL+C in the command-line session where you ran the server, or by typing q and then pressing the enter/return key.

Great work! You’re done!

You built and tested a web application project running on an Open Liberty server using Gradle.

Guide Attribution

Building a web application with Gradle by Open Liberty is licensed under CC BY-ND 4.0

Copied to clipboard
Copy code block
Copy file contents

Prerequisites:

Nice work! Where to next?

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star