Exercise 2: The Java implementation
Note: This exercise is structured in understanding and hands-on tasks.
Step 1: Understand
1 Usage of Maven for Java
We begin with the Maven part for our Java project.
Maven Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.
In the pom file we define the configuration of our Java project with dependencies, build, and properties including the compiler information as you can see in the pom file below.
REMEMBER: We use this pom file to build our Authors service with RUN mvn -f /usr/src/app/pom.xml clean package
inside our Build environment container.
2 Configuration of the Open Liberty Server
Our Authors Microservice will run on an OpenLiberty Server in a container on Kubernetes.
We need to configure the OpenLiberty server with a server.xml file. For our Java implementation we decided to use MicroProfile and within the feature definition in the server.xml we provide this information to our server with the entry microProfile-3
. The server must be reached in the network. Therefore we define the httpEndpoint including httpPort we use for our microservice. For configuration details take a look into the openliberty documentation.
IMPORTANT: We should remember that this port (httpPort="3000"
) must be exposed in the Dockerfile for our container and mapped inside the Kubernetes deployment configuration.
Also the name of the executable web application is definied in the server.xml
.
Note: Later we will change the contextRoot.
3 Implementation of the REST GET endpoint with MicroProfile
3.1 MicroProfile basics
Some definitions:
Microservice architecture is a popular approach for building cloud-native applications in which each capability is developed as an independent service. It enables small, autonomous teams to develop, deploy, and scale their respective services independently.
Eclipse MicroProfile is a modular set of technologies designed so that you can write cloud-native Java™ Microservices. MicroProfile utilizes some of existing tools (JAX-RS, CDI, JSON-P for example), and combine them with new ones to create a baseline platform optimized for a Microservice architecture.
In the following image you see a list of MicroProfile specifications, we will use the red marked ones.
3.2 Java classes needed to expose the Authors service
For the Authors service to expose the REST API we need to implement three classes:
AuthorsApplication class repesents our web application.
Author class repesents the data structure we use for the Author.
GetAuthor class repesents the REST API.
3.2.1 Class AuthorsApplication
Our web application does not implement any business or other logic, it simply needs to run on a server with no UI. The AuthorsApplication class extends the javax.ws.rs.core.Application class to do this.
The AuthorsApplication
class provides access to the classes from the com.ibm.authors
package at runtime. The implementation of the interface class Application enables the usage of easy REST implementation provided by MircoProfile.
With @ApplicationPath
from MicroProfile we define the base path of the application.
Note: Later we will change the ApplicationPath in this class.
3.2.2 Class Author
This class simply repesents the data structure we use for the Author. No MircoProfile feature is used here.
3.2.3 Class GetAuthor
This class implements the REST API response for our Authors Microservice. We implement the REST endpoint using the MicroProfile REST Client. We use @Path
and @Get
statements from JAX-RS for the REST endpoint and for the OpenAPI documentation we use @OpenAPIDefinition
statements. When you add MicroProfile with OpenAPI, OpenAPI always creates automatically an OpenAPI explorer for you.
REMEMBER: In the server.xml configuration we added MicroProfile to the Open Liberty server as a feature, as you see in the code below.
With the combination of the server.xml and our usage of MicroProfile features in the GetAuthor class we will be able to access an OpenAPI explorer with this URL http://host:http_port/openapi
later.
This is the source code of the GetAuthors class with the mentioned MicroProfile features:
Note: Later we will change the return values for the response in the local source code.
3.3 Supporting live and readiness probes in Kubernetes with HealthCheck
We have added the class HealthEndpoint to the Authors package as you see in the following diagram.
We want to support this Kubernetes function:
Kubernetes provides liveness and readiness probes that are used to check the health of your containers. These probes can check certain files in your containers, check a TCP socket, or make HTTP requests. MicroProfile Health exposes readiness and liveness endpoints on your Microservices. Kubernetes polls these endpoints as specified by the probes to react appropriately to any change in the Microservice’s status.
For more information check the Kubernetes Microprofile Health documentation and the documentation on GitHub.
This is the implementation of the Health Check for Kubernetes in the HealthEndpoint class of the Authors service:
Note: Later we will change return information of the HealthCheckResponse.
This HealthEndpoint is configured in the Kubernetes deployment yaml. In the following yaml extract we see the livenessProbe
definition.
Step 2: Hands-on tasks
Change the code of the authors Microservice and run the service in a container locally
Note: That lab does only need Docker and a terminal session on your local machine.
Step 1: Open a terminal session on you local machine
Step 2: Update server.xml
Change the contextRoot in server.xml to something similar like "myapi"
Open the file cloud-native-starter/authors-java-jee/liberty/server.xml
in a editor and change the value.
Step 3: Update AuthorsApplication.java
Change the @ApplicationPath in the class AuthorsApplication.java something similar like "myv1"
Open the file cloud-native-starter/authors-java-jee/src/main/java/com/ibm/authors/AuthorsApplication.java
in a editor and change the value.
Step 4: Update GetAuthor.java
In the class GetAuthor.java change the returned author name to something similar like "MY NAME"
Open the file cloud-native-starter/authors-java-jee/src/main/java/com/ibm/authors/GetAuthor.java
in a editor and change the value.
Step 5: Update HealthEndpoint.java
In the class HealthEndpoint.java change the returned information to something similar like "ok for the workshop"
Step 6: To test and see how the code works you can run the code locally as a Docker container
Step 7: Open the swagger UI of the mircoservice in a browser and verfiy the changes
Step 8: Open the health check of the mircoservice in a browser and verfiy the changes
Congratulations you have finished exercise 2.
Last updated