Spring Boot CLI - Quick Guide

Spring Boot CLI - Overview

The Spring Boot CLI is a Command Line Interface for Spring Boot. It can be used for a quick start with Spring. It can run Groovy scripts which means that a developer need not write boilerplate code; all that is needed is focus on business logic. Spring Boot CLI is the fastest way to create a Spring-based application.

Features

In this section, we will look at the different features of Spring Boot CL −

• It provides an interface to run and test Spring Boot Application from command prompt.

• It internally use Spring Boot Starter and Spring Boot AutoConfigurate components in order to resolve all dependencies and executes the application.

• It contains Groovy compiler and Grape Dependency Manager.

• It supports Groovy Scripts without external Groovy installation.

• It adds Spring Boot defaults and resolve all dependencies automatically.

Spring Boot CLI - Environment Setup

Spring is a Java-based framework; hence, we need to set up JDK first. Following are the steps needed to setup Spring Boot CLI along with JDK installation.

Step 1 - Setup Java Development Kit (JDK)

You can download the latest version of SDK from Oracle's Java site − Java SE Downloads. You will find instructions for installing JDK in downloaded files, follow the given instructions to install and configure the setup. Finally set PATH and JAVA_HOME environment variables to refer to the directory that contains java and javac, typically java_install_dir/bin and java_install_dir respectively.

If you are running Windows and have installed the JDK in C:\jdk1.6.0_15, you would have to put the following line in your C:\autoexec.bat file −

set PATH=C:\jdk1.6.0_15\bin;%PATH% 
set JAVA_HOME=C:\jdk1.6.0_15 

Alternatively, on Windows NT/2000/XP, you will have to right-click on My Computer, select Properties → Advanced → Environment Variables. Then, you will have to update the PATH value and click the OK button.

On Unix (Solaris, Linux, etc.), if the SDK is installed in /usr/local/jdk1.6.0_15 and you use the C shell, you will have to put the following into your .cshrc file −

setenv PATH /usr/local/jdk1.6.0_15/bin:$PATH 
setenv JAVA_HOME /usr/local/jdk1.6.0_15 

Step 2 - Install Spring Boot CLI

You can download the latest version of Spring Boot CLI API as ZIP archive from https://repo.spring.io/release/org/springframework/boot/spring-boot-cli/. Once you download the installation, unpack the zip distribution into a convenient location. For example, in E:\Test\spring-1.5.8.RELEASE on Windows, or /usr/local/spring-1.5.8.RELEASE on Linux/Unix.

Make sure you set your CLASSPATH variable on this directory properly otherwise you will face a problem while running your application.

Or set the path in command prompt temporarily to run the spring boot application as shown below −

E:/Test/> set path=E:\Test\spring-1.5.8.RELEASE\bin;%PATH%

Step 3 - Verify installation

Run the following command on command prompt to verify the installation −

E:/Test/> spring --version

It should print the following output confirming the successful installation −

Spring CLI v1.5.8.RELEASE

Spring Boot CLI - Hello World Example

In this example, we'll create a Spring Boot + MVC + Rest based Web application.

Step 1: Create source Folder

Create a folder FirstApplication in E:\Test folder.

Step 2: Create Source File

Create FirstApplication.groovy file in E:\Test folder with following source code −

@RestController
class FirstApplication {
   @RequestMapping("/")
   
   String welcome() {
      "Welcome to Howcodex.Com"
   }
}

Step 3: Run the application

Type the following command −

E:/Test/> spring run FirstApplication.groovy

Now Spring Boot CLI will come into action, download required dependencies, run the embedded tomcat, deploy the application and start it. You can see the following output on console −

Resolving dependencies..........................................................
................................................................................
........................

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _> | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.8.RELEASE)

2017-11-07 17:36:55.703  INFO 5528 --- [       runner-0] o.s.boot.SpringApplication: 
Starting application on ...
2017-11-07 17:36:55.707  INFO 5528 --- [       runner-0] o.s.boot.SpringApplication: 
No active profile set, falling back to default profiles: default
2017-11-07 17:36:56.067  INFO 5528 --- [       runner-0] ationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@4c108392: startup date [Tue Nov 07 17:36:
56 IST 2017]; root of context hierarchy
2017-11-07 17:36:57.327  INFO 5528 --- [       runner-0] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat initialized with port(s): 8080 (http)
2017-11-07 17:36:57.346  INFO 5528 --- [       runner-0] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2017-11-07 17:36:57.354  INFO 5528 --- [       runner-0] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/8.5.23
2017-11-07 17:36:57.537  INFO 5528 --- [ost-startStop-1] org.apache.catalina.loader.WebappLoader  : Unknown loader org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader@41bfad4f class org.springframew
ork.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader
2017-11-07 17:36:57.567  INFO 5528 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2017-11-07 17:36:57.567  INFO 5528 --- [ost-startStop-1] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 1500 ms
2017-11-07 17:36:57.725  INFO 5528 --- [ost-startStop-1] o.s.b.w.servlet.ServletRegistrationBean  : Mapping servlet: 'dispatcherServlet' to [/]
2017-11-07 17:36:57.730  INFO 5528 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'characterEncodingFilter' to: [/*]
2017-11-07 17:36:57.730  INFO 5528 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]
2017-11-07 17:36:57.730  INFO 5528 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'httpPutFormContentFilter' to: [/*]
2017-11-07 17:36:57.730  INFO 5528 --- [ost-startStop-1] o.s.b.w.servlet.FilterRegistrationBean   : Mapping filter: 'requestContextFilter' to: [/*]
2017-11-07 17:36:58.012  INFO 5528 --- [       runner-0] s.w.s.m.m.a.RequestMappingHandlerAdapter : Looking for @ControllerAdvice: org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@4c108392: startup date [Tue Nov 07 17:36:56 IST 2017]; root of context hierarchy
2017-11-07 17:36:58.066  INFO 5528 --- [       runner-0] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/]}" onto public java.lang.String FirstApplication.home()
2017-11-07 17:36:58.070  INFO 5528 --- [       runner-0] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/error]}" onto public org.springframework.http.ResponseEntity> org.springframework.boot.autoconfigure.web.BasicErrorController.error(javax.servlet.http.HttpServletRequest)
2017-11-07 17:36:58.071  INFO 5528 --- [       runner-0] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped "{[/error],produces=[text/html]}" onto public org.springframework.web.servlet.ModelAndView org.springframework.boot.autoconfigure.web
.BasicErrorController.errorHtml(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)
2017-11-07 17:36:58.096  INFO 5528 --- [       runner-0] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/webjars/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-11-07 17:36:58.096  INFO 5528 --- [       runner-0] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-11-07 17:36:58.129  INFO 5528 --- [       runner-0] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped URL path [/**/favicon.ico] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
2017-11-07 17:36:58.626  INFO 5528 --- [       runner-0] o.s.j.e.a.AnnotationMBeanExporter        : Registering beans for JMX exposure on startup
2017-11-07 17:36:58.696  INFO 5528 --- [       runner-0] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2017-11-07 17:36:58.699  INFO 5528 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 3.529 seconds (JVM running for 190.196)
2017-11-07 17:37:20.217  INFO 5528 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring FrameworkServlet 'dispatcherServlet'
2017-11-07 17:37:20.218  INFO 5528 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : FrameworkServlet 'dispatcherServlet': initialization started

2017-11-07 17:37:20.238  INFO 5528 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : FrameworkServlet 'dispatcherServlet': initialization completed in 20 ms

Step 4: Browse the application in Browser

Our spring based rest application is now ready. Open url as "http://localhost:8080/" and you will see the following output −

Hello World

Important points

Consider the following points to understand how Spring CLI works.−

• All dependency JARs are downloaded for the first time only.

• Spring CLI automatically detects which dependency JARs are to be downloaded based on the classes and annotations used in code.

• Finally after the compilation of the code, deploy the war file on an embedded tomcat and start embedded tomcat server on the default port 8080.

"grab" Dependency Deduction

Standard Groovy codebase contains a @Grab annotation so that dependencies on third-party libraries can be declared. Using @Grab annotation, Grape Dependency Manager downloads jar in similar fashion as that of Maven/Gradle without any build tool. Spring Boot attempts to deduce the required libraries based on code. For example, use of @RestController tells that "Tomcat" and "Spring MVC" libraries are to be grabbed.

Grab Hints

Following table details the hints that Spring Boot uses to download third party libraries −

"grab" Co-ordinates Deduction

We can specify a dependency using @Grab annotation even without specifying group or version. For example,

@Grab('antlr')

Now Spring Boot CLI will download 2.7.7 version of antlr as it is present in Spring Boot's default dependency metadata for 1.5.8 version. Spring Boot maintains all dependency versions by default which are provided in its CLI, Maven dependency management and Gradle plugin. Whenever we declare a dependency of any of those artifacts present in efault dependency metadata without declaring a version, the version listed in its table will be used.

The following table shows all the dependencies and their versions included in the default metadata for Spring Boot CLI 1.5.8 version.

Spring Boot CLI - Default Statements

In this chapter, we will learn about the Default Statements in Spring Boot CLI. To begin with, we will learn about the Default Imports.

Default Imports

Spring CLI automatically imports many libraries by default so that explicit imports are not required. Let us now consider the following groovy script to understand Default Imports.

@RestController
class FirstApplication {
   @RequestMapping("/")
   
   String welcome() {
      "Welcome to Howcodex.Com"
   }
}

Here import for @RestController, @RequestMapping annotations are already included by default by Spring Boot. We're not even require to use fully-qualified names. You can check by running the application.

Type the following command −

E:/Test/> spring run FirstApplication.groovy

The above command will generate the following output on console −

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _> | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.8.RELEASE)

...
2017-11-07 19:22:17.310  INFO 4824 --- [       runner-0] o.s.boot.SpringApplication
: Started application in 3.405 seconds (JVM running for 7.021)

Automatic Main Method

We are not required to create standard main method for groovy script to initialize a spring application. It is automatically created for spring boot application.

Spring Boot CLI - Starter Thymeleaf Project

In this chapter, we will learn how to create a sample Thymeleaf-based project to demonstrate the capabilities of Spring CLI. Follow the below mentioned step to create a sample project −

TestApplication/message.groovy

@Controller
@Grab('spring-boot-starter-thymeleaf')

class MessageController {
   @RequestMapping("/message")
   
   String getMessage(Model model) {
      String message = "Welcome to Howcodex.Com!";
      model.addAttribute("message", message);
      return "message";
   }
} 

TestApplication/templates/message.html

<!DOCTYPE HTML>
<html xmlns:th = "http://www.thymeleaf.org">
   <head> 
      <title>Spring Boot CLI Example</title> 
      <meta http-equiv = "Content-Type" content = "text/html; charset = UTF-8" />
   </head>
   
   <body> 
      <p th:text = "'Message: ' + ${message}" />
   </body>
</html> 

TestApplication/static/index.html

<!DOCTYPE HTML>
<html>
   <head> 
      <title>Spring Boot CLI Example</title> 
      <meta http-equiv = "Content-Type" content = "text/html; charset = UTF-8" />
   </head>
   
   <body>
      <p>Go to <a href = "/msg">Message</a></p>
   </body>
</html> 

Run the application

To run the application, type the following command −

E:/Test/TestApplication/> spring run *.groovy

Now Spring Boot CLI will come into action, download required dependencies, run the embedded tomcat, deploy the application and start it. You can see the following output on console −

Resolving dependencies.............................

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _> | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.8.RELEASE)

...
2017-11-08 16:27:28.300  INFO 8360 --- [       runner-0] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2017-11-08 16:27:28.305  INFO 8360 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 4.203 seconds (JVM running for 38.792)

Browse the application in Browser

Our spring based rest application is now ready. Open url as "http://localhost:8080/" and you will see the following output −

Go to Message

Click on the Message link and you will see the following output −

Message − Welcome to Howcodex.Com!

Important points

Consider the following points to understand the actions taken by Spring CLI −

• The @Grab('spring-boot-starter-thymeleaf') annotation directs CLI to download spring-boot-starter-thymeleaf 1.5.8.RELEASE version.

• Spring CLI automatically detects the version using its metadata, as we have not specified any group id or version id here.

• Finally after code compilation, deploy the war on a embedded tomcat, start embedded tomcat server on the default port 8080.

Spring Boot CLI - Testing Application

In this chapter, we will test the sample project created in Hello World Example Chapter to demonstrate the testing capabilities of Spring CLI. Follow the steps listed in the table below to test the sample project −

FirstApplication/FirstApplication.groovy

@RestController
class FirstApplication {
   @RequestMapping("/")
   
   String welcome() {
      "Welcome to Howcodex.Com"
   }
} 

FirstApplication/TestFirstApplication.groovy

class TestFirstApplication {
   @Test
   void welcomeTest() {
      assertEquals("Welcome to Howcodex.Com", new FirstApplication().welcome())
   }
} 

Run the application

To run the application, type the following command −

E:/Test/FirstApplication/> spring test FirstApplication.groovy TestFirstApplication.groovy

Now Spring Boot CLI will come into action, download the required dependencies, compile the source and test file and unit test the code. The following output will be generated on console −

Resolving dependencies........................................................
.
Time: 0.457

OK (1 test)

Important points

Consider the following points to understand the actions taken by Spring CLI −

• The @Test annotation directs CLI to download JUnit 4.12 version.

• Spring CLI automatically detects the version using its metadata, as we have not specified any dependency.

• Finally, after code compilation, test the application.

Spring Boot CLI - Packaging Application

Spring boot CLI provides jar command in order to package a application as jar file. Let us test the sample project created in Starter Thymeleaf Project Chapter to demonstrate the packaging capabilities of Spring CLI.

Follow the steps describe below to package the sample project −

Package the application

To package the application, begin by typing the following command −

E:/Test/TestApplication/> spring jar TestApplication.jar *.groovy 

Output

The command will print the following output −

E:/Test/TestApplication/> spring jar TestApplication.jar *.groovy 

Output

Now you can see two new files created in TestApplication folder.

• TestApplication.jar − An executable jar file.

• TestApplication.jar.original − Original jar file.

Include/Exclude

By default following directories are included along with their contents −

• public
• resources
• static
• templates
• META-INF

By default, following directories are excluded along with their contents −

• repository
• build
• target
• *.jar files
• *.groovy files

Using --include, we can include directories excluded otherwise. Using --exclude, we can exclude directories included otherwise.

Running the Executable Jar

To run the executable Jar, type the following command −

E:/Test/TestApplication/> java -jar TestApplication.jar

The above command will generate the following output on console −

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _> | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.8.RELEASE)

...
2017-11-08 16:27:28.300  INFO 8360 --- [       runner-0] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2017-11-08 16:27:28.305  INFO 8360 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 4.203 seconds (JVM running for 38.792)

Browse the application in Browser

Our spring-based rest application is now ready. Open url as "http://localhost:8080/" and you will see the following output −

Go to Message

Click on Message link and you will see the following output −

Message: Welcome to Howcodex.Com!

Spring Boot CLI - Creating Project

Spring Boot CLI can be used to create a new project with maven as default build tool using init command. Maven will use https://start.spring.io service. In following example we'll create a web application using thymeleaf. Go to E:\Test folder and type the following command −

E:/Test> spring init --dependencies = web,thymeleaf MavenApplication.zip

The above command will generate the following output −

Using service at https://start.spring.io
Content saved to MavenApplication.zip

Create Gradle project

We can create a Gradle based project as well by setting --build as gradle. To understand this in a better way, consider the example given below. Go to E:\Test folder and type the following command −

E:/Test> spring init --build = gradle --java-version = 1.8 --dependencies = web,thymeleaf --packaging = war GradleApplication.zip

The above command will generate the following output −

Using service at https://start.spring.io
Content saved to GradleApplication.zip

Spring Boot CLI - Using Shell

Spring Boot CLI provides a Shell interface to run the commands in which we can directly run the commands as shown below. Go to E:\Test folder and type the following command −

E:/Test> spring shell

The above command will generate the following output −

?[1mSpring Boot?[m?[2m (v1.5.8.RELEASE)?[m
Hit TAB to complete. Type 'help' and hit RETURN for help, and 'exit' to quit.

Running commands in Shell

In this section, we will learn how to run commands in Shell. Type the following and see the output −

version
Spring CLI v1.5.8.RELEASE

You can press tab to auto complete the commands and type exit to finish the shell console.

Testing the application in shell

Let us now learn how to test the application in shell. Type the following line of code and see the output −

E:\Test\FirstApplication>spring shell
?[1mSpring Boot?[m?[2m (v1.5.8.RELEASE)?[m
Hit TAB to complete. Type 'help' and hit RETURN for help, and 'exit' to quit.
$ test FirstApplication.groovy TestFirstApplication.groovy
.
Time: 0.347

OK (1 test)

$ exit
E:\Test\FirstApplication>