1. Getting Started
2. What you will need
3. Create an Application
4. Introduction
5. Main Class
6. Controller
7. Generate Executable JAR
8. Run the Executable JAR
9. Time To First Request
- 9.1. Script
- 9.2. Measurement
10. Next steps
11. Help with the Micronaut Framework

Create an Executable JAR of a Micronaut application

Learn how to generate an executable JAR of a Micronaut application with Maven or Gradle.

Authors: Sergio del Amo

Micronaut Version: 3.9.2

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

2. What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE
JDK 1.8 or greater installed with JAVA_HOME configured appropriately

3. Create an Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide --build=maven --lang=java

If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

4. Introduction

To distribute a self-contained Micronaut application that can be run from the command line, you can generate a fat-jar or uber-jar. A fat JAR combines every project’s dependency classes and resources into a single output JAR - an executable JAR.

If you use Micronaut Launch or the Micronaut CLI to generate a Micronaut application, the application’s build contains everything you need to produce an executable JAR.

5. Main Class

The generated application contains an Application class, the entry point of the Micronaut application. Moreover, It has the build configuration to define that class as the application’s Main class.

pom.xml

...
    <properties>
...
       <exec.mainClass>example.micronaut.Application</exec.mainClass>
    </properties>

6. Controller

Add a controller which responds with the JSON payload in the root route.

{"message":"Hello World"}

src/main/java/example/micronaut/HelloController.java

package example.micronaut;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

import java.util.Collections;
import java.util.Map;

@Controller (1)
public class HelloController {

    @Get (2)
    public Map<String, Object> index() {
        return Collections.singletonMap("message", "Hello World"); (3)
    }
}

1	The class is defined as a controller with the @Controller annotation mapped to the path `/`.
2	The @Get annotation maps the method to an HTTP GET request.
3	The Micronaut framework will automatically convert it to JSON before sending it.

7. Generate Executable JAR

Create an executable jar including all dependencies:

./mvnw package

The Micronaut Maven Plugin supports different <packaging> types. The previous command does not specify a packing type, and because of that, it uses jar - the default packing type. The command produces a runnable fat JAR.

The Micronaut Maven Plugin delegates to the maven-shade-plugin to produce a JAR file. The io.micronaut:micronaut-parent POM defines the Maven Shade Plugin configuration, and the defaults should be enough. Refer to the Maven Shade Plugin documentation to customize how to produce the executable JAR.

8. Run the Executable JAR

Run the application packaged as a JAR file:

java -jar target/micronautguide-0.1.jar

9. Time To First Request

9.1. Script

Use the following script to measure time to first request of a single output Jar.

src/main/../../ttfr.sh

#!/usr/bin/env bash

set -e

TYPE="docker"
PORT=8080
DELAY=20

usage() {
  echo "$0: Time to first request for checkpoint, native, java or docker applications"
  echo ""
  echo "  $0 [-c|-d|-j|-n] [-p port] ARTIFACT"
  echo ""
  echo "    -c : ARTIFACT is a CRaC checkpoint"
  echo "    -d : ARTIFACT is a docker image (default)"
  echo "    -j : ARTIFACT is a fat jar"
  echo "    -n : ARTIFACT is a native executable"
  echo "    -p : port to check (default 8080)"
  echo ""
}

while getopts 'cdjnp:' flag; do
  case "${flag}" in
    c) TYPE="crac" ;;
    d) TYPE="docker" ;;
    j) TYPE="java" ;;
    n) TYPE="native" ;;
    p) PORT="${OPTARG}" ;;
    *) usage
       exit 1 ;;
  esac
done
shift $(($OPTIND - 1))
echo $1

if [ $# -eq 0 ]; then
  echo "Needs the docker image or Jar file to run"
  exit 1
fi

execute() {
  local END=$((SECONDS+DELAY))
  while ! curl -o /dev/null -s "http://localhost:${PORT}"; do
    if [ $SECONDS -gt $END ]; then
      echo "No response from the app in $DELAY seconds" >&2
      exit 1
    fi
    sleep 0.001;
  done
}

mytime() {
  exec 3>&1 4>&2
  mytime=$(TIMEFORMAT="%3R"; { time $1 1>&3 2>&4; } 2>&1)
  exec 3>&- 4>&-
  echo $mytime
}

if [[ "$TYPE" == "crac" ]]; then
  java -XX:CRaCRestoreFrom=$1 &
  PID=$!
  TTFR=$(mytime execute)
  kill -9 $PID
elif [[ "$TYPE" == "java" ]]; then
  java -jar $1 &
  PID=$!
  TTFR=$(mytime execute)
  kill -9 $PID
elif [[ "$TYPE" == "docker" ]]; then
  CONTAINER=$(docker run -d --rm -p $PORT:$PORT --privileged $1)
  TTFR=$(mytime execute)
  docker container kill $CONTAINER > /dev/null
else
  $1 &
  PID=$!
  TTFR=$(mytime execute)
  kill -9 $PID
fi

if [ "$TTFR" != "" ]; then
    echo "${TTFR} seconds"
else
    exit 1
fi

9.2. Measurement

./ttfr.sh -j target/micronautguide-0.1.jar
 __  __ _                                  _
|  \/  (_) ___ _ __ ___  _ __   __ _ _   _| |_
| |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
| |  | | | (__| | | (_) | | | | (_| | |_| | |_
|_|  |_|_|\___|_|  \___/|_| |_|\__,_|\__,_|\__|
  Micronaut (v3.8.4)

16:00:32.037 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 439ms. Server Running: http://localhost:8080
0.734 seconds

10. Next steps

Explore more features with Micronaut Guides.

Learn more about how to build a Docker Image of your Micronaut application.

11. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

Table of Contents