A quick tour of MicroProfile Starter

Let's take a quick tour of MicroProfile Starter:

1. When you go to the MicroProfile Starter "Beta" page, https://start.microprofile.io/, you will see the following landing page:

You can accept the defaults for the Maven-related parameters (https://maven.apache.org/guides/mini/guide-naming-conventions.html), groupId and artifactId, or change them to your liking. The groupId parameter uniquely identifies your project across all projects, and artifactId is the name of the JAR file without the MicroProfile version number. For this tour, accept all of the defaults.

1. Next, select MicroProfile Version from the drop-down list:

For this tour, select MicroProfile version MP 2.1. Notice that, depending on the version of MicroProfile you select, the number of specifications listed in the Example for specifications section will vary. This number depends on how many APIs were included as part of each MicroProfile umbrella release. To find out what APIs were included in each release, please refer to the MicroProfile community presentation (https://docs.google.com/presentation/d/1BYfVqnBIffh-QDIrPyromwc9YSwIbsawGUECSsrSQB0/edit#slide=id.g4ef35057a0_6_205).

1. Then, select MicroProfile Server from the drop-down list:

For this tour, select Thorntail V2, which is the open source project that Red Hat uses to implement the Eclipse MicroProfile specification.

1. Leave all the Examples for specifications checkboxes selected (that is, do not uncheck any of the checkboxes):

This will generate example working code for all of the APIs included in MicroProfile version 2.1.

1. The last step in the samples source code generation process using MicroProfile Starter is to click on the DOWNLOAD button, which will create a ZIP archive. Ensure you save the demo.zip file to your local drive. Then, unzip demo.zip in your local drive. The contents should look like this:

Notice that there's a readme.md file in the generated content. This file contains instructions on how to compile and run the generated code, which includes a sample web application that exercises the different capabilities of Eclipse MicroProfile.

1. Change directory to wherever you unzipped the demo project. In my case, I had it in my Downloads directory:

$ cd Downloads/demo

1. Compile the generated sample code by entering the following command:

$ mvn clean package

1. Run the microservice:

$ java -jar target/demo-thorntail.jar

1. After a few seconds, you will see the following message:

$ INFO  [org.wildfly.swarm] (main) WFSWARM99999: Thorntail is Ready

This indicates that the microservice is up and running.

1. Open your favorite web browser and point it to http://localhost:8080/index.html.

This will open up the sample web application, as follows:

1. To see the capabilities of MicroProfile Config, click on Injected config values. A window tab will open with the following display:

1. Likewise, if you click on Config values by lookup, another window tab will be displayed as follows:

The parameter value's injected value and lookup value that we saw previously are defined in the ./demo/src/main/resources/META-INF/microprofile-config.properties file, as shown here:

$ cat ./src/main/resources/META-INF/microprofile-config.properties
injected.value=Injected value
value=lookup value

1. Imagine that you need to use a different value for the value parameter between development and system testing. You could do this by passing a parameter in the command line when starting the microservice as follows (ensure to exit the running application by pressing Ctrl + C on the Terminal window first):

$ java -jar target/demo-thorntail.jar -Dvalue=hola

1. Now, when you click on Config values by lookup, another window tab is displayed:

Note that the source code executing this logic is located in the generated ./src/main/java/com/example/demo/config/ConfigTestController.java file.

1. To see the capabilities of MicroProfile Fault Tolerance, click on Fallback after timeout. A window tab will open with the following display:

The sample code is exercising the @Fallback annotation in combination with @Timeout. Here's the sample code:

@Fallback(fallbackMethod = "fallback") // fallback handler
   @Timeout(500)
   @GET
   public String checkTimeout() {
     try {
       Thread.sleep(700L);
     } catch (InterruptedException e) {
       //
     }
     return "Never from normal processing";
   }
   public String fallback() {
   return "Fallback answer due to timeout";
   }

The @Timeout annotation specifies that if the method takes longer than 500 milliseconds to execute, a timeout exception should be thrown. This annotation can be used together with @Fallback, which, in this case, invokes the fallback handler called fallback when the timeout exception occurs. In the previously generated sample code, the timeout exception will always happen because the method is executing—that is, sleeping for 700 milliseconds, which is longer than 500 milliseconds.

Note that the source code executing this logic is located in the generated ./src/main/java/com/example/demo/resilient/ResilienceController.java file.

The MicroProfile community welcomes your feedback as well as collaboration or contributions toward the continued development of the MicroProfile Starter project. To give feedback, you need to click on the Give Feedback button in the top-right of the MicroProfile Starter "Beta"(https://start.microprofile.io/) landing page and create an issue.

The MicroProfile Starter project groups and prioritizes requested items and fixes in milestones with the goal of releasing continuously. The MicroProfile Starter working group meets on a regular basis and if you'd like to help the project with your development skills, please send an email to microprofile@googlegroups.com or join the discussion on its Gitter channel (https://gitter.im/eclipse/microprofile-starter). The project information, including the location of its source code, can be found at https://wiki.eclipse.org/MicroProfile/StarterPage.