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.

<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.ibm.cloud</groupId>
 <artifactId>authors</artifactId>
 <version>1.0-SNAPSHOT</version>
 <packaging>war</packaging>

 <dependencies>
  <dependency>
   <groupId>org.eclipse.microprofile</groupId>
   <artifactId>microprofile</artifactId>
   <version>3.0</version>
   <scope>provided</scope>
   <type>pom</type>
  </dependency>
 </dependencies>

 <build>
  <finalName>authors</finalName>
 </build>

 <properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
  <failOnMissingWebXml>false</failOnMissingWebXml>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 </properties>
</project>

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.

FROM maven:3.5-jdk-8 as BUILD

COPY src /usr/src/app/src
COPY pom.xml /usr/src/app
RUN mvn -f /usr/src/app/pom.xml clean package

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.

<?xml version="1.0" encoding="UTF-8"?>
<server description="OpenLiberty Server">

    <featureManager>
        <feature>microProfile-3</feature>
    </featureManager>

    <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="3000" httpsPort="9443"/>

    <webApplication location="authors.war" contextRoot="api"/>

</server>

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.

microprofiles

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.

classdiagram

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.

package com.ibm.authors;

// JAX-RS from Microprofile specification
import javax.ws.rs.core.Application;
import javax.ws.rs.ApplicationPath;

// JAX-RS from Microprofile specification
@ApplicationPath("v1")
public class AuthorsApplication extends 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.

package com.ibm.authors;

public class Author {
public String name;
public String twitter;
public String blog;
}

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.

<featureManager>
        <feature>microProfile-3</feature>
        ....
</featureManager>

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:

// JAX-RS from Microprofile specification
@ApplicationScoped
@Path("/getauthor")
// OpenAPI from Microprofile specification
@OpenAPIDefinition(info = @Info(title = "Authors Service", version = "1.0", description = "Authors Service APIs", contact = @Contact(url = "https://github.com/nheidloff/cloud-native-starter", name = "Niklas Heidloff"), license = @License(name = "License", url = "https://github.com/nheidloff/cloud-native-starter/blob/master/LICENSE")))
public class GetAuthor {
 // JAX-RS from Microprofile specification
 @GET
 // OpenAPI from Microprofile specification
 @APIResponses(value = {
  @APIResponse(
       responseCode = "404",
       description = "Author Not Found"
     ),
     @APIResponse(
       responseCode = "200",
       description = "Author with requested name",
       content = @Content(
         mediaType = "application/json",
         schema = @Schema(implementation = Author.class)
       )
     ),
     @APIResponse(
       responseCode = "500",
       description = "Internal service error"
     )
 })
 @Operation(
      summary = "Get specific author",
      description = "Get specific author"
 )
 public Response getAuthor(@Parameter(
            description = "The unique name of the author",
            required = true,
            example = "Niklas Heidloff",
            schema = @Schema(type = SchemaType.STRING))
   @QueryParam("name") String name) {

   Author author = new Author();
   author.name = "Niklas Heidloff";
   author.twitter = "https://twitter.com/nheidloff";
   author.blog = "http://heidloff.net";

   return Response.ok(this.createJson(author)).build();
 }

 private JsonObject createJson(Author author) {
  JsonObject output = Json.createObjectBuilder().add("name", author.name).add("twitter", author.twitter)
    .add("blog", author.blog).build();
  return output;
 }
}

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.

classdiagram

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:

@Readiness
public class HealthEndpoint implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("authors").withData("authors", "ok").up().build();
    }
}

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.

    livenessProbe:
      exec:
        command: ["sh", "-c", "curl -s http://localhost:3000/"]
      initialDelaySeconds: 20
    readinessProbe:
      exec:
        command: ["sh", "-c", "curl -s http://localhost:3000/health | grep -q authors"]
      initialDelaySeconds: 40

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

cd $ROOT_FOLDER/authors-java-jee
docker build -t authors .
docker run -i --rm -p 3000:3000 authors

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.

<?xml version="1.0" encoding="UTF-8"?>
<server description="OpenLiberty Server">

    <featureManager>
        <feature>microProfile-3</feature>
    </featureManager>

    <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="3000" httpsPort="9443"/>

    <webApplication location="authors.war" contextRoot="myapi"/>

</server>

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.

package com.ibm.authors;

import javax.ws.rs.core.Application;
import javax.ws.rs.ApplicationPath;

@ApplicationPath("myv1")
public class AuthorsApplication extends Application {
}

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.

public Response getAuthor(@Parameter(
            description = "The unique name of the author",
            required = true,
            example = "MY NAME",
            schema = @Schema(type = SchemaType.STRING))
   @QueryParam("name") String name) {

   Author author = new Author();
   author.name = "MY NAME";
   author.twitter = "https://twitter.com/MY NAME";
   author.blog = "http://MY NAME.net";

   return Response.ok(this.createJson(author)).build();
 }

Step 5: Update HealthEndpoint.java

In the class HealthEndpoint.java change the returned information to something similar like "ok for the workshop"

@Health
@ApplicationScoped
public class HealthEndpoint implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("authors").withData("authors", "ok for the workshop").up().build();
    }
}

Step 6: To test and see how the code works you can run the code locally as a Docker container

cd $ROOT_FOLDER/authors-java-jee
docker build -t authors .
docker run -i --rm -p 3000:3000 authors

Step 7: Open the swagger UI of the mircoservice in a browser and verfiy the changes

http://localhost:3000/openapi/ui/

changed-authors-open-api

Step 8: Open the health check of the mircoservice in a browser and verfiy the changes

http://localhost:3000/health

changed-authors-healthcheck

---

Congratulations you have finished exercise 2.