324 lines
8.8 KiB
Plaintext
324 lines
8.8 KiB
Plaintext
|
[[cli]]
|
||
|
|
= Spring Boot CLI
|
||
|
|
|
||
|
|
[partintro]
|
||
|
|
--
|
||
|
|
The Spring Boot CLI is a command line tool that can be used if you want to quickly
|
||
|
|
prototype with Spring. It allows you to run Groovy scripts, which means that you have a
|
||
|
|
familiar Java-like syntax, without so much boilerplate code.
|
||
|
|
--
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-installation]]
|
||
|
|
== Installing the CLI
|
||
|
|
The Spring Boot CLI can be installed manually; using GVM (the Groovy Environment
|
||
|
|
Manually) or using Homebrew if you are an OSX user. See
|
||
|
|
``<<getting-started.adoc#getting-started-installing-the-cli>>''
|
||
|
|
in the ``Getting started'' section for comprehensive installation instructions.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-using-the-cli]]
|
||
|
|
== Using the CLI
|
||
|
|
Once you have installed the CLI you can run it by typing `spring`. If you run `spring`
|
||
|
|
without any arguments, a simple help screen is displayed:
|
||
|
|
|
||
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
||
|
|
----
|
||
|
|
$ spring
|
||
|
|
usage: spring [--help] [--version]
|
||
|
|
<command> [<args>]
|
||
|
|
|
||
|
|
Available commands are:
|
||
|
|
|
||
|
|
run [options] <files> [--] [args]
|
||
|
|
Run a spring groovy script
|
||
|
|
|
||
|
|
_... more command help is shown here_
|
||
|
|
----
|
||
|
|
|
||
|
|
You can use `help` to get more details about any of the supported commands. For example:
|
||
|
|
|
||
|
|
[indent=0]
|
||
|
|
----
|
||
|
|
$ spring help run
|
||
|
|
spring run - Run a spring groovy script
|
||
|
|
|
||
|
|
usage: spring run [options] <files> [--] [args]
|
||
|
|
|
||
|
|
Option Description
|
||
|
|
------ -----------
|
||
|
|
--autoconfigure [Boolean] Add autoconfigure compiler
|
||
|
|
transformations (default: true)
|
||
|
|
--classpath, -cp Additional classpath entries
|
||
|
|
-e, --edit Open the file with the default system
|
||
|
|
editor
|
||
|
|
--no-guess-dependencies Do not attempt to guess dependencies
|
||
|
|
--no-guess-imports Do not attempt to guess imports
|
||
|
|
-q, --quiet Quiet logging
|
||
|
|
-v, --verbose Verbose logging of dependency
|
||
|
|
resolution
|
||
|
|
--watch Watch the specified file for changes
|
||
|
|
----
|
||
|
|
|
||
|
|
The `version` command provides a quick way to check which version of Spring Boot you are
|
||
|
|
using.
|
||
|
|
|
||
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
||
|
|
----
|
||
|
|
$ spring version
|
||
|
|
Spring CLI v{spring-boot-version}
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-run]]
|
||
|
|
=== Running applications using the CLI
|
||
|
|
You can compile and run Groovy source code using the `run` command. The Spring Boot CLI
|
||
|
|
is completely self contained so you don't need any external Groovy installation.
|
||
|
|
|
||
|
|
Here is an example ``hello world'' web application written in Groovy:
|
||
|
|
|
||
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||
|
|
----
|
||
|
|
@Controller
|
||
|
|
class WebApplication {
|
||
|
|
|
||
|
|
@RequestMapping("/")
|
||
|
|
@ResponseBody
|
||
|
|
String home() {
|
||
|
|
return "Hello World!"
|
||
|
|
}
|
||
|
|
|
||
|
|
}
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-deduced-grab-annotations]]
|
||
|
|
==== Deduced ``grab'' dependencies
|
||
|
|
Standard Groovy includes a `@Grab` annotation which allows you to declare dependencies
|
||
|
|
on a third-party libraries. This useful technique allows Groovy to download jars in the
|
||
|
|
same way as Maven or Gradle would; but without requiring you to use a build tool.
|
||
|
|
|
||
|
|
Spring Boot extends this technique further, and will attempt to deduce which libraries
|
||
|
|
to ``grab'' based on your code. For example, since the `WebApplication` code above uses
|
||
|
|
`@Controller` annotations, ``Tomcat'' and ``Spring MVC'' will be grabbed.
|
||
|
|
|
||
|
|
The following items are used as ``grab hints'':
|
||
|
|
|
||
|
|
|===
|
||
|
|
| Items | Grabs
|
||
|
|
|
||
|
|
|`JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`
|
||
|
|
|JDBC Application.
|
||
|
|
|
||
|
|
|`@EnableJmsMessaging`
|
||
|
|
|JMS Application.
|
||
|
|
|
||
|
|
|`@Test`
|
||
|
|
|JUnit.
|
||
|
|
|
||
|
|
|`@EnableRabbitMessaging`
|
||
|
|
|RabbitMQ.
|
||
|
|
|
||
|
|
|`@EnableReactor`
|
||
|
|
|Project Reactor.
|
||
|
|
|
||
|
|
|extends `Specification`
|
||
|
|
|Spock test.
|
||
|
|
|
||
|
|
|`@EnableBatchProcessing`
|
||
|
|
|Spring Batch.
|
||
|
|
|
||
|
|
|`@MessageEndpoint` `@EnableIntegrationPatterns`
|
||
|
|
|Spring Integration.
|
||
|
|
|
||
|
|
|`@EnableDeviceResolver`
|
||
|
|
|Spring Mobile.
|
||
|
|
|
||
|
|
|`@Controller` `@RestController` `@EnableWebMvc`
|
||
|
|
|Spring MVC + Embedded Tomcat.
|
||
|
|
|
||
|
|
|`@EnableWebSecurity`
|
||
|
|
|Spring Security.
|
||
|
|
|
||
|
|
|`@EnableTransactionManagement`
|
||
|
|
|Spring Transaction Management.
|
||
|
|
|===
|
||
|
|
|
||
|
|
TIP: See subclasses of
|
||
|
|
{sc-spring-boot-cli}/compiler/CompilerAutoConfiguration.{sc-ext}[`CompilerAutoConfiguration`]
|
||
|
|
in the Spring Boot CLI source code to understand exactly how customizations are applied.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-default-import-statements]]
|
||
|
|
==== Default import statements
|
||
|
|
To help reduce the size of your Groovy code, several `import` statements are
|
||
|
|
automatically included. Notice how the example above refers to `@Component`,
|
||
|
|
`@Controller`, `@RequestMapping` and `@ResponseBody` without needing to use
|
||
|
|
fully-qualified names or `import` statements.
|
||
|
|
|
||
|
|
TIP: Many Spring annotations will work without using `import` statements. Try running
|
||
|
|
your application to see what fails before adding imports.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-automatic-main-method]]
|
||
|
|
==== Automatic main method
|
||
|
|
Unlike the equilvement Java application, you do not need to include a
|
||
|
|
`public static void main(String[] args)` method with your `Groovy` scripts. A
|
||
|
|
`SpringApplication` is automatically created, with your compiled code acting as the
|
||
|
|
`source`.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-testing]]
|
||
|
|
=== Testing your code
|
||
|
|
The `test` command allows you to compile and run tests for your application. Typical
|
||
|
|
usage looks like this:
|
||
|
|
|
||
|
|
[indent=0]
|
||
|
|
----
|
||
|
|
$ spring test app.groovy tests.groovy
|
||
|
|
Total: 1, Success: 1, : Failures: 0
|
||
|
|
Passed? true
|
||
|
|
----
|
||
|
|
|
||
|
|
In this example, `tests.groovy` contains JUnit `@Test` methods or Spock `Specification`
|
||
|
|
classes. All the common framework annotations and static methods should be available to
|
||
|
|
you without having to `import` them.
|
||
|
|
|
||
|
|
Here is the `test.groovy` file that we used above:
|
||
|
|
|
||
|
|
[source,groovy,indent=0]
|
||
|
|
----
|
||
|
|
class ApplicationTests {
|
||
|
|
|
||
|
|
@Test
|
||
|
|
void homeSaysHello() {
|
||
|
|
assertEquals("Hello World", new WebApplication().home())
|
||
|
|
}
|
||
|
|
|
||
|
|
}
|
||
|
|
----
|
||
|
|
|
||
|
|
TIP: If you have more than one test source files, you might prefer to organize them
|
||
|
|
into a `test` directory.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-multiple-source-files]]
|
||
|
|
=== Applications with multiple source files
|
||
|
|
You can use ``shell globbing'' with all commands that accept file input. This allows you
|
||
|
|
to easily use multiple files from a single directory, e.g.
|
||
|
|
|
||
|
|
[indent=0]
|
||
|
|
----
|
||
|
|
$ spring run *.groovy
|
||
|
|
----
|
||
|
|
|
||
|
|
This technique can also be useful if you want to segregate your ``test'' or ``spec'' code
|
||
|
|
from the main application code:
|
||
|
|
|
||
|
|
[indent=0]
|
||
|
|
----
|
||
|
|
$ spring test app/*.groovy test/*.groovy
|
||
|
|
----
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-jar]]
|
||
|
|
=== Packaging your application
|
||
|
|
You can use the `jar` command to package your application into a self-contained
|
||
|
|
executable jar file. For example:
|
||
|
|
|
||
|
|
[indent=0]
|
||
|
|
----
|
||
|
|
$ spring jar my-app.jar *.groovy
|
||
|
|
----
|
||
|
|
|
||
|
|
The resulting jar will contain the classes produced by compiling the application and all
|
||
|
|
of the application's dependencies so that it can then be run using `java -jar`. The jar
|
||
|
|
file will also contain entries from the application's classpath.
|
||
|
|
|
||
|
|
See the output of `spring help jar` for more information.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-shell]]
|
||
|
|
=== Using the embedded shell
|
||
|
|
Spring Boot includes command-line completion scripts for BASH and zsh shells. If you
|
||
|
|
don't use either of these shells (perhaps you are a Windows user) then you can use the
|
||
|
|
`shell` command to launch an integrated shell.
|
||
|
|
|
||
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
||
|
|
----
|
||
|
|
$ spring shell
|
||
|
|
*Spring Boot* (v{spring-boot-version})
|
||
|
|
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.
|
||
|
|
----
|
||
|
|
|
||
|
|
From inside the embedded shell you can run other commands directly:
|
||
|
|
|
||
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
||
|
|
----
|
||
|
|
$ version
|
||
|
|
Spring CLI v{spring-boot-version}
|
||
|
|
----
|
||
|
|
|
||
|
|
The embedded shell supports ANSI color output as well as `tab` completion. If you need
|
||
|
|
to run a native command you can use the `$` prefix. Hitting `ctrl-c` will exit the
|
||
|
|
embedded shell.
|
||
|
|
|
||
|
|
[[cli-groovy-beans-dsl]]
|
||
|
|
== Developing application with the Groovy beans DSL
|
||
|
|
Spring Framework 4.0 has native support for a `beans{}` ``DSL'' (borrowed from
|
||
|
|
http://grails.org/[Grails]), and you can embed bean definitions in your Groovy
|
||
|
|
application scripts using the same format. This is sometimes a good way to include
|
||
|
|
external features like middleware declarations. For example:
|
||
|
|
|
||
|
|
[source,groovy,indent=0]
|
||
|
|
----
|
||
|
|
@Configuration
|
||
|
|
class Application implements CommandLineRunner {
|
||
|
|
|
||
|
|
@Autowired
|
||
|
|
SharedService service
|
||
|
|
|
||
|
|
@Override
|
||
|
|
void run(String... args) {
|
||
|
|
println service.message
|
||
|
|
}
|
||
|
|
|
||
|
|
}
|
||
|
|
|
||
|
|
import my.company.SharedService
|
||
|
|
|
||
|
|
beans {
|
||
|
|
service(SharedService) {
|
||
|
|
message "Hello World"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
----
|
||
|
|
|
||
|
|
You can mix class declarations with `beans{}` in the same file as long as they stay at
|
||
|
|
the top level, or you can put the beans DSL in a separate file if you prefer.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
[[cli-whats-next]]
|
||
|
|
== What to read next
|
||
|
|
There are some {github-code}/spring-boot-cli/samples[sample groovy
|
||
|
|
scripts] available from the GitHub repository that you can use to try out the
|
||
|
|
Spring Boot CLI. There is also extensive javadoc throughout the
|
||
|
|
{sc-spring-boot-cli}[source code].
|
||
|
|
|
||
|
|
If you find that you reach the limit of the CLI tool, you will probably want to look
|
||
|
|
at converting your application to full Gradle or Maven built ``groovy project''. The
|
||
|
|
next section covers Spring Boot's
|
||
|
|
``<<build-tool-plugins.adoc#build-tool-plugins, Build tool plugins>>'' that you can
|
||
|
|
use with Gradle or Maven.
|