{"id":18429044,"url":"https://github.com/openliberty/guide-gradle-intro","last_synced_at":"2025-04-07T17:32:23.689Z","repository":{"id":27690108,"uuid":"114931020","full_name":"OpenLiberty/guide-gradle-intro","owner":"OpenLiberty","description":"An introductory guide on how to build and test a simple web application using Gradle and Open Liberty: https://openliberty.io/guides/gradle-intro.html","archived":false,"fork":false,"pushed_at":"2025-03-05T20:06:01.000Z","size":436,"stargazers_count":3,"open_issues_count":3,"forks_count":17,"subscribers_count":5,"default_branch":"prod","last_synced_at":"2025-03-22T21:51:07.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenLiberty.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-20T21:04:19.000Z","updated_at":"2025-03-05T20:06:05.000Z","dependencies_parsed_at":"2023-10-14T22:20:43.991Z","dependency_job_id":"4313743a-c60a-4c0d-9890-9c9736af84f2","html_url":"https://github.com/OpenLiberty/guide-gradle-intro","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-gradle-intro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-gradle-intro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-gradle-intro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fguide-gradle-intro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenLiberty","download_url":"https://codeload.github.com/OpenLiberty/guide-gradle-intro/tar.gz/refs/heads/prod","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247697893,"owners_count":20981270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T05:15:36.352Z","updated_at":"2025-04-07T17:32:23.682Z","avatar_url":"https://github.com/OpenLiberty.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"// Copyright (c) 2017, 2025 IBM Corporation and others.\n// Licensed under Creative Commons Attribution-NoDerivatives\n// 4.0 International (CC BY-ND 4.0)\n//   https://creativecommons.org/licenses/by-nd/4.0/\n//\n// Contributors:\n//     IBM Corporation\n//\n:projectid: gradle-intro\n:page-layout: guide-multipane\n:page-duration: 15 minutes\n:page-description: Learn how to build and test a web application using a build configuration script, the Gradle War plug-in and Open Liberty Gradle plug-in.\n:page-releasedate: 2017-12-27\n:page-guide-category: basic\n:page-essential: true\n:page-essential-order: 2\n:page-permalink: /guides/{projectid}\n:page-related-guides: ['maven-intro']\n:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod\n:page-seo-title: Building a Java web application using Gradle\n:page-seo-description: A getting started tutorial with examples of how to build and test a Java web application with a Gradle build configuration script using the Gradle War plug-in and Open Liberty Gradle plug-in.\n:source-highlighter: prettify\n:guide-author: Open Liberty\n= Building a web application with Gradle\n\n[.hidden]\nNOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].\n\nLearn how to build and test a simple web application using Gradle and Open Liberty.\n\n== What you'll learn\n\nYou will learn how to build and test a simple web servlet application using the Gradle `war` \nplug-in and the Liberty Gradle plug-in. The `war` plug-in compiles and builds the application \ncode. The https://github.com/WASdev/ci.gradle/blob/main/README.md[`liberty` Gradle plug-in^] \ninstalls the Open Liberty runtime, creates an instance, and installs the application to run and test.\nThe application displays a simple web page with a link. When you click that link, the application \ncalls the servlet to return a simple response of `Hello! Is Gradle working for you?`.\n\nOne benefit of using a build tool like Gradle is that you can define the details of the project and any dependencies it has, and Gradle automatically downloads and installs the dependencies.\nAnother benefit of using Gradle is that it can run repeatable, automated tests on the application. \nYou can, of course, test your application manually by starting a Liberty instance and pointing a web browser at the application URL. \nHowever, automated tests are a much better approach because you can easily rerun the same tests each time the application is built.\nIf the tests don't pass after you change the application, the build fails, and you know that you introduced a regression that requires a fix to your code.\n\nChoosing a build tool often comes down to personal or organizational preference, but you might choose to use Gradle for several reasons. \nGradle defines its builds by using https://docs.gradle.org/current/userguide/writing_build_scripts.html[Groovy build scripts^], which gives you a lot of control and customization in your builds. \nGradle also uses a build cache that rebuilds only the parts of your application that changed, which saves build time in larger projects.\nSo Gradle can be a good choice in larger, more complex projects.\n\nUsing this guide, you will create a Gradle build definition file (`build.gradle`) for the \nweb application project, and use it to build the application. You will then create a simple, \nautomated test, and configure Gradle to run it after building the application.\n\nLearn more about Gradle on the https://docs.gradle.org/current/userguide/userguide.html[official Gradle website^].\n\n[role='command']\ninclude::{common-includes}/gitclone.adoc[]\n\n== Creating the application\n\nThe web application that you will build using Gradle and Open Liberty is provided for you \nin the `start` directory so that you can focus on learning about Gradle. The application uses \nthe standard Gradle directory structure. Using this directory structure saves you from \ncustomizing the `build.gradle` file later.\n\nAll the application source code, including the Open Liberty `server.xml` configuration file, \nis in the `start/src` directory:\n\n[source, role=\"no_copy\"]\n----\n\n└── src\n    └── main\n        └── java\n        └── liberty\n            └── config\n        └── webapp\n            └── WEB-INF\n----\n\n== Testing Gradle\n\nIf 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 https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle Wrapper documentation^].\n\nRun the following commands to navigate to the `start` directory and verify that Gradle was installed correctly:\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section]\n--\n[role='command']\n----\ncd start\ngradlew.bat -v\n----\n--\n\n[.tab_content.mac_section.linux_section]\n--\n[role='command']\n----\ncd start\n./gradlew -v\n----\n--\n\nYou should see information about the Gradle installation similar to this example:\n\n[source, role=\"no_copy\"]\n----\n------------------------------------------------------------\nGradle 8.6\n------------------------------------------------------------\n\nBuild time:   2024-02-02 16:47:16 UTC\nRevision:     d55c486870a0dc6f6278f53d21381396d0741c6e\n\nKotlin:       1.9.20\nGroovy:       3.0.17\nAnt:          Apache Ant(TM) version 1.10.13 compiled on January 4 2023\nJVM:          17.0.12 (Eclipse OpenJ9 openj9-0.46.0)\nOS:           Mac OS X 15.2 aarch64\n\n----\n\n\n== Configure your project\n\n//file 0\nsettings.gradle\n[source, gradle, linenums, role='code_column']\n----\ninclude::finish/settings.gradle[]\n----\n\n//file 1\nbuild.gradle\n[source, gradle, linenums, role='code_column']\n----\ninclude::finish/build.gradle[]\n----\n\nThe project configuration is defined in the Gradle settings and build files.\nYou will create these project configurations one section at a time. \n\nGradle https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html[settings^] \nare used to instantiate and configure the project. This sample uses the [hotspot file=0]`settings.gradle` \nto name the project `GradleSample`.\n\n[role=\"code_command hotspot file=0\", subs=\"quotes\"] \n---- \n#Create the Gradle settings file in the `start` directory.#\n`settings.gradle`\n---- \n\nThis [hotspot file=0]`settings.gradle` file isn't required for a single-module Gradle project. \nWithout this definition, by default, the project name is set as the name of the folder in \nwhich it is contained (`start` for this example).\n\nLet's go through the [hotspot file=1]`build.gradle` \nfile so that you understand each part.\n\n[cols=\"40, 100\"]\n|===\n| *Configuration*       |   *Purpose*\n| Plug-ins used         |   The first part of the build file specifies the plug-ins required to \n                            build the project and some basic project configuration.\n| buildscript           |   Where to find plug-ins for download.\n| repositories          |   Where to find dependencies for download.\n| dependencies          |   Java dependencies that are required for compiling, testing, \n                            and running the application are included here.\n| ext                   |   Gradle extra properties extension for project level properties.\n| test                  |   Unit test and integration test configuration.\n|===\n\n\n[role=\"code_command hotspot file=1\", subs=\"quotes\"] \n---- \n#Create the build file in the `start` directory.#\n`build.gradle`\n---- \n\nThe first section of code defines the [hotspot=war file=1]`war` and [hotspot=liberty file=1]`liberty` plug-ins \nthat you want to use. The [hotspot=war file=1]`war` plug-in contains all the tasks to compile \nJava files, build the WAR file structure, and assemble the archive. The [hotspot=liberty file=1]`liberty` \nplug-in contains the tasks used to install the Liberty runtime and create and manage \nthe associated Liberty instances. The compatibility and encoding settings are for Java.\n\nThe [hotspot=buildscript file=1]`buildscript` section defines plug-in versions to use in the \nbuild and where to find them. This guide uses the [hotspot=liberty-dependency file=1]`liberty` plug-in, \nwhich is available from the [hotspot=buildmaven file=1]`Maven Central Repository`.\n\nThe [hotspot=repositories file=1]`repositories` section defines where to find the dependencies \nthat you are using in the build. For this build, everything you need is in [hotspot=maven file=1]`Maven Central`.\n\nThe [hotspot=dependencies file=1]`dependencies` section defines what is needed to compile and \ntest the code. This section also defines how to run the application. The \n[hotspot=providedcompile file=1]`providedCompile` dependencies are APIs that are needed to compile the \napplication, but they do not need to be packaged with the application because Open Liberty \nprovides their implementation at run time. The [hotspot=testimplementation file=1]`testImplementation` dependencies \nare needed to compile and run tests.\n\nThe Gradle [hotspot=ext file=1]`extra properties` extension allows you to add properties to a Gradle project.\nIf you use a value more than once in your build file, you can simplify updates by defining \nit as a variable here and referring to the variable later in the build file.\nThis project defines variables for the application ports and the context-root.\n\nYou can view the default and Liberty tasks available by running the following command:\n\ninclude::{common-includes}/os-tabs.adoc[]\n\n[.tab_content.windows_section]\n--\n[source, role=\"command\"]\n----\ngradlew.bat tasks\n----\n--\n\n\n[.tab_content.mac_section.linux_section]\n--\n[source, role=\"command\"]\n----\n./gradlew tasks\n----\n--\n\n== Running the application\n\nStart Open Liberty in https://openliberty.io/docs/latest/development-mode.html[dev mode^], which starts the Open Liberty instance and listens for file changes:\n\n[role='command']\n----\n./gradlew libertyDev\n----\n\nAfter you see the following message, your Liberty instance is ready in dev mode.\n\n[role=\"no_copy\"]\n----\n**********************************************\n*    Liberty is running in dev mode.\n----\n\nThe dev mode holds your command prompt to listen for file changes.\nYou need to open another command prompt to continue, or simply open the project in your editor.\n\nNavigate your browser to the http://localhost:9080/GradleSample/servlet[^] URL to access the application. \nThe servlet returns a simple response of `Hello! Is Gradle working for you?`.\n\n== Testing the web application\n\n//file 0\nEndpointIT.java \n[source, java, linenums, role='code_column hide_tags=copyright']\n----\ninclude::finish/src/test/java/io/openliberty/guides/hello/it/EndpointIT.java[]\n----\n\n//file 1\nbuild.gradle   \n[source, groovy, linenums, role='code_column']\n----\ninclude::finish/build.gradle[]\n----\n\n//file 2\nHelloServlet.java\n[source, Java, linenums, role='code_column hide_tags=copyright']\n----\ninclude::finish/src/main/java/io/openliberty/guides/hello/HelloServlet.java[]\n----\n\nOne of the benefits of building an application with a build system like Gradle is that \nit can be configured to run a set of automated tests. The [hotspot=war file=1]`war` \nplug-in extends the https://docs.gradle.org/current/userguide/java_plugin.html[Java plug-in^], \nwhich provides test tasks. You can write tests for the individual units of code outside \nof a running Liberty instance (unit tests), or you can write them to call the application \nthat runs on the Liberty instance (integration tests). In this example, you will create a simple \nintegration test that checks that the web page opens and that the correct response is \nreturned when the link is clicked.\n\n[role=\"code_command hotspot file=0\", subs=\"quotes\"] \n---- \n#Create the `EndpointIT` test class.#\n`src/test/java/io/openliberty/guides/hello/it/EndpointIT.java`\n---- \n\nThe test class name ends in `IT` to indicate that it contains an integration test.\nThe integration tests are put in the `it` folder by convention.\n\nThe [hotspot=tests file=1]`test` section in your build file is added by the Java plug-in, and the \n[hotspot=junitplatform file=1]`useJUnitPlatform()` line configures Gradle to add JUnit 5 support.\n\nThe [hotspot=systemproperty file=1]`systemProperty` configuration  defines some variables needed by \nthe test class. While the port number and context-root information can be \nhardcoded in the test class, it is better to specify it in a single place like the Gradle \n[hotspot file=1]`build.gradle` file, in case they need to change.\nThe [hotspot=systemproperty file=1]`systemProperty` lines passes these details to the test JVMs \nas a series of system properties, resolving the [hotspot=httpport file=1]`http.port` \nand [hotspot=contextroot file=1]`context.root` variables.\n\nThe [hotspot=init file=0]`init()` method in the `EndpointIT.java` test class uses these \nsystem variables to build the URL of the application.\n\nIn the test class, after defining how to build the application URL, the [hotspot=test file=0]`@Test` \nannotation indicates the start of the test method.\n\nIn the [hotspot=try file=0]`try` block of the test method, an HTTP `GET` request to the \nURL of the application returns a status code. If the response to the request includes the \nstring `Hello! Is Gradle working for you?`, the test passes. If that string is not in the \nresponse, the test fails. The HTTP client then disconnects from the application.\n\nIn the [hotspot=import file=0]`import` statements of this test class, you'll notice that the \ntest has some new dependencies. Earlier you added some [hotspot=testimplementation file=1]`testImplementation` \ndependencies. The Apache [hotspot=commons file=1]`httpclient` and [hotspot=junit file=1]`org.junit` \ndependencies are needed to compile and run the integration test [hotspot=endpointit file=0]`EndpointIT` \nclass.\n\nThe scope for each of the dependencies is set to [hotspot=testimplementation file=1]`testImplementation` \nbecause the libraries are needed only during the Gradle test phase and do not need to be \npackaged with the application.\n\nNow, the created WAR file contains the web application, and dev mode can run any integration \ntest classes that it finds. Integration test classes are classes with names that end in `IT`.\n\nThe directory structure of the project in the `start` folder should now look like this \nexample:\n\n[source, role=\"no_copy\"]\n----\n└── build.gradle\n├── settings.gradle\n└── src\n    ├── main\n    │    ├── java\n    │    ├── liberty\n    │    │    └── config\n    │    └── webapp\n    │         └── WEB_INF\n    └── test\n         └── java\n\n----\n\n=== A few more pieces\n\nWe show a few more Gradle tricks in this example with the [hotspot=openbrowser file=1]`openBrowser` task. \nThis task displays your application and the test report in the default browser.\n\nThe final Gradle magic to add is the task dependency directives.\nThe [hotspot=depends file=1]`dependency directives` organizes task execution. \nIn this case, the test task is set to run after the Liberty instance is started, and the\n[hotspot=openbrowser file=1]`openBrowser` task is executed after the test task is finalized.\n\n=== Running the tests\n\nBecause you started Open Liberty in dev mode at the start of the guide, press the `enter/return` \nkey from the command-line session where you started dev mode to run the tests.\nYou will see that the browser opened up the test summary page, which ran one successful test.\n\nTo see whether the test detects a failure, change the [hotspot=responsestring file=2]`response string` in the \n[hotspot file=2]`src/main/java/io/openliberty/guides/hello/HelloServlet.java` file \nso that it doesn't match the string that the test is looking for. Then rerun the Gradle \ntest to automatically restart and retest your application to check to see if the test fails.\n\n[role='command']\ninclude::{common-includes}/devmode-quit-ctrlc.adoc[]\n\n== Great work! You're done!\n\nYou built and tested a web application project running on an Open Liberty instance using Gradle.\n\ninclude::{common-includes}/attribution.adoc[subs=\"attributes\"]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fguide-gradle-intro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenliberty%2Fguide-gradle-intro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fguide-gradle-intro/lists"}