Skip to content

Commit

Permalink
Merge pull request #163 from OpenLiberty/staging
Browse files Browse the repository at this point in the history 
Merge staging to prod - Change server to runtime or instance
  • Loading branch information
@gkwan-ibm
gkwan-ibm authored Aug 22, 2023
2 parents d81c6b9 + 8a27e30 commit 7ce8d45
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 17 deletions.
24 changes: 12 additions & 12 deletions README.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ Learn how to build and test a simple web application using Maven and Open Libert

== What you'll learn

You will learn how to configure a simple web servlet application using https://maven.apache.org/what-is-maven.html[Maven^] and the https://github.com/OpenLiberty/ci.maven/blob/main/README.md[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?`.
You will learn how to configure a simple web servlet application using https://maven.apache.org/what-is-maven.html[Maven^] and the https://github.com/OpenLiberty/ci.maven/blob/main/README.md[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 instance 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 a build tool like Maven is that you can define the details of the project and any dependencies it has, and Maven automatically downloads and installs the dependencies. Another benefit of using Maven is that it can run repeatable, automated tests on the application. You can, of course, test your application manually by starting a server and pointing a web browser at the application URL. However, 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 change the application, the build fails, and you know that you introduced a regression that requires a fix to your code.
One benefit of using a build tool like Maven is that you can define the details of the project and any dependencies it has, and Maven automatically downloads and installs the dependencies. Another benefit of using Maven is that it can run repeatable, automated tests on the application. You can, of course, test your application manually by starting a Liberty instance and pointing a web browser at the application URL. However, 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 change the application, the build fails, and you know that you introduced a regression that requires a fix to your code.

Choosing a build tool often comes down to personal or organizational preference, but you might choose to use Maven for several reasons. Maven defines its builds by using XML, which is probably familiar to you already. As a mature, commonly used build tool, Maven probably integrates with whichever IDE you prefer to use. Maven also has an extensive plug-in library that offers various ways to quickly customize your build. Maven can be a good choice if your team is already familiar with it.

Expand Down Expand Up @@ -93,7 +93,7 @@ cd finish
mvn liberty:run
```

After you see the following message, your application server is ready.
After you see the following message, your Liberty instance is ready.

[role="no_copy"]
----
Expand Down Expand Up @@ -125,7 +125,7 @@ include::{common-includes}/twyb-end.adoc[]

The simple web application that you will build using Maven and Open Liberty is provided for you in the `start` directory so that you can focus on learning about Maven. This application uses a standard Maven directory structure, eliminating the need to customize the `pom.xml` file so that Maven understands your project layout.

All the application source code, including the Open Liberty server configuration (`server.xml`), is in the `src/main/liberty/config` directory:
All the application source code, including the Open Liberty `server.xml` configuration file, is in the `src/main/liberty/config` directory:

[source, role="no_copy"]
----
Expand Down Expand Up @@ -174,26 +174,26 @@ A typical POM for a Liberty application contains the following sections:
* **Dependencies** ([hotspot=dependencies file=0]`dependencies`): Any Java dependencies that are required for compiling, testing, and running the application are listed here.
* **Build plugins** ([hotspot=build file=0]`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.

The project coordinates describe the name and version of the application. The [hotspot=artifactID file=0]`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 [hotspot file=0]`pom.xml` file use variables that are resolved by the [hotspot=artifactID file=0]`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 [hotspot file=0]`pom.xml` file. The value of the [hotspot=packaging file=0]`packaging` field is `war` so that the project output artifact is a WAR file.
The project coordinates describe the name and version of the application. The [hotspot=artifactID file=0]`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 instance that is created. You'll notice that other fields in the [hotspot file=0]`pom.xml` file use variables that are resolved by the [hotspot=artifactID file=0]`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 [hotspot file=0]`pom.xml` file. The value of the [hotspot=packaging file=0]`packaging` field is `war` so that the project output artifact is a WAR file.

The first four properties in the properties section of the project, just define the encoding ([hotspot=encoding file=0]`UTF-8`) and version of Java ([hotspot=java-version file=0]`Java 8`) that Maven uses to compile the application source code.
The first four properties in the properties section of the project, just define the encoding ([hotspot=encoding file=0]`UTF-8`) and version of Java ([hotspot=java-version file=0]`Java 11`) that Maven uses to compile the application source code.

Open Liberty configuration properties provide you with a single place to specify values that are used in multiple places throughout the application. For example, the [hotspot=default-http-port file=0]`default.http.port` value is used in both the server configuration ([hotspot=httpEndpoint file=2]`server.xml`) file and will be used in the test class that you will add (`EndpointIT.java`) to the application. Because the [hotspot=default-http-port file=0]`default.http.port` value is specified in the [hotspot file=0]`pom.xml` file, you can easily change the port number that the server runs on without updating the application code in multiple places.
Open Liberty configuration properties provide you with a single place to specify values that are used in multiple places throughout the application. For example, the [hotspot=default-http-port file=0]`default.http.port` value is used in both the Liberty [hotspot=httpEndpoint file=2]`server.xml` configuration file and will be used in the test class that you will add (`EndpointIT.java`) to the application. Because the [hotspot=default-http-port file=0]`default.http.port` value is specified in the [hotspot file=0]`pom.xml` file, you can easily change the port number that the Liberty instance runs on without updating the application code in multiple places.

HelloServlet.java
[source, java, linenums, role='code_column hide_tags=comment,javadoc1,javadoc2']
----
include::finish/src/main/java/io/openliberty/guides/hello/HelloServlet.java[]
----

The [hotspot file=1]`HelloServlet.java` class depends on [hotspot=javax-servlet-api file=0]`javax.servlet-api` to compile. Maven will download this dependency from the Maven Central repository using the [hotspot=groupID-servlet-api file=0]`groupId`, [hotspot=artifactID-servlet-api file=0]`artifactId`, and [hotspot=version-servlet-api file=0]`version` details that you provide here. The dependency is set to [hotspot=scope-servlet-api file=0]`provided`, which means that the API is in the server runtime and doesn't need to be packaged by the application.
The [hotspot file=1]`HelloServlet.java` class depends on [hotspot=jakarta.jakartaee-api file=0]`jakarta.jakartaee-api` to compile. Maven will download this dependency from the Maven Central repository using the [hotspot=groupID-api file=0]`groupId`, [hotspot=artifactID-api file=0]`artifactId`, and [hotspot=version-api file=0]`version` details that you provide here. The dependency is set to [hotspot=scope-api file=0]`provided`, which means that the API is in the Liberty runtime and doesn't need to be packaged by the application.

The [hotspot=build file=0]`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 plug-in, which allows you to install applications into Open Liberty and manage the server instances.
* The Liberty Maven plug-in, which allows you to install applications into Open Liberty and manage the associated Liberty instances.

In the [hotspot=liberty-maven-plugin file=0]`liberty-maven-plugin` plug-in section, you can add a [hotspot=configuration file=0]`configuration` element to specify Open Liberty configuration details. For example, the [hotspot=serverName file=0]`serverName` field defines the name of the Open Liberty server that Maven creates. You specified `guideServer` as the value for [hotspot=serverName file=0]`serverName`. If the [hotspot=serverName file=0]`serverName` field is not included, the default value is `defaultServer`.
In the [hotspot=liberty-maven-plugin file=0]`liberty-maven-plugin` plug-in section, you can add a [hotspot=configuration file=0]`configuration` element to specify Open Liberty configuration details. For example, the [hotspot=serverName file=0]`serverName` field defines the name of the Open Liberty instance that Maven creates. You specified `guideServer` as the value for [hotspot=serverName file=0]`serverName`. If the [hotspot=serverName file=0]`serverName` field is not included, the default value is `defaultServer`.

server.xml
[source, xml, linenums, role='code_column hide_tags=comment']
Expand Down Expand Up @@ -228,7 +228,7 @@ endif::[]

== Testing the web application

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.
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 Liberty instance (unit tests), or you can write them to call the Liberty instance 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.

[role="code_command hotspot", subs="quotes"]
----
Expand Down Expand Up @@ -314,6 +314,6 @@ include::{common-includes}/devmode-quit.adoc[]

== Great work! You're done!

You built and tested a web application project with an Open Liberty server using Maven.
You built and tested a web application project with an Open Liberty instance using Maven.

include::{common-includes}/attribution.adoc[subs="attributes"]
20 changes: 15 additions & 5 deletions finish/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,26 @@
<!-- tag::dependencies[] -->
<dependencies>
<!-- Provided dependencies -->
<!-- tag::jakarta.jakartaee-api[] -->
<dependency>
<!-- tag::groupID-api[] -->
<groupId>jakarta.platform</groupId>
<!-- end::groupID-api[] -->
<!-- tag::artifactID-api[] -->
<artifactId>jakarta.jakartaee-api</artifactId>
<version>9.1.0</version>
<!-- end::artifactID-api[] -->
<!-- tag::version-api[] -->
<version>10.0.0</version>
<!-- end::version-api[] -->
<!-- tag::scope-api[] -->
<scope>provided</scope>
<!-- end::scope-api[] -->
</dependency>
<!-- end::jakarta.jakartaee-api[] -->
<dependency>
<groupId>org.eclipse.microprofile</groupId>
<artifactId>microprofile</artifactId>
<version>5.0</version>
<version>6.0</version>
<type>pom</type>
<scope>provided</scope>
</dependency>
Expand All @@ -65,7 +75,7 @@
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.8.2</version>
<version>5.9.2</version>
<!-- tag::test2[] -->
<scope>test</scope>
<!-- end::test2[] -->
Expand All @@ -87,7 +97,7 @@
<plugin>
<groupId>io.openliberty.tools</groupId>
<artifactId>liberty-maven-plugin</artifactId>
<version>3.7.1</version>
<version>3.8.2</version>
<!-- tag::configuration[] -->
<configuration>
<!-- tag::serverName[] -->
Expand All @@ -101,7 +111,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>2.22.2</version>
<version>3.0.0</version>
<configuration>
<!-- tag::system-property-variables[] -->
<systemPropertyVariables>
Expand Down

0 comments on commit 7ce8d45

Please sign in to comment.