How to Use Spring Boot CLI

Spring boot cli is a command line tool available as part of the spring boot framework. This tool can be used to quickly create and run spring boot applications. Using spring boot cli you can,

  • Run spring controllers written in groovy directly on embedded tomcat server.
  • Package spring controllers written in groovy as a standalone executable jar.
  • Create a new starter spring boot project using the spring initializr service hosted here. This is one of the fastest ways to get started on a Java based microservices project.

Please note that this article uses Spring boot version 1.5.1.

Installing Spring Boot CLI

You can install spring boot cli in a number of ways (SDKMan, OSX Homebrew and MacPorts). For this article we will setup spring boot cli manually.

Step 1: Download the spring boot cli zip file from this link. Extract the contents of the zip file to a folder of your choice.

Step 2: Add the bin folder inside the spring boot cli to the PATH variable. For Windows run the following command (or permanently add the PATH at control panel => system => environment variables). Don't forget to replace <path to bin> with the actual path where you have extracted the spring boot cli!

set PATH = %PATH%;<path to bin>

In Linux or Mac, run the following command (or permanently add the PATH in bash profile),

export PATH = $PATH:<path to bin>

Step 3: Verify the version of spring boot cli by running the following command from the command line.

spring --version

Use the following commands to get help information,

spring help
spring help run

Using Spring Boot CLI

Spring boot cli can take concise controllers written in groovy language and then run them directly as a web application. This is probably the fastest way to prototype JSON based http microservices in Java.

Create a new file named helloworld.groovy in a new folder with the following content. This groovy controller creates an http endpoint at the root of a web application and then returns the hello world greeting in JSON format. 

@RestController
class HelloWorld {

    @RequestMapping("/")
    Map home() {
        Map<String,String> greeting = new HashMap();
        greeting.put("greeting","Hello World!");
        return greeting;
    }
}

The above controller can be run as a web application using the following command,

spring run helloworld.groovy

The above command may take a while since it will download all the dependency jars before running the groovy file as a full fledged web application on an embedded tomcat server. Once the server is up and running check the JSON output either by accessing the URL http://localhost:8080 from a browser or by running the following command (linux/mac only),

curl http://localhost:8080

You have your JSON bases microservices application up and running in less than a minute! How cool is that!

If you look closely at the helloworld.groovy you will notice that it has no imports or main method. This is where the spring boot cli does its magic. It automatically adds a number of things by making some default assumptions,

  • Automatically adds dependencies by looking at code and annotations. Spring mvc and embedded tomcat libraries are automatically added due to the @RestController annotation.
  • Adds default import statements for commonly uses classes. In the above example it adds imports for RestController and RequestMapping.
  • Adds a wrapper application class with main method as the entry point to the application.

What if you want to convert the groovy controller classes as standalone executable jar files? This is required if you want to quickly host your application in the cloud. Well, spring boot cli has a command to create the fat jar containing all dependencies from the groovy controllers,

spring jar myapp.jar *.groovy

This creates a single jar containing compiled groovy classes with all dependencies added including the embedded tomcat. This jar can be directly executed from the command line,

java -jar myapp.jar

This starts the embedded tomcat and configures the web application enables all the controllers on the specified endpoints.

One problem with using spring run is that you don't have much control over the web application created. If you are working with a production spring boot application what you need is the initial starter project. Spring boot cli can be used to create the starter project,

spring init --dependencies=web --build=gradle myapp

This creates a spring boot starter project using gradle build system (If you don't specify the build type, a maven project will be created). To build and run this sample application, simply run the following command from the myapp folder newly created.

On linux/mac,

./gradlew bootRun

On windows,

gradlew.bat bootRun

To create a distributable jar file, run the following command,

./gradlew bootRepackage

The executable fat jar is available in build/libs folder of the new project.

Running Multiple Controllers

It is possible to pass multiple groovy files to spring boot cli. Just use the following command,

spring run *.groovy

References

Posted in Spring Boot