Table of Contents

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: 4.4.0

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:

3. Create an Application

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

mn create-app example.micronaut.micronautguide --build=gradle --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.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

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.

The Micronaut Gradle Plugin implicitly applies the Gradle Application Plugin.

The application contains the only mandatory configuration for the Application plugin - the specification of the main class:

build.gradle
application {
    mainClass.set("example.micronaut.Application")
}

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

The application applies the Shadow Gradle plugin. You can use its task shadowJar to generate an executable JAR.

Create an executable jar including all dependencies:

./gradlew shadowJar

8. Run the Executable JAR

Run the application packaged as a JAR file:

java -jar build/libs/micronautguide-0.1-all.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 build/libs/micronautguide-0.1-all.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.

12. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).