root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Add initial reference manual documentation 

See gh-295
This commit is contained in:
Phillip Webb 2014-03-13 13:18:47 -07:00
parent abba0d63fe
commit 163509b5e5
13 changed files with 5416 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

249
spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc Normal file
View File

@ -0,0 +1,249 @@
:numbered!:
[appendix]
[[common-application-properties]]
== Common application properties
Various properties can be specified inside your `application.properties`/`application.yml`
file or as command line switches. This section provides a list common Spring Boot
properties and references to the underlying classes that consume them.
NOTE: Property contributions can come from additional jar files on your classpath so
you should not consider this an exhaustive list. It is also perfectly legal to define
your own properties.
WARNING: This sample file is meant as a guide only. Do **not** copy/paste the entire
content into your application; rather pick only the properties that you need.
[source,properties,indent=0,subs="verbatim,attributes"]
----
# ===================================================================
# COMMON SPRING BOOT PROPERTIES
#
# This sample file is provided as a guideline. Do NOT copy it in its
# entirety to your own application. ^^^
# ===================================================================
# ----------------------------------------
# CORE PROPERTIES
# ----------------------------------------
# SPRING CONFIG (ConfigFileApplicationListner)
spring.config.name= # config file name (default to 'application')
spring.config.location= # location of config file
# PROFILES
spring.profiles= # comma list of active profiles
# APPLICATION SETTINGS (SpringApplication_
spring.main.sources=
spring.main.web-environment= # detect by default
spring.main.show-bannder=true
spring.main.... # see class for all properties
# LOGGING
logging.path=/var/logs
logging.file=myapp.log
logging.config=
# IDENTITY (ContextIdApplicationContextInitializer)
spring.application.name=
vcap.application.name=
# EMBEDDED SERVER CONFIGURATION (ServerProperties)
server.port=8080
server.address= # bind to a specific NIC
server.session-timeout= # session timeout in sections
server.context-path= # the context path, defaults to '/'
server.servlet-path= # the servlet path, defaults to '/'
server.tomcat.access-log-pattern= # log pattern of the access log
server.tomcat.access-log-enabled=false # is access logging enabled
server.tomcat.protocol-header="x-forwarded-proto" # ssl forward headers
server.tomcat.remote-ip-header="x-forwarded-for"
server.tomcat.basedir="/tmp" # base dir (usually not needed, defaults to tmp)
server.tomcat.background-processor-delay=30; # in seconds
server.tomcat.max-threads = 0 # number of threads in protocol handler
# SPRING MVC (HttpMapperProperties)
http.mappers.json-pretty-print=false # pretty print JSON
spring.view.prefix= # MVC view prefix
spring.view.suffix= # ... and suffix
spring.resources.cache-period # cache timeouts in headers sent to browser
# THYMELEAF (ThymeleafAutoConfiguration)
spring.thymeleaf.prefix="classpath:/templates/"
spring.thymeleaf.suffix=".html"
spring.thymeleaf.mode="HTML5"
spring.thymeleaf.encoding="UTF-8"
spring.thymeleaf.cache=true # set to false for hot refresh
# INTERNATIONALIZATION (MessageSourceAutoConfiguration)
spring.messages.basename="messages"
spring.messages.encoding="UTF-8"
# SECURITY (SecurityProperties)
security.user.name="user" # login username
security.user.password= # login password
security.user.role="USER" # role assigned to the user
security.require-ssl=false # advanced settings ...
security.enable-csrf=false
security.basic.enabled=true
security.basic.realm="Spring"
security.basic.path="/**"
security.headers.xss=false
security.headers.cache=false
security.headers.frame=false
security.headers.contentType=false
security.headers.hsts=all # none / domain / all
security.sessions=stateless # always / never / if_required / stateless
security.ignored=false
# DATASOURCE (DataSourceAutoConfiguration & AbstractDataSourceConfiguration)
spring.datasource.name= # name of the data source
spring.datasource.intialize=true # populate using data.sql
spring.datasource.schema= # a schema resource reference
spring.datasource.continueOnError=false # continue even if can't be initialized
spring.datasource.driverClassName= # JDBC Settings...
spring.datasource.url=
spring.datasource.username=
spring.datasource.password=
spring.datasource.max-active=100 # Advanced configuration...
spring.datasource.max-idle=8
spring.datasource.min-idle=8
spring.datasource.initial-size=10
spring.datasource.validation-query
spring.datasource.test-on-borrow=false
spring.datasource.test-on-return=false
# MONGODB (MongoProperties)
spring.data.mongodb.host= # the db host
spring.data.mongodb.port=27017 # the connection port (defaults to 27107)
spring.data.mongodb.uri=mongodb://localhost/test # connection URL
# JPA (JpaBaseConfiguration, HibernateJpaAutoConfiguration)
spring.jpa.properties.*= # properties to set on the JPA connection
spring.jpa.openInView=true
spring.jpa.show-sql=true
spring.jpa.database-platform=
spring.jpa.database=
spring.jpa.generate-ddl=
spring.jpa.hibernate.naming-strategy= # naming classname
spring.jpa.hibernate.ddl-auto= # defaults to create-drop for embedded dbs
# JMX
spring.jmx.enabled=true # Expose MBeans from Spring
# RABBIT (RabbitProperties)
spring.rabbitmq.host= # connection host
spring.rabbitmq.port= # connection port
spring.rabbitmq.username= # login user
spring.rabbitmq.password= # login password
spring.rabbitmq.virtualhost=
spring.rabbitmq.dynamic=
# REDIS (RedisProperties)
spring.redis.host="localhost" # server host
spring.redis.password= # server password
spring.redis.port=6379 # connection port
spring.redis.pool.max-idle=8 # pool settings ...
spring.redis.pool.min-idle=0
spring.redis.pool.max-active=8
spring.redis.pool.max-wait=-1
# ACTIVEMQ (ActiveMQProperties)
spring.activemq.broker-url="tcp://localhost:61616" # connection URL
spring.activemq.in-memory=true
spring.activemq.pooled=false
# JMS (JmsTemplateProperties)
spring.jms.pub-sub-domain=
# SPRING BATCH (BatchDatabaseInitializer)
spring.batch.job.names="job1,job2"
spring.batch.job.enabled=true
spring.batch.initializer.enabled=true
spring.batch.schema= # batch schema to load
# AOP
spring.aop.auto=
spring.aop.proxyTargetClass=
# FILE ENCODING (FileEncodingApplicationListener)
spring.mandatory-file-encoding=false
# ----------------------------------------
# ACTUATOR PROPERTIES
# ----------------------------------------
# MANAGEMENT HTTP SERVER (ManagementServerProperties)
management.port= # defaults to 'server.port'
management.address= # bind to a specific NIC
management.contextPath= # default to '/'
# ENDPOINTS (AbstractEndpoint subclasses)
endpoints.autoconfig.id="autoconfig"
endpoints.autoconfig.sensitive=true
endpoints.autoconfig.enabled=true
endpoints.beans.id="beans"
endpoints.beans.sensitive=true
endpoints.beans.enabled=true
endpoints.configprops.id="configprops"
endpoints.configprops.sensitive=true
endpoints.configprops.enabled=true
endpoints.configprops.keys-to-sanitize="password,secret"
endpoints.dump.id="dump"
endpoints.dump.sensitive=true
endpoints.dump.enabled=true
endpoints.env.id="env"
endpoints.env.sensitive=true
endpoints.env.enabled=true
endpoints.health.id="health"
endpoints.health.sensitive=false
endpoints.health.enabled=true
endpoints.info.id="info"
endpoints.info.sensitive=false
endpoints.info.enabled=true
endpoints.metrics.id="metrics"
endpoints.metrics.sensitive=true
endpoints.metrics.enabled=true
endpoints.shutdown.id="shutdown"
endpoints.shutdown.sensitive=true
endpoints.shutdown.enabled=false
endpoints.trace.id="trace"
endpoints.trace.sensitive=true
endpoints.trace.enabled=true
# MVC ONLY ENDPOINTS
endpoints.jolokia.path="jolokia"
endpoints.jolokia.sensitive=true
endpoints.jolokia.enabled=true # when using Jolokia
endpoints.error.path="/error"
# JMX ENDPOINT (EndpointMBeanExportProperties)
endpoints.jmx.enabled=true
endpoints.jmx.domain= # the JMX domain, defaults to 'org.springboot'
endpoints.jmx.unique-names=false
endpoints.jmx.enabled=true
endpoints.jmx.staticNames=
# JOLOKIA (JolokiaProperties)
jolokia.config.*= # See Jolokia manual
# REMOTE SHELL
shell.auth=simple # jaas, key, simple, spring
shell.command-refresh-interval=-1
shell.command-path-pattern="classpath*:/commands/**, classpath*:/crash/commands/**"
shell.config-path-patterns="classpath*:/crash/*"
shell.disabled-plugins=false # don't expose plugins
shell.ssh.enabled= # ssh settings ...
shell.ssh.keyPath=
shell.ssh.port=
shell.telnet.enabled= # telnet settings ...
shell.telnet.port=
shell.auth.jaas.domain= # authentication settings ...
shell.auth.key.path=
shell.auth.simple.user.name=
shell.auth.simple.user.password=
shell.auth.spring.roles=
# GIT INFO
spring.git.properties= # resource ref to generated git info properties file
----

147
spring-boot-docs/src/main/asciidoc/appendix-auto-configuration-classes.adoc Normal file
View File

@ -0,0 +1,147 @@
[appendix]
[[auto-configuration-classes]]
== Auto-configuration classes
Here is a list of all auto configuration classes provided by Spring Boot with links to
documentation and source code. Remember to also look at the autoconfig report in your
application for more details of which features are switched on.
(start the app with `--debug` or `-Ddebug`, or in an Actuator application use the
`autoconfig` endpoint).
[[auto-configuration-classes-from-autoconfigure-module]]
=== From the ``spring-boot-autoconfigure'' module
The following auto-configuration classes are from the `spring-boot-autoconfigure` module:
[cols="4,1"]
|===
|Configuration Class | Links
|{sc-spring-boot-autoconfigure}/MessageSourceAutoConfiguration.{sc-ext}[MessageSourceAutoConfiguration]
|{dc-spring-boot-autoconfigure}/MessageSourceAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/PropertyPlaceholderAutoConfiguration.{sc-ext}[PropertyPlaceholderAutoConfiguration]
|{dc-spring-boot-autoconfigure}/PropertyPlaceholderAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/amqp/RabbitAutoConfiguration.{sc-ext}[RabbitAutoConfiguration]
|{dc-spring-boot-autoconfigure}/amqp/RabbitAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/aop/AopAutoConfiguration.{sc-ext}[AopAutoConfiguration]
|{dc-spring-boot-autoconfigure}/aop/AopAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/batch/BatchAutoConfiguration.{sc-ext}[BatchAutoConfiguration]
|{dc-spring-boot-autoconfigure}/batch/BatchAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/JpaRepositoriesAutoConfiguration.{sc-ext}[JpaRepositoriesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/JpaRepositoriesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/MongoRepositoriesAutoConfiguration.{sc-ext}[MongoRepositoriesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/MongoRepositoriesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/data/MongoTemplateAutoConfiguration.{sc-ext}[MongoTemplateAutoConfiguration]
|{dc-spring-boot-autoconfigure}/data/MongoTemplateAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jdbc/DataSourceAutoConfiguration.{sc-ext}[DataSourceAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jdbc/DataSourceAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jdbc/DataSourceTransactionManagerAutoConfiguration.{sc-ext}[DataSourceTransactionManagerAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jdbc/DataSourceTransactionManagerAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jms/JmsTemplateAutoConfiguration.{sc-ext}[JmsTemplateAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jms/JmsTemplateAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/jmx/JmxAutoConfiguration.{sc-ext}[JmxAutoConfiguration]
|{dc-spring-boot-autoconfigure}/jmx/JmxAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/mobile/DeviceResolverAutoConfiguration.{sc-ext}[DeviceResolverAutoConfiguration]
|{dc-spring-boot-autoconfigure}/mobile/DeviceResolverAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/mongo/MongoAutoConfiguration.{sc-ext}[MongoAutoConfiguration]
|{dc-spring-boot-autoconfigure}/mongo/MongoAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/orm/jpa/HibernateJpaAutoConfiguration.{sc-ext}[HibernateJpaAutoConfiguration]
|{dc-spring-boot-autoconfigure}/orm/jpa/HibernateJpaAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/reactor/ReactorAutoConfiguration.{sc-ext}[ReactorAutoConfiguration]
|{dc-spring-boot-autoconfigure}/reactor/ReactorAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/redis/RedisAutoConfiguration.{sc-ext}[RedisAutoConfiguration]
|{dc-spring-boot-autoconfigure}/redis/RedisAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/security/SecurityAutoConfiguration.{sc-ext}[SecurityAutoConfiguration]
|{dc-spring-boot-autoconfigure}/security/SecurityAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{sc-ext}[ThymeleafAutoConfiguration]
|{dc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/DispatcherServletAutoConfiguration.{sc-ext}[DispatcherServletAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/DispatcherServletAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/EmbeddedServletContainerAutoConfiguration.{sc-ext}[EmbeddedServletContainerAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/EmbeddedServletContainerAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/HttpMessageConvertersAutoConfiguration.{sc-ext}[HttpMessageConvertersAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/HttpMessageConvertersAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/MultipartAutoConfiguration.{sc-ext}[MultipartAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/MultipartAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/ServerPropertiesAutoConfiguration.{sc-ext}[ServerPropertiesAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/ServerPropertiesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{sc-ext}[WebMvcAutoConfiguration]
|{dc-spring-boot-autoconfigure}/web/WebMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-autoconfigure}/websocket/WebSocketAutoConfiguration.{sc-ext}[WebSocketAutoConfiguration]
|{dc-spring-boot-autoconfigure}/websocket/WebSocketAutoConfiguration.{dc-ext}[javadoc]
|===
[[auto-configuration-classes-from-actuator]]
=== From the ``spring-boot-actuator'' module
The following auto-configuration classes are from the `spring-boot-actuator` module:
[cols="4,1"]
|===
|Configuration Class |Links
|{sc-spring-boot-actuator}/autoconfigure/AuditAutoConfiguration.{sc-ext}[AuditAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/AuditAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{sc-ext}[CrshAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointAutoConfiguration.{sc-ext}[EndpointAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointMBeanExportAutoConfiguration.{sc-ext}[EndpointMBeanExportAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointMBeanExportAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/EndpointWebMvcAutoConfiguration.{sc-ext}[EndpointWebMvcAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/EndpointWebMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ErrorMvcAutoConfiguration.{sc-ext}[ErrorMvcAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ErrorMvcAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/JolokiaAutoConfiguration.{sc-ext}[JolokiaAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/JolokiaAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ManagementSecurityAutoConfiguration.{sc-ext}[ManagementSecurityAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ManagementSecurityAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/ManagementServerPropertiesAutoConfiguration.{sc-ext}[ManagementServerPropertiesAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/ManagementServerPropertiesAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/MetricFilterAutoConfiguration.{sc-ext}[MetricFilterAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/MetricFilterAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/MetricRepositoryAutoConfiguration.{sc-ext}[MetricRepositoryAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/MetricRepositoryAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/TraceRepositoryAutoConfiguration.{sc-ext}[TraceRepositoryAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/TraceRepositoryAutoConfiguration.{dc-ext}[javadoc]
|{sc-spring-boot-actuator}/autoconfigure/TraceWebFilterAutoConfiguration.{sc-ext}[TraceWebFilterAutoConfiguration]
|{dc-spring-boot-actuator}/autoconfigure/TraceWebFilterAutoConfiguration.{dc-ext}[javadoc]
|===

277
spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc Normal file
View File

@ -0,0 +1,277 @@
[appendix]
[[executable-jar]]
== The executable jar format
The `spring-boot-loader` modules allows Spring Boot to support executable jar and
war files. If you're using the Maven or Gradle plugin, executable jars are
automatically generated and you generally won't need to know the details of how
they work.
If you need to create executable jars from a different build system, or if you are just
curious about the underlying technology, this section provides some background.
[[executable-jar-nested-jars]]
=== Nested JARs
Java does not provide any standard way to load nested jar files (i.e. jar files that
are themselves contained within a jar). This can be problematic if you are looking
to distribute a self contained application that you can just run from the command line
without unpacking.
To solve this problem, many developers use ``shaded'' jars. A shaded jar simply packages
all classes, from all jars, into a single 'uber jar'. The problem with shaded jars is
that it becomes hard to see which libraries you are actually using in your application.
It can also be problematic if the the same filename is used (but with different content)
in multiple jars. Spring Boot takes a different approach and allows you to actually nest
jars directly.
[[executable-jar-jar-file-structure]]
==== The executable jar file structure
Spring Boot Loader compatible jar files should be structured in the following way:
[indent=0]
----
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-com
| +-mycompany
| + project
| +-YouClasses.class
+-lib
+-dependency1.jar
+-dependency2.jar
----
Dependencies should be placed in a nested `lib` directory.
[[executable-jar-war-file-structure]]
==== The executable war file structure
Spring Boot Loader compatible war files should be structured in the following way:
[indent=0]
----
example.jar
|
+-META-INF
| +-MANIFEST.MF
+-org
| +-springframework
| +-boot
| +-loader
| +-<spring boot loader classes>
+-WEB-INF
+-classes
| +-com
| +-mycompany
| +-project
| +-YouClasses.class
+-lib
| +-dependency1.jar
| +-dependency2.jar
+-lib-provided
+-servlet-api.jar
+-dependency3.jar
----
Dependencies should be placed in a nested `WEB-INF/lib` directory. Any dependencies
that are required when running embedded but are not required when deploying to
a traditional web container should be placed in `WEB-INF/lib-provided`.
[[executable-jar-jarfile]]
=== Spring Boot's ``JarFile'' class
The core class used to support loading nested jars is
`org.springframework.boot.loader.jar.JarFile`. It allows you load jar
content from a standard jar file, or from nested child jar data. When first loaded, the
location of each `JarEntry` is mapped to a physical file offset of the outer jar:
[indent=0]
----
myapp.jar
+---------+---------------------+
| | /lib/mylib.jar |
| A.class |+---------+---------+|
| || B.class | B.class ||
| |+---------+---------+|
+---------+---------------------+
^ ^ ^
0063 3452 3980
----
The example above shows how `A.class` can be found in `myapp.jar` position `0063`.
`B.class` from the nested jar can actually be found in `myapp.jar` position `3452`
and `B.class` is at position `3980`.
Armed with this information, we can load specific nested entries by simply seeking to
appropriate part if the outer jar. We don't need to unpack the archive and we don't
need to read all entry data into memory.
[[executable-jar-jarfile-compatibility]]
==== Compatibility with the standard Java ``JarFile''
Spring Boot Loader strives to remain compatible with existing code and libraries.
`org.springframework.boot.loader.jar.JarFile` extends from `java.util.jar.JarFile` and
should work as a drop-in replacement. The `RandomAccessJarFile.getURL()` method will
return a `URL` that opens a `java.net.JarURLConnection` compatible connection.
`RandomAccessJarFile` URLs can be used with Java's `URLClassLoader`.
[[executable-jar-launching]]
=== Launching executable jars
The `org.springframework.boot.loader.Launcher` class is a special bootstrap class that
is used as an executable jars main entry point. It is the actual `Main-Class` in your jar
file and it's used to setup an appropriate `URLClassLoader` and ultimately call your
`main()` method.
There are 3 launcher subclasses (`JarLauncher`, `WarLauncher` and `PropertiesLauncher`).
Their purpose is to load resources (`.class` files etc.) from nested jar files or war
files in directories (as opposed to explicitly on the classpath). In the case of the
`[Jar|War]Launcher` the nested paths are fixed `(lib/*.jar` and `lib-provided/*.jar` for
the war case) so you just add extra jars in those locations if you want more. The
`PropertiesLauncher` looks in `lib/` by default, but you can add additional locations by
setting an environment variable `LOADER_PATH` or `loader.path` in `application.properties`
(colon-separated list of directories or archives).
[[executable-jar-launcher-manifest]]
==== Launcher manifest
You need specify an appropriate `Launcher` as the `Main-Class` attribute of
`META-INF/MANIFEST.MF`. The actual class that you want to launch (i.e. the class that
you wrote that contains a `main` method) should be specified in the `Start-Class`
attribute.
For example, here is a typical `MANIFEST.MF` for a executable jar file:
[indent=0]
----
Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication
----
For a war file, it would be:
[indent=0]
----
Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication
----
NOTE: You do not need to specify `Class-Path` entries in your manifest file, the classpath
will be deduced from the nested jars.
[[executable-jar-exploded-archives]]
==== Exploded archives
Certain PaaS implementations may choose to unpack archives before they run. For example,
Cloud Foundry operates in this way. You can run an unpacked archive by simply starting
the appropriate launcher:
[indent=0]
----
$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher
----
[[executable-jar-property-launcher-features]]
=== PropertiesLauncher Features
`PropertiesLauncher` has a few special features that can be enabled with external
properties (System properties, environment variables, manifest entries or
`application.properties`).
[cols="2,4"]
|===
|Key |Purpose
|`loader.path`
|Colon-separated Classpath, e.g. `lib:${HOME}/app/lib`.
|`loader.home`
|Location of additional properties file, e.g. `file:///opt/app`
(defaults to `${user.dir}`)
|`loader.args`
|Default arguments for the main method (space separated)
|`loader.main`
|Name of main class to launch, e.g. `com.app.Application`.
|`loader.config.name`
|Name of properties file, e.g. `loader` (defaults to `application`).
|`loader.config.location`
|Path to properties file, e.g. `classpath:loader.properties` (defaults to
`application/.properties`).
|`loader.system`
|Boolean flag to indicate that all properties should be added to System properties
(defaults to `false`)
|===
Manifest entry keys are formed by capitalizing initial letters of words and changing the
separator to "`-`" from "`.`" (e.g. `Loader-Path`). The exception is `loader.main` which
is looked up as `Start-Class` in the manifest for compatibility with `JarLauncher`).
Environment variables can be capitalized with underscore separators instead of periods.
* `loader.home` is the directory location of an additional properties file (overriding
the default) as long as `loader.config.location` is not specified.
* `loader.path` can contain directories (scanned recursively for jar and zip files),
archive paths, or wildcard patterns (for the default JVM behavior).
* Placeholder replacement is done from System and environment variables plus the
properties file itself on all values before use.
[[executable-jar-restrictions]]
=== Executable jar restrictions
There are a number of restrictions that you need to consider when working with a Spring
Boot Loader packaged application.
[[executable-jar-zip-entry-compression]]
==== Zip entry compression
The `ZipEntry` for a nested jar must be saved using the `ZipEntry.STORED` method. This
is required so that we can seek directly to individual content within the nested jar.
The content of the nested jar file itself can still be compressed, as can any other
entries in the outer jar.
[[executable-jar-system-classloader]]
==== System ClassLoader
Launched applications should use `Thread.getContextClassLoader()` when loading classes
(most libraries and frameworks will do this by default). Trying to load nested jar
classes via `ClassLoader.getSystemClassLoader()` will fail. Please be aware that
`java.util.Logging` always uses the system classloader, for this reason you should
consider a different logging implementation.
[[executable-jar-alternatives]]
=== Alternative single jar solutions
If the above restrictions mean that you cannot use Spring Boot Loader the following
alternatives could be considered:
* http://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin]
* http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader]
* http://one-jar.sourceforge.net[OneJar]

7
spring-boot-docs/src/main/asciidoc/appendix.adoc Normal file
View File

@ -0,0 +1,7 @@
[[appendix]]
= Appendices
include::appendix-application-properties.adoc[]
include::appendix-auto-configuration-classes.adoc[]
include::appendix-executable-jar-format.adoc[]

578
spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc Normal file
View File

@ -0,0 +1,578 @@
[[build-tool-plugins]]
= Build tool plugins
[partintro]
--
Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a
variety of features, including the packaging of executable jars. The section provides
more details on both plugins, as well as some help should you need to extend an
unsupported build system. If you are just getting started, you might want to read
``<<using-spring-boot.adoc#using-boot-build-systems>>'' from the
<<using-spring-boot.adoc#using-boot>> section first.
--
[[build-tool-plugins-maven-plugin]]
== Spring Boot Maven plugin
The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to
package executable jar or war archives and run an application ``in-place''. To use it you
must be using Maven 3 (or better).
[[build-tool-plugins-include-maven-plugin]]
=== Including the plugin
To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins`
section of your `pom.xml`
[source,xml,indent=0,subs="verbatim,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<!-- ... -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>{spring-boot-version}</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
----
This configuration will repackage a jar or war that is built during the `package` phase of
the Maven lifecycle. The following example shows both the repackaged jar, as well as the
original jar, in the `target` directory:
[indent=0]
----
$ mvn package
$ ls target/*.jar
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
----
If you don't include the `<execution/>` configuration as above, you can run the plugin on
its own (but only if the package goal is used as well). For example:
[indent=0]
----
$ mvn package spring-boot:repackage
$ ls target/*.jar
target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original
----
If you are using a milestone or snapshot release you will also need to add appropriate
`pluginRepository` elements:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
----
[[build-tool-plugins-maven-packaging]]
=== Packaging executable jar and war files
Once `spring-boot-maven-plugin` has been included in your `pom.xml` it will automatically
attempt to rewrite archives to make them executable using the `spring-boot:repackage`
goal. You should configure your project to build a jar or war (as appropriate) using the
usual `packaging` element:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<!-- ... -->
<packaging>jar</packaging>
<!-- ... -->
</project>
----
Your existing archive will be enhanced by Spring Boot during the `package` phase. The
main class that you want to launch can either be specified using a configuration option,
or by adding a `Main-Class` attribute to the manifest in the usual way. If you don't
specify a main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you can type the following:
[indent=0]
----
$ mvn package
$ java -jar target/mymodule-0.0.1-SNAPSHOT.jar
----
[[build-tool-plugins-maven-packaging-configuration]]
=== Repackage configuration
The following configuration options are available for the `spring-boot:repackage` goal:
[[build-tool-plugins-maven-packaging-required-params]]
==== Required parameters
[cols="2,4"]
|===
|Name |Description
|`outputDirectory`
|Directory containing the generated archive (defaults to `${project.build.directory}`).
|`finalName`
|Name of the generated archive (defaults to `${project.build.finalName}`).
|===
|==
[[build-tool-plugins-maven-packaging-optional-params]]
==== Optional parameters
[cols="2,4"]
|===
|Name |Description
|`classifier`
|Classifier to add to the artifact generated. If given, the artifact will be attached. If
this is not given, it will merely be written to the output directory according to the
`finalName`.
|`mainClass`
|The name of the main class. If not specified will search for a single compiled class
that contains a `main` method.
|`layout`
|The type of archive (which corresponds to how the dependencies are laid out inside it).
Defaults to a guess based on the archive type.
|===
The plugin rewrites your manifest, and in particular it manages the `Main-Class` and
`Start-Class` entries, so if the defaults don't work you have to configure those there
(not in the jar plugin). The `Main-Class` in the manifest is actually controlled by the
`layout` property of the boot plugin, e.g.
[source,xml,indent=0,subs="verbatim,attributes"]
----
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>{spring-boot-version}</version>
<configuration>
<mainClass>${start-class}</mainClass>
<layout>ZIP</layout>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
----
The layout property defaults to a guess based on the archive type (jar or war). For the
`PropertiesLauncher` the layout is ``ZIP'' (even though the output might be a jar file).
TIP: The executable jar format is <<appendix-executable-jar-format.adoc#executable-jar,
described in the appendix>>.
[[build-tool-plugins-maven-running-applications]]
=== Running applications
The Spring Boot Maven Plugin includes a `run` goal which can be used to launch your
application from the command line. Type the following from the root of your Maven
project:
[indent=0]
----
$ mvn spring-boot:run
----
By default, any `src/main/resources` folder will be added to the application classpath
when you run via the maven plugin. This allows hot refreshing of resources which can be
very useful when developing web applications. For example, you can work on HTML, CSS or
JavaScipt files and see your changes immediately without recompiling your application. It
is also a helpful way of allowing your front end developers to work without needing to
download and install a Java IDE.
[[build-tool-plugins-maven-run-configuration]]
=== Run configuration
The following configuration options are available for the `spring-boot:run` goal:
[[build-tool-plugins-maven-run-configuration-required-params]]
=== Required parameters
[cols="2,4"]
|===
|Name |Description
|`classesDirectrory`
|Directory containing the classes and resource files that should be packaged into the
archive (defaults to `${project.build.outputDirectory}`).
|===
[[build-tool-plugins-maven-run-configuration-optional-params]]
=== Optional parameters
[cols="2,4"]
|===
|Name |Description
|`arguments` or `-Drun.arguments`
|Arguments that should be passed to the application.
|`addResources` or `-Drun.addResources`
|Add Maven resources to the classpath directly, this allows live in-place editing or
resources. Since resources will be added directly, and via the target/classes folder
they will appear twice if `ClassLoader.getResources()` is called. In practice, however,
most applications call `ClassLoader.getResource()` which will always return the first
resource (defaults to `true`).
|`mainClass`
|The name of the main class. If not specified the first compiled class found that
contains a 'main' method will be used.
|`folders`
|Folders that should be added to the classpath (defaults to
`${project.build.outputDirectory}`).
|===
[[build-tool-plugins-gradle-plugin]]
== Spring Boot Gradle plugin
The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to
package executable jar or war archives, run Spring Boot applications and omit version
information from your `build.gradle` file for ``blessed'' dependencies.
[[build-tool-plugins-including-the-gradle-plugin]]
=== Including the plugin
To use the Spring Boot Gradle Plugin simply include a `buildscript` dependency and apply
the `spring-boot` plugin:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
buildscript {
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}")
}
}
apply plugin: 'spring-boot'
----
If you are using a milestone or snapshot release you will also need to add appropriate
`repositories` reference:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
buildscript {
repositories {
maven.url "http://repo.spring.io/snapshot"
maven.url "http://repo.spring.io/milestone"
}
// ...
}
----
[[build-tool-plugins-gradle-dependencies-without-versions]]
=== Declaring dependencies without versions
The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your
build that allows you to omit version numbers when declaring dependencies to ``blessed''
artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the
artifacts declared in the `managementDependencies` section of the
{github-code}/spring-boot-dependencies/pom.xml[`spring-dependencies`]
POM can have their version number resolved automatically.
Simply declare dependencies in the usual way, but leave the version number empty:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
compile("org.thymeleaf:thymeleaf-spring4")
compile("nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect")
}
----
[[build-tool-plugins-gradle-packaging]]
=== Packaging executable jar and war files
Once the `spring-boot` plugin has been applied to your project it will automatically
attempt to rewrite archives to make them executable using the `bootRepackage` task. You
should configure your project to build a jar or war (as appropriate) in the usual way.
The main class that you want to launch can either be specified using a configuration
option, or by adding a `Main-Class` attribute to the manifest. If you don't specify a
main class the plugin will search for a class with a
`public static void main(String[] args)` method.
To build and run a project artifact, you can type the following:
[indent=0]
----
$ gradle build
$ java -jar build/libs/mymodule-0.0.1-SNAPSHOT.jar
----
[[build-tool-plugins-gradle-running-applications]]
=== Running a project in-place
To run a project in place without building a jar first you can use the "bootRun" task:
[indent=0]
----
$ gradle bootRun
----
Running this way makes your static classpath resources (i.e. in `src/main/resources` by
default) reloadable in the live application, which can be helpful at development time.
[[build-tool-plugins-gradle-repackage-configuration]]
=== Repackage configuration
The gradle plugin automatically extends your build script DSL with a `springBoot` element
for configuration. Simply set the appropriate properties as you would any other Gradle
extension (see below for a list of configuration options):
[source,groovy,indent=0,subs="verbatim,attributes"]
----
springBoot {
backupSource = false
}
----
[[build-tool-plugins-gradle-repackage-custom-configuration]]
=== Repackage with custom Gradle configuration
Sometimes it may be more appropriate to not package default dependencies resolved from
`compile`, `runtime` and `provided` scopes. If the created executable jar file
is intended to be run as it is, you need to have all dependencies nested inside it;
however, if the plan is to explode a jar file and run main class manually, you may already
have some of the libraries available via `CLASSPATH`. This is a situation where
you can repackage your jar with a different set of dependencies.
Using a custom
configuration will automatically disable dependency resolving from
`compile`, `runtime` and `provided` scopes. Custom configuration can be either
defined globally (inside the `springBoot` section) or per task.
[source,groovy,indent=0,subs="verbatim,attributes"]
----
task clientJar(type: Jar) {
appendix = 'client'
from sourceSets.main.output
exclude('**/*Something*')
}
task clientBoot(type: BootRepackage, dependsOn: clientJar) {
withJarTask = clientJar
customConfiguration = "mycustomconfiguration"
}
----
In above example, we created a new `clientJar` Jar task to package a customized
file set from your compiled sources. Then we created a new `clientBoot`
BootRepackage task and instructed it to work with only `clientJar` task and
`mycustomconfiguration`.
[source,groovy,indent=0,subs="verbatim,attributes"]
----
configurations {
mycustomconfiguration.exclude group: 'log4j'
}
dependencies {
mycustomconfiguration configurations.runtime
}
----
The configuration that we are referring to in `BootRepackage` is a normal
http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.Configuration.html[Gradle
configuration]. In the above example we created a new configuration named
`mycustomconfiguration` instructing it to derive from a `runtime` and exclude the `log4j`
group. If the `clientBoot` task is executed, the repackaged boot jar will have all
dependencies from `runtime` but no `log4j` jars.
[[build-tool-plugins-gradle-configuration-options]]
==== Configuration options
The following configuration options are available:
[cols="2,4"]
|===
|Name |Description
|`mainClass`
|The main class that should be run. If not specified the value from the manifest will be
used, or if no manifest entry is the archive will be searched for a suitable class.
|`providedConfiguration`
|The name of the provided configuration (defaults to `providedRuntime`).
|`backupSource`
|If the original source archive should be backed-up before being repackaged (defaults
to `true`).
|`customConfiguration`
|The name of the custom configuration.
|`layout`
|The type of archive, corresponding to how the dependencies are laid out inside
(defaults to a guess based on the archive type).
|===
[[build-tool-plugins-understanding-the-gradle-plugin]]
=== Understanding how the Gradle plugin works
When `spring-boot` is applied to your Gradle project a default task named `bootRepackage`
is created automatically. The `bootRepackage` task depends on Gradle `assemble` task, and
when executed, it tries to find all jar artifacts whose qualifier is empty (i.e. tests and
sources jars are automatically skipped).
Due to the fact that `bootRepackage` finds 'all' created jar artifacts, the order of
Gradle task execution is important. Most projects only create a single jar file, so
usually this is not an issue; however, if you are planning to create a more complex
project setup, with custom `Jar` and `BootRepackage` tasks, there are few tweaks to
consider.
If you are 'just' creating custom jar files from your project you can simply disables
default `jar` and `bootRepackage` tasks:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
jar.enabled = false
bootRepackage.enabled = false
----
Another option is to instruct the default `bootRepackage` task to only work with a
default `jar` task.
[source,groovy,indent=0,subs="verbatim,attributes"]
----
bootRepackage.withJarTask = jar
----
If you have a default project setup where the main jar file is created and repackaged,
'and' you still want to create additional custom jars, you can combine your custom
repackage tasks together and use `dependsOn` so that the `bootJars` task will run after
the default `bootRepackage` task is executed:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
task bootJars
bootJars.dependsOn = [clientBoot1,clientBoot2,clientBoot3]
build.dependsOn(bootJars)
----
All the above tweaks are usually used to avoid situations where an already created boot
jar is repackaged again. Repackaging an existing boot jar will not break anything, but
you may find that it includes unnecessary dependencies.
[[build-tool-plugins-other-build-systems]]
== Supporting other build systems
If you want to use a build tool other than Maven or Gradle, you will likely need to develop
your own plugin. Executable jars need to follow a specific format and certain entries need
to be written in an uncompressed form (see the
``<<appendix-executable-jar-format.adoc#executable-jar, executable jar format>>'' section
in the appendix for details).
The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to
actually generate jars. You are also free to use this library directly yourself if you
need to.
[[build-tool-plugins-repackaging-archives]]
=== Repackaging archives
To repackage an existing archive so that it becomes a self-contained executable archive
use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a
single constructor argument that refers to an existing jar or war archive. Use one of the
two available `repackage()` methods to either replace the original file or write to a new
destination. Various settings can also be configured on the repackager before it is
run.
[[build-tool-plugins-nested-libraries]]
=== Nested libraries
When repackaging an archive you can include references to dependency files using the
`org.springframework.boot.loader.tools.Libraries` interface. We don't provide any
concrete implementations of `Libraries` here as they are usually build system specific.
If your archive already includes libraries you can use `Libraries.NONE`.
[[build-tool-plugins-find-a-main-class]]
=== Finding a main class
If you don't use `Repackager.setMainClass()` to specify a main class, the repackager will
use http://asm.ow2.org/[ASM] to read class files and attempt to find a suitable class
with a `public static void main(String[] args)` method. An exception is thrown if more
than one candidate is found.
[[build-tool-plugins-repackage-implementation]]
=== Example repackage implementation
Here is a typical example repackage:
[source,java,indent=0]
----
Repackager repackager = new Repackager(sourceJarFile);
repackager.setBackupSource(false);
repackager.repackage(new Libraries() {
@Override
public void doWithLibraries(LibraryCallback callback) throws IOException {
// Build system specific implementation, callback for each dependency
// callback.library(nestedFile, LibraryScope.COMPILE);
}
});
----
[[build-tool-plugins-whats-next]]
== What to read next
If your interested to looking at how the build tool plugins were developed you can
look at the {github-code}/spring-boot-tools[`spring-boot-tools`] module on GitHub. More
technical details of the <<appendix-executable-jar-format.adoc#executable-jar, executable
jar format>> are covered in the appendix.
If you have specific build related questions, you can check out the
``<<howto.adoc#howto, how-to>>'' guides.

123
spring-boot-docs/src/main/asciidoc/documentation-overview.adoc Normal file
View File

@ -0,0 +1,123 @@
[[boot-documentation]]
= Spring Boot Documentation
[partintro]
--
This section provides a brief overview of Spring Boot reference documentation. Think of
it as map for the rest of the document. You can read this reference guide in a linear
fashion, or you can skip sections if something doesn't interest you.
--
[[boot-documentation-getting-help]]
== Getting help
Having trouble with Spring Boot, We'd like to help!
* Try the <<howto.adoc#howto, How-to's>> -- they provide solutions to the most common
questions
* Learn the Spring basics -- Spring Boot is builds on many other Spring projects, check
the http://spring.io[spring.io] web-site for a wealth of reference documentation. If
you are just starting out with Spring, try one of the http://spring.io/guides[guides]
* Ask a questions - we monitor http://stackoverflow.com[stackoverflow.com] for questions
tagged with http://stackoverflow.com/tags/spring-boot[`spring-boot`]
* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues
NOTE: All of Spring Boot is open source, including the documentation! If you find problems
with the docs; or if you just want to improve them, please <<github-code, get involved>>.
[[boot-documentation-first-steps]]
== First steps
If your just getting started with Spring Boot, or 'Spring' in general,
<<getting-started.adoc#getting-started, this is the place to start!>>
* *From scratch:*
<<getting-started.adoc#getting-started-introducing-spring-boot, Overview>> |
<<getting-started.adoc#getting-started-installing-spring-boot, Installation>>
* *Tutorial:*
<<getting-started.adoc#getting-started-first-application, Part 1>> |
<<getting-started.adoc#getting-started-first-application-code, Part 2>>
* *Running your example:*
<<getting-started.adoc#getting-started-first-application-run, Part 1>> |
<<getting-started.adoc#getting-started-first-application-executable-jar, Part 2>>
== Working with Spring Boot
Ready to actually start using Spring Boot? <<using-spring-boot.adoc#using-boot, We've
got you covered>>.
* *Build systems:*
<<using-spring-boot.adoc#using-boot-maven, Maven>> |
<<using-spring-boot.adoc#using-boot-gradle, Gradle>> |
<<using-spring-boot.adoc#using-boot-ant, Ant>> |
<<using-spring-boot.adoc#using-boot-starter-poms, Starter POMs>>
* *Best practices:*
<<using-spring-boot.adoc#using-boot-structuring-your-code, Code Structure>> |
<<using-spring-boot.adoc#using-boot-configuration-classes, @Configuration>> |
<<using-spring-boot.adoc#using-boot-auto-configuration, @EnableAutoConfiguration>> |
<<using-spring-boot.adoc#using-boot-spring-beans-and-dependency-injection, Beans and Dependency Injection>>
* *Running your code*
<<using-spring-boot.adoc#using-boot-running-from-an-ide, IDE>> |
<<using-spring-boot.adoc#using-boot-running-as-a-packaged-application, Packaged>> |
<<using-spring-boot.adoc#using-boot-running-with-the-maven-plugin, Maven>> |
<<using-spring-boot.adoc#using-boot-running-with-the-gradle-plugin, Gradle>>
* *Packaging your app:*
<<using-spring-boot.adoc#using-boot-packaging-for-production, Production jars>>
* *Spring Boot CLI:*
<<using-spring-boot-cli.adoc#cli, Using the CLI>>
== Learning about Spring Boot features
Need more details about Spring Boot's core features?
<<spring-boot-features.adoc#boot-features, This is for you>>!
* *Core Features:*
<<spring-boot-features.adoc#boot-features-spring-application, SpringApplication>> |
<<spring-boot-features.adoc#boot-features-external-config, External Configuration>> |
<<spring-boot-features.adoc#boot-features-profiles, Profiles>> |
<<spring-boot-features.adoc#boot-features-logging, Logging>>
* *Web Applications:*
<<spring-boot-features.adoc#boot-features-spring-mvc, MVC>> |
<<spring-boot-features.adoc#boot-features-embedded-container, Embedded Containers>>
* *Working with data:*
<<spring-boot-features.adoc#boot-features-sql, SQL>> |
<<spring-boot-features.adoc#boot-features-nosql, NO-SQL>>
* *Testing:*
<<spring-boot-features.adoc#boot-features-testing, Overview>> |
<<spring-boot-features.adoc#boot-features-testing-spring-boot-applications, Boot Applications>> |
<<spring-boot-features.adoc#boot-features-test-utilities, Utils>>
* *Extending:*
<<spring-boot-features.adoc#boot-features-developing-auto-configuration, Auto-configuration>> |
<<spring-boot-features.adoc#boot-features-condition-annotations, @Conditions>>
== Moving to production
When your ready to push your Spring Boot application to production, we've got
<<production-ready-features.adoc#production-ready, some tricks that you might like>>!
* *Management endpoints:*
<<production-ready-features.adoc#production-ready-endpoints, Overview>> |
<<production-ready-features.adoc#production-ready-customizing-endpoints, Customization>>
* *Connection options:*
<<production-ready-features.adoc#production-ready-monitoring, HTTP>> |
<<production-ready-features.adoc#production-ready-jmx, JMX>> |
<<production-ready-features.adoc#production-ready-remote-shell, SSH>>
* *Monitoring:*
<<production-ready-features.adoc#production-ready-metrics, Metrics>> |
<<production-ready-features.adoc#production-ready-auditing, Auditing>> |
<<production-ready-features.adoc#production-ready-tracing, Tracing>>
== Advanced topics
Lastly, we have a few topics for the more advanced user.
* *Build tool plugins:*
<<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven>> |
<<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle>>
* *Appendix:*
<<appendix-application-properties.adoc#common-application-properties, Application Properties>> |
<<appendix-auto-configuration-classes.adoc#auto-configuration-classes, Auto-configuration classes>> |
<<appendix-executable-jar-format.adoc#executable-jar, Executable Jars>>

731
spring-boot-docs/src/main/asciidoc/getting-started.adoc Normal file
View File

@ -0,0 +1,731 @@
[[getting-started]]
= Getting started
[partintro]
--
If your just getting started with Spring Boot, or 'Spring' in general, this is the section
for you! Here we answer the basic '``what?''', '``how?''' and '``why?''' questions. You'll
find a gentle introduction to Spring Boot along with installation instructions.
We'll then build our first Spring Boot application, discussing some core principles as
we go.
--
[[getting-started-introducing-spring-boot]]
== Introducing Spring Boot
Spring Boot makes it easy to create stand-alone, production-grade Spring based
Applications that can you can ``just run''. We take an opinionated view of the Spring
platform and third-party libraries so you can get started with minimum fuss. Most Spring
Boot applications need very little Spring configuration.
You can use Spring Boot to create Java applications that can be started using `java -jar`
or more traditional war deployments. We also provide a command line tool that runs
``spring scripts''.
Our primary goals are:
* Provide a radically faster and widely accessible getting started experience for all
Spring development.
* Be opinionated out of the box, but get out of the way quickly as requirements start to
diverge from the defaults.
* Provide a range of non-functional features that are common to large classes of projects
(e.g. embedded servers, security, metrics, health checks, externalized configuration).
* Absolutely no code generation and no requirement for XML configuration.
[[getting-started-installing-spring-boot]]
== Installing Spring Boot
Spring Boot can be used with ``classic'' Java development tools or installed as a command
line tool. Regardless, you will need http://www.java.com[Java SDK v1.6] or higher. You
should check your current Java installation before you begin:
[indent=0]
----
$ java -version
----
If you are new to Java development, or if you just want to experiment with Spring Boot
you might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> first,
otherwise, read on for ``classic'' installation instructions.
TIP: Although Spring Boot is compatible with Java 1.6, if possible, you should consider
using the latest version of Java.
[[getting-started-installation-instructions-for-java]]
=== Installation instructions for the Java developer
You can use Spring Boot in the same way as any standard java library. Simply include the
appropriate `spring-boot-*.jar` files on your classpath. Spring Boot does not require
any special ``tools'' integration, so you can use any IDE or text editor; and there is
nothing special about a Spring Boot application, so you can run and debug as you would
any other Java program.
Although you _could_ just copy Spring Boot jars, we generally recommend that you use a
build tool that supports dependency management (such as Maven or Gradle).
[[getting-started-maven-installation]]
==== Maven installation
Spring Boot is compatible with Apache Maven 3.0 or above. If you don't already have Maven
installed you can follow the instructions at http://maven.apache.org.
TIP: On many operating systems Maven can be installed via a package manager. If you're an
OSX Homebrew user try `brew install maven`. Ubuntu users can run
`sudo apt-get install maven`.
Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically your
Maven POM file will inherit from the `spring-boot-starter-parent` project and declare
dependencies to one or more <<using-spring-boot.adoc#using-boot-starter-poms, ``Starter
POMs''>>. Spring Boot also provides an optional
<<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> to create
executable jars.
Here is a typical `pom.xml` file:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
</parent>
<!-- Add typical dependencies for a web application -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- Package as an executable jar -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
ifeval::["{spring-boot-repo}" != "release"]
<!-- Add Spring repoistories -->
<!-- (you don't need this if you are using a .RELEASE version) -->
<repositories>
<repository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
endif::[]
</project>
----
[[getting-started-gradle-installation]]
==== Gradle installation
Spring Boot is compatible with Gradle 1.6 or above. If you don't already have Gradle
installed you can follow the instructions at http://www.gradle.org/.
Spring Boot dependencies can be declared using the `org.springframework.boot` `group`.
Typically your project will declare dependencies to one or more
<<using-spring-boot.adoc#using-boot-starter-poms, ``Starter POMs''>>. Spring Boot
provides a useful <<build-tool-plugins.adoc#build-tool-plugins-gradle, Gradle plugin>>
that can be used to simplify dependency declarations and to create executable jars.
.Gradle Wrapper
****
The Gradle Wrapper provides a nice way of ``obtaining'' Gradle when you need to build a
project. It's a small script and library that you commit alongside your code to bootstrap
the build process. See http://www.gradle.org/docs/current/userguide/gradle_wrapper.html
for details.
****
Here is a typical `build.gradle` file:
[source,groovy,indent=0,subs="verbatim,attributes"]
----
buildscript {
repositories {
mavenCentral()
ifndef::release[]
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
endif::release[]
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}")
}
}
apply plugin: 'java'
apply plugin: 'spring-boot'
jar {
baseName = 'myproject'
version = '0.0.1-SNAPSHOT'
}
repositories {
mavenCentral()
ifndef::release[]
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
endif::release[]
}
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("junit:junit")
}
----
[[getting-started-installing-the-cli]]
=== Installing the Spring Boot CLI
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 http://groovy.codehaus.org/[Groovy] scripts,
which means that you have a familiar Java-like syntax, without so much boilerplate code.
You don't need to use the CLI to work with Spring Boot but it's definitely the quickest
way to get a Spring application off the ground.
[[getting-started-manual-cli-installation]]
==== Manual installation
You can download the Spring CLI distribution from the Spring software repository:
* http://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.zip[spring-boot-cli-{spring-boot-version}-bin.zip]
* http://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.tar.gz[spring-boot-cli-{spring-boot-version}-bin.tar.gz]
Cutting edge http://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/[snapshot distributions]
are also available.
Once downloaded, follow the {github-raw}/spring-boot-cli/src/main/content/INSTALL.txt[INSTALL.txt]
instructions from the unpacked archive. In summary: there is a `spring` script
(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file, or alternatively you
can use `java -jar` with the `.jar` file (the script helps you to be sure that the
classpath is set correctly).
[[getting-started-gvm-cli-installation]]
==== Installation with GVM
GVM (the Groovy Environment Manager) can be used for managing multiple versions of
various Groovy and Java binary packages, including Groovy itself and the Spring Boot CLI.
Get `gvm` from http://gvmtool.net and install Spring Boot with
[indent=0,subs="verbatim,quotes,attributes"]
----
$ gvm install springboot
$ spring --version
Spring Boot v{spring-boot-version}
----
If you are developing features for the CLI and want easy access to the version you just
built, follow these extra instructions.
[indent=0,subs="verbatim,quotes,attributes"]
----
$ gvm install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-{spring-boot-version}-bin/spring-{spring-boot-version}/
$ gvm use springboot dev
$ spring --version
Spring CLI v{spring-boot-version}
----
This will install a local instance of `spring` called the `dev` instance inside your gvm
repository. It points at your target build location, so every time you rebuild Spring
Boot, `spring` will be up-to-date.
You can see it by doing this:
[indent=0,subs="verbatim,quotes,attributes"]
----
$ gvm ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* {spring-boot-version}
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
----
[[getting-started-homebrew-cli-installation]]
==== OSX Homebrew installation
If you are on a Mac and using http://brew.sh/[Homebrew], all you need to do to install
the Spring Boot CLI is:
[indent=0]
----
$ brew tap pivotal/tap
$ brew install springboot
----
Homebrew will install `spring` to `/usr/local/bin`.
NOTE: If you don't see the formula, you're installation of brew might be out-of-date.
Just execute `brew update` and try again.
[[getting-started-cli-command-line-completion]]
==== Command-line completion
Spring Boot CLI ships with scripts that provide command completion for
http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29[BASH] and
http://en.wikipedia.org/wiki/Zsh[zsh] shells. You can `source` the script (also named
`spring`) in any shell, or put it in your personal or system-wide bash completion
initialization. On a Debian system the system-wide scripts are in `/etc/bash_completion.d`
and all scripts in that directory are executed when a new shell starts. To run the script
manually, e.g. if you have installed using `GVM`
[indent=0]
----
$ . ~/.gvm/springboot/current/bash_completion.d/spring
$ spring <HIT TAB HERE>
grab help jar run test version
----
NOTE: If you install Spring Boot CLI using Homebrew, the command-line completion scripts
are automatically registered with your shell.
[[getting-started-cli-example]]
==== Quick start Spring CLI example
Here's a really simple web application that you can use to test you installation. Create
a file called `app.groovy`:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
@Controller
class ThisWillActuallyRun {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!"
}
}
----
Then simply run it from a shell:
[indent=0]
----
$ spring run app.groovy
----
NOTE: It will take some time when you first run the application as dependencies are
downloaded, subsequent runs will be much quicker.
Open http://localhost:8080 in your favorite web browser and you should see the following
output:
[indent=0]
----
Hello World!
----
[[getting-started-first-application]]
== Developing your first Spring Boot application
Let's develop a simple ``Hello World!'' web application in Java that highlights some
of Spring Boot's key features. We'll use Maven to build this project since most IDEs
support it.
TIP: The http://spring.io[spring.io] web site contains many ``Getting Started'' guides
that use Spring Boot. If you're looking to solve a specific problem; check there first.
Before we begin, open a terminal to check that you have valid versions of Java and Maven
installed.
[indent=0]
----
$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
----
[indent=0]
----
$ mvn -v
Apache Maven 3.1.1 (0728685237757ffbf44136acec0402957f723d9a; 2013-09-17 08:22:22-0700)
Maven home: /Users/user/tools/apache-maven-3.1.1
Java version: 1.7.0_51, vendor: Oracle Corporation
----
NOTE: This sample needs to be created in its own folder. Subsequent instructions assume
that you have created a suitable folder and that it is your ``current directory''.
[[getting-started-first-application-pom]]
=== Creating the POM
We need to start by creating a Maven `pom.xml` file. The `pom.xml` is the recipe that
will be used to build your project. Open you favorite text editor and add the following:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
</parent>
<!-- Additional lines to be added here... -->
ifeval::["{spring-boot-repo}" != "release"]
<!-- (you don't need this if you are using a .RELEASE version) -->
<repositories>
<repository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<url>http://repo.spring.io/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<url>http://repo.spring.io/milestone</url>
</pluginRepository>
</pluginRepositories>
endif::[]
</project>
----
This should give you a working build, you can test it out by running `mvn package` (you
can ignore the '``jar will be empty - no content was marked for inclusion!''' warning for
now).
NOTE: At this point you could import the project into an IDE (most modern Java IDE's
include built-in support for Maven). For simplicity, we will continue to use a plain
text editor for this example.
[[getting-started-first-application-dependencies]]
=== Adding classpath dependencies
Spring Boot provides a number of ``Starter POMs'' that make easy to add jars to your
classpath. Our sample application has already used `spring-boot-starter-parent` in the
`parent` section of the POM. The `spring-boot-starter-parent` is a special starter
that provides useful Maven defaults. It also provides a `dependency-management` section
so that you can omit `version` tags for ``blessed'' dependencies.
Other ``Starter POMs'' simply provide dependencies that you are likely to need when
developing a specific type of application. Since we are developing web application we will
add a `spring-boot-starter-web` dependency -- but before that, lets look at what we
currently have.
[indent=0]
----
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT
[INFO] +- junit:junit:jar:4.11:test
[INFO] | \- org.hamcrest:hamcrest-core:jar:1.3:test
[INFO] +- org.mockito:mockito-core:jar:1.9.5:test
[INFO] | \- org.objenesis:objenesis:jar:1.0:test
[INFO] \- org.hamcrest:hamcrest-library:jar:1.3:test
----
The `mvn dependency:tree` command prints tree representation of your project dependencies.
You can see that `spring-boot-starter-parent` has already provides some useful test
dependencies. Lets edit our `pom.xml` and add the `spring-boot-starter-web` dependency
just below the `parent` section:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
----
If you run `mvn dependency:tree` again, you will see that there are now a number of
additional dependencies, including the Tomcat web server and Spring Boot itself.
[[getting-started-first-application-code]]
=== Writing the code
To finish our application we need to create a single Java file. Maven will compile sources
from `src/main/java` so you need to create that folder structure, then add a file named
`src/main/java/Example.java`:
[source,java,indent=0]
----
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
import org.springframework.web.bind.annotation.*;
@Controller
@EnableAutoConfiguration
public class Example {
@RequestMapping("/")
@ResponseBody
String home() {
return "Hello World!";
}
public static void main(String[] args) throws Exception {
SpringApplication.run(Example.class, args);
}
}
----
Although there isn't much code here, quite a lot is going on. Lets step though the
important parts.
[[getting-started-first-application-annotations]]
==== The @Controller, @RequestMapping and @ResponseBody annotations
The first annotation on our `Example` class is `@Controller`. This is known as a
_stereotype_ annotation. It provides hints for people reading the code, and for Spring,
that the class plays a specific role. In this case, our class is a web `@Controller` so
Spring will consider it when handling incoming web requests.
The `@RequestMapping` annotation provides ``routing'' information. It is telling Spring
that any HTTP request with the path "`/`" should be mapped to the `home` method. The
additional `@ResponseBody` annotation tells Spring to render the resulting string directly
back to the caller.
TIP: The `@Controller`, `@RequestMapping` and `@ResponseBody` annotations are Spring MVC
annotations (they are not specific to Spring Boot). See the
<{spring-reference}/#mvc>[MVC section] in the Spring
Reference Documentation for more details.
[[getting-started-first-application-auto-configuration]]
==== The @EnableAutoConfiguration annotation
The second class-level annotation is `@EnableAutoConfiguration`. This annotation tells
Spring Boot to ``guess'' how you will want to configure Spring, based on the jar
dependencies that you have added. Since `spring-boot-starter-web` added Tomcat and
Spring MVC, the auto-configuration will assume that you are developing a web application
and setup Spring accordingly.
.Starter POMs and Auto-Configuration
****
Auto-configuration is designed to work well with ``Starter POMs'', but the two concepts
are not directly tied. You are free to pick-and-choose jar dependencies outside of the
starter POMs and Spring Boot will still do its best to auto-configure your application.
****
[[getting-started-first-application-main-method]]
==== The ``main'' method
The final part of our application is the `main` method. This is just a standard method
that follows the Java convention for an application entry point. Our main method delegates
to Spring Boot's `SpringApplication` class by calling `run`. `SpringApplication` will
bootstrap our application, starting Spring which will in turn start the auto-configured
Tomcat web server. We need to pass `Example.class` as an argument to the `run` method to
tell `SpringApplication` which is the primary Spring component. The `args` array is also
passed though to expose any command-line arguments.
[[getting-started-first-application-run]]
=== Running the example
At this point out application should work. Since we have used the
`spring-boot-starter-parent` POM we have a useful `run` goal that we can use to start
the application. Type `mvn spring-boot:run` from the root project directory to start the
application:
[indent=0,subs="attributes"]
----
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v{spring-boot-version})
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
----
If you open a web browser to http://localhost:8080 you should see the following output:
[indent=0]
----
Hello World!
----
To gracefully exit the application hit `ctrl-c`.
[[getting-started-first-application-executable-jar]]
=== Creating an executable jar
Lets finish our example by creating a completely self-contained executable jar file that
we could run in production. Executable jars (sometimes called ``fat jars'') are archives
containing your compiled classes along with all of the jar dependencies that your code
needs to run.
.Executable jars and Java
****
Java does not provide any standard way to load nested jar files (i.e. jar files that are
themselves contained within a jar). This can be problematic if you are looking to
distribute a self contained application.
To solve this problem, many developers use ``shaded'' jars. A shaded jar simply packages
all classes, from all jars, into a single ``uber jar''. The problem with shaded jars is that
it becomes hard to see which libraries you are actually using in your application. It can
also be problematic if the the same filename is used (but with different content) in
multiple jars.
Spring Boot takes a <<appendix-executable-jar-format.adoc#executable-jar, different
approach>> and allows you to actually nest jars directly.
****
To create an executable jar we need to add the `spring-boot-maven-plugin` to our
`pom.xml`. Insert the following lines just below the `dependencies` section:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
----
Save your `pom.xml` and run `mvn package` from the command line:
[indent=0,subs="attributes"]
----
$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:{spring-boot-version}:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
----
If you look in the `target` directory you should see `myproject-0.0.1-SNAPSHOT.jar`. The
file should be around 10 Mb in size. If you want to peek inside, you can use `jar tvf`:
[indent=0]
----
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
----
You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.original`
in the `target` directory. This is the original jar file that Maven created before it was
repackaged by Spring Boot.
To run that application, use the `java -jar` command:
[indent=0,subs="attributes"]
----
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v{spring-boot-version})
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 3.236 seconds (JVM running for 3.764)
----
As before, to gracefully exit the application hit `ctrl-c`.
[[getting-started-whats-next]]
== What to read next
Hopefully this section has provided you with some of the Spring Boot basics, and got you
on your way to writing your own applications. If your a ``task oriented'' type of
developer you might want to jump over to http://spring.io and check out some of the
http://spring.io/guides/[getting started] guides that solve specific
'``How do I do that with Spring''' problems; we also have a Spring Boot specific
``<<howto.adoc#how-to, How-to>>'' reference documentation.
Otherwise, the next logical step is to read the ``<<using-spring-boot.adoc#using-boot>>''
section. If you're really impatient, you could also jump ahead and read about
``<<spring-boot-features.adoc#boot-features>>''.

17
spring-boot-docs/src/main/asciidoc/howto.adoc Normal file
View File

@ -0,0 +1,17 @@
[[howto]]
= ``How-to'' guides
[partintro]
--
This section provides answers to some common '``how do I do that...''' type of questions
that often arise when using Spring Boot. This is by no means an exhaustive list, but it
does cover quite a lot.
If you are having a specific problem that we don't cover here, you might want to check out
http://stackoverflow.com/tags/spring-boot[stackoverflow.com] to see if someone has
already provided an answer; this is also a great place to ask new questions (please use
the `spring-boot` tag).
We're also more than happy to extend this section; If you want to add a ``how-to'' you
can send us a {github-code}[pull request].
--

11
spring-boot-docs/src/main/asciidoc/index.adoc
View File

@ -28,7 +28,14 @@ Phillip Webb; Dave Syer;
:spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
// ====================================================================================== // ======================================================================================
= Spring Boot include::documentation-overview.adoc[]
== Reference Documentation include::getting-started.adoc[]
include::using-spring-boot.adoc[]
include::spring-boot-features.adoc[]
include::production-ready-features.adoc[]
include::spring-boot-cli.adoc[]
include::build-tool-plugins.adoc[]
include::howto.adoc[]
include::appendix.adoc[]
// ====================================================================================== // ======================================================================================

747
spring-boot-docs/src/main/asciidoc/production-ready-features.adoc Normal file
View File

@ -0,0 +1,747 @@
[[production-ready]]
= Production-ready features
[partintro]
--
Spring Boot includes a number of additional features to help you monitor and manage your
application when it's pushed to production. You can choose to manage and monitor your
application using HTTP endpoints, with JMX or even by remote shell (SSH or Telnet).
Auditing, health and metrics gathering can be automatically applied to your application.
--
[[production-ready-enabling]]
== Enabling production-ready features.
The `spring-boot-actuator` project provides all of Spring Boot's production-ready
features. The simplist way to enable the features is to add a dependency to the
`spring-boot-starter-actuator` ``Starter POM''.
.Definition of Actuator
****
An actuator is a manufacturing term, referring to a mechanical device for moving or
controlling something. Actuators can generate a large amount of motion from a small
change.
****
To add the actuator to a Maven based project, add the following ``starter''
dependency:
[source,xml,indent=0]
----
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>
----
For Gradle, use the declaration:
[source,groovy,indent=0]
----
dependencies {
compile("org.springframework.boot:spring-boot-starter-actuator")
}
----
[[production-ready-endpoints]]
== Endpoints
Actuator endpoints allow you to monitor and interact with your application. Spring Boot
includes a number of built-in endpoints and you can also add your own. For example the
`health` endpoint provides basic application health information.
The way that enpoints are exposed will depend on the type of technology that you choose.
Most applications choose HTTP monitoring, where the ID of the endpoint is mapped
to a URL. For example, by default, the `health` endpoint will be mapped to `/health`.
The following endpoints are available:
[cols="2,5,1"]
|===
| ID | Description | Sensitive
|`autoconfig`
|Displays an auto-configuration report showing all auto-configuration candidates and the
reason why they ``were'' or ``were not'' applied.
|true
|`beans`
|Displays a complete list of all the Spring Beans in your application.
|true
|`configprops`
|Displays a collated list of all `@ConfigurationProperties`.
|true
|`dump`
|Performs a thread dump.
|true
|`env`
|Exposes properties from Spring's `ConfigurableEnvironment`.
|true
|`health`
|Shows application health information (defaulting to a simple ``OK'' message).
|false
|`info`
|Displays arbitrary application info.
|false
|`metrics`
|Shows ``metrics'' information for the current application.
|true
|`mappings`
|Displays a collated list of all `@RequestMapping` paths.
|true
|`shutdown`
|Allows the application to be gracefully shutdown (not enabled by default).
|true
|`trace`
|Displays trace information (by default the last few HTTP requests).
|true
|===
NOTE: Depending on how an endpoint is exposed, the `sensitive` parameter may be used as
a security hint. For example, sensitive endpoints will require a username/password when
they are accessed over HTTP (or simply disabled if web security is not enabled).
[[production-ready-customizing-endpoints]]
=== Customizing endpoints
Endpoints can be customized using Spring properties. You can change if an endpoint is
`enabled`, if it is considered `sensitive` and even its `id`.
For example, here is an `application.properties` that changes the sensitivity and id
of the `beans` endpoint and also enables `shutdown`.
[indent=0]
----
endpoints.beans.id=springbeans
endpoints.beans.sensitive=false
endpoints.shutdown.enabled=true
----
NOTE: The prefix "`endpoints` + `.` + `name`" is used to uniquely identify the endpoint
that is being configured.
[[production-ready-health]]
=== Custom health information
The default information exposed by the `health` endpoint is a simple ``OK'' message. It
is often useful to perform some additional health checks, for example you might check
that a database connection works, or that a remote REST endpoint is functioning.
To provide custom health information you can register a Spring bean that implements the
{sc-spring-boot-actuator}/health/HealthIndicator.{sc-ext}[`HealthIndicator`] interface.
[source,java,indent=0]
----
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class MyHealth implements HealthIndicator<String> {
@Override
public String health() {
// perform some specific health check
return ...
}
}
----
Spring Boot also provides a
{sc-spring-boot-actuator}/health/SimpleHealthIndicator/{sc-ext}[`SimpleHealthIndicator`]
implementation that attempts a simple database test.
[[production-ready-application-info]]
=== Custom application info information
You can customize the data exposed by the `info` endpoint by settings `info.*` Spring
properties. All `Environment` properties under the info key will be automatically
exposed. For example, you could add the following to your `application.properties`:
[indent=0]
----
info.app.name: MyService
info.app.description: My awesome service
info.app.version: 1.0.0
----
If you are using Maven, you can automatically expand info properties from the Maven
project using resource filtering. In your `pom.xml` you have (inside the `<build/>`
element):
[source,xml,indent=0]
----
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
----
You can then refer to your Maven ``project properties'' via placeholders, e.g.
[indent=0]
----
project.artifactId: myproject
project.name: Demo
project.version: X.X.X.X
project.description: Demo project for info endpoint
info.build.artifact: ${project.artifactId}
info.build.name: ${project.name}
info.build.description: ${project.description}
info.build.version: ${project.version}
----
NOTE: In the above example we used `project.*` to set some values to be used as
fallbacks if the Maven resource filtering has not been switched on for some reason.
[[production-ready-git-commit-information]]
==== Git commit information
Another useful feature of the `info` endpoint is its ability to publish information
about the state of your `git` source code repository when the project was built. If a
`git.properties` file is contained in your jar the `git.branch` and `git.commit`
properties will be loaded.
For Maven users the `spring-boot-starter-parent` POM includes a pre-configured plugin to
generate a `git.properties` file. Simply add the following declaration to your POM:
[source,xml,indent=0]
----
<build>
<plugins>
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
</plugin>
</plugins>
</build>
----
A similar https://github.com/ajoberstar/gradle-git[`gradle-git`] plugin is also available
for Gradle users, although a little more work is required to generate the properties file.
[[production-ready-monitoring]]
== Monitoring and management over HTTP
If you are developing a Spring MVC application, Spring Boot Actuator will auto-configure
all non-sensitive endpoints to be exposed over HTTP. The default convention it to use the
`id` of the endpoint as the URL path. For example, `health` is exposed as `/health`.
[[production-ready-sensitive-endpoints]]
=== Exposing sensitive endpoints
If you use ``Spring Security'' sensitive endpoints will also be exposed over HTTP. By
default ``basic'' authentication will be used with the username `user` and a generated
password.
TIP: Generated passwords are logged as the application starts. Search for ``Using default
password for application endpoints''.
You can use Spring properties to change the username and passsword and to change the
security role required to access the endpoints. For example, you might set the following
in your `application.properties`:
[indent=0]
----
security.user.name=admin
security.user.password=secret
management.security.role=SUPERUSER
----
[[production-ready-customizing-management-server-context-path]]
=== Customizing the management server context path
Sometimes it is useful to group all management endpoints under a single path. For example,
your application might already use `/info` for another purpose. You can use the
`management.contextPath` property to set a prefix for your manangement endpoint:
[indent=0]
----
management.contextpath=/manage
----
The `application.properties` example above will change the endpoint from `/{id}` to
`/manage/{id}` (e.g. `/manage/info`).
[[production-ready-customizing-management-server-port]]
=== Customizing the management server port
Exposing management endpoints using the default HTTP port is a sensible choice for cloud
based deployments. If, however, your application runs inside your own data center you
may prefer to expose endpoints using a different HTTP port.
The `management.port` property can be used to change the HTTP port. Since your management
port is often protected by a firewall, and not exposed to the public, you might also
want to disable management security:
[indent=0]
----
management.port=8081
management.security.enabled=false
----
[[production-ready-customizing-management-server-address]]
=== Customizing the management server address
You can customize the address that the management endpoints are available on by
setting the `management.security.address` property. This can be useful if you want to
listen only on an internal or ops-facing network, or to only listen for connections from
`localhost`.
NOTE: You can only listen on a different address if the port is different to the
main server port.
Here is an example `application.properties` that will not allow remote management
connections:
[indent=0]
----
management.port=8081
management.address=127.0.0.1
----
[[production-ready-disabling-http-endpoints]]
=== Disabling HTTP endpoints
If you don't want to expose endpoints over HTTP you can set the management port to `-1`:
[indent=0]
----
management.port=-1
----
[[production-ready-jmx]]
== Monitoring and management over JMX
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage
applications. By default Spring Boot will expose management endpoints as JMX MBeans
under the `org.springframework.boot` domain.
[[production-ready-custom-mbean-names]]
=== Customizing MBean names
The name of the MBean is usually generated from the `id` of the endpoint. For example
the `health` endpoint is exposed as `org.springframework.boot/Endpoint/HealthEndpoint`.
If your application contains more than one Spring `ApplicationContext` you may find that
names clash. To solve this problem you can set the `endpoints.jmx.uniqueNames` property
to `true` so that MBean names are always unique.
You can also customize the JMX domain under which endpoints are exposed. Here is an
example `application.properties`:
[indent=0]
----
endpoints.jmx.domain=myapp
endpoints.jmx.uniqueNames=true
----
[[production-ready-disable-jmx-endpoints]]
=== Disabling JMX endpoints
If you don't want to expose endpoints over JMX you can set the `spring.jmx.enabled`
property to `false`:
[indent=0]
----
spring.jmx.enabled=false
----
[[production-ready-jolokia]]
=== Using Jolokia for JMX over HTTP
Jolokia is a JMX-HTTP bridge giving an alternative method of accessing JMX beans. To
use Jolokia, simply include a dependency to `org.jolokia:jolokia-core`. For example,
using Maven you you add the following:
[source,xml,indent=0]
----
<dependency>
<groupId>org.jolokia</groupId>
<artifactId>jolokia-core</artifactId>
</dependency>
----
Jolokia can then be accessed using `/jolokia` on your management HTTP server.
[[production-ready-customizing-jolokia]]
==== Customizing Jolokia
Jolokia has a number of settings that you would traditionally configure using servlet
parameters. With Spring Boot you can use your `application.properties`, simply prefix the
parameter with `jolokia.config.`:
[indent=0]
----
jolokia.config.debug=true
----
[[production-ready-disabling-jolokia]]
==== Disabling Jolokia
If you are using Jolokia but you don't want Spring Boot to configure it, simply set the
`endpoints.jolokia.enabled` property to `false`:
[indent=0]
----
jolokia.config.enabled=false
----
[[production-ready-remote-shell]]
== Monitoring and management using a remote shell
Spring Boot supports an integrated Java shell called ``CRaSH''. You can use CRaSH to
`ssh` or `telnet` into your running application. To enable remote shell support add a
dependency to `spring-boot-starter-shell-remote`:
[source,xml,indent=0]
----
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-shell-remote</artifactId>
</dependency>
----
TIP: If you want to also enable telnet access your will additionally need a dependency
on `org.crsh:crsh.shell.telnet`.
[[production-ready-connecting-to-the-remote-shell]]
=== Connecting to the remote shell
By default the remote shell will listen for connections on port `2000`. The default user
is `user` and the default password will be randomly generated and displayed in the log
output, you should see a message like this:
[indent=0]
----
Using default password for shell access: ec03e16c-4cf4-49ee-b745-7c8255c1dd7e
----
Linux and OSX users can use `ssh` to connect to the remote shell, Windows users can
download and install http://www.putty.org/[PuTTY].
[indent=0,subs="attributes"]
----
$ ssh -p 2000 user@localhost
user@localhost's password:
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v{spring-boot-version}) on myhost
----
Type `help` for a list of commands. Spring boot provides `metrics`, `beans` and
`autoconfig` commands. You can also use the `jmx` command to query endpoint data:
[indent=0]
----
jmx find -p org.springframework.boot:type=Endpoint,name=healthEndpoint | jmx get Data
----
[[production-ready-remote-shell-credentials]]
==== Remote shell credentials
You can use the `shell.auth.simple.username` and `shell.auth.simple.password` properties
to configure custom connection credentials. It is also possible to use a
``Spring Security'' `AuthenticationManager` to handle login duties. See the
{dc-spring-boot-actuator}/autoconfigure/CrshAutoConfiguration.{dc-ext}[`CrshAutoConfiguration`]
and {dc-spring-boot-actuator}/autoconfigure/ShellProperties.{dc-ext}[`ShellProperties`]
Javadoc for full details.
[[production-ready-extending-the-remote-shell]]
=== Extending the remote shell
The remote shell can be extended in a number of interesting ways.
[[production-ready-remote-commands]]
==== Remote shell commands
You can write additional shell commands using Groovy or Java (see the CRaSH documentation
for details). By default Spring Boot will search for commands in the following locations:
* `classpath*:/commands/**`
* `classpath*:/crash/commands/**`
TIP: You can change the search path by settings a `shell.commandpathpatterns` property.
Here is a simple ``hello world'' command that could be loaded from
`src/main/resources/commands/Hello.groovy`
[source,groovy,indent=0]
----
package commands
import org.springframework.boot.actuate.endpoint.BeansEndpoint
class hello {
@Usage("Say Hello")
@Command
def main(InvocationContext context) {
return "Hello"
}
}
----
Spring Boot adds some additional attributes to `InvocationContext` that you can access
from your command:
[cols="2,3"]
|===
| Attribute Name | Description
|`spring.boot.version`
|The version of Spring Boot
|`spring.version`
|The version of the core Spring Framework
|`spring.beanFactory`
|Access to the Spring `BeanFactory`
|===
[[production-ready-remote-shell-plugins]]
==== Remote shell plugins
In addition to new commands, it is also possible to extend other CRaSH shell features.
All Spring Beans that extends `org.crsh.plugin.CRaSHPlugin` will be automatically
registered with the shell.
For more information please refer to the http://www.crashub.org/[CRaSH reference
documentation].
[[production-ready-metrics]]
== Metrics
Spring Boot Actuator includes a metrics service with ``gauge'' and ``counter'' support.
A ``gauge'' records a single value; and a ``counter'' records a delta (an increment or
decrement). Metrics for all HTTP requests are automatically recorded, so if you hit the
`metrics` endpoint should should see a response similar to this:
[source,json,indent=0]
----
{
"counter.status.200.root": 20,
"counter.status.200.metrics": 3,
"counter.status.401.root": 4,
"gauge.response.root": 2,
"gauge.response.metrics": 3,
"mem": 466944,
"mem.free": 410117,
"processors": 8
}
----
Here we can see basic `memory` and `processor` information along with some HTTP metrics.
In this instance the `root` (``/'') and `/metrics` URLs have returned `HTTP 200` responses
`20` and `3` times respectively. It also appears that the `root` URL returned `HTTP 401`
(unauthorized) `4` times.
The `gauge` shows the last response time for a request. So the last request to `root` took
`2ms` to respond and the last to `/metrics` took `3ms`.
NOTE: In this example we are actually accessing the endpoint over HTTP using the
`/metrics` URL, this explains why `metrics` appears in the response.
[[production-ready-recording-metrics]]
=== Recording your own metrics
To record your own metrics inject a
{sc-spring-boot-actuator}/metrics/CounterService.{sc-ext}[`CounterService`] and/or
{sc-spring-boot-actuator}/metrics/GaugeService.{sc-ext}[`GaugeService`] into
your bean. The `CounterService` exposes `increment`, `decrement` and `reset` methods; the
`GaugeService` provides a `submit` method.
Here is a simple example that counts the number of times that a method is invoked:
[source,java,indent=0]
----
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.actuate.metrics.CounterService;
import org.springframework.stereotype.Service;
@Service
public class MyService {
private final CounterService counterService;
@Autowired
public MyService(CounterService counterService) {
this.counterService = counterService;
}
public void exampleMethod() {
this.counterService.increment("services.system.myservice.invoked");
}
}
----
TIP: You can use any string as a metric name but you following guidelines of your chosen
store/graphing technology. Some good guidelines for Graphite are available on
http://matt.aimonetti.net/posts/2013/06/26/practical-guide-to-graphite-monitoring/[Matt Aimonetti's Blog].
[[production-ready-metric-repositories]]
=== Metric repositories
Metric service implementations are usually bound to a
{sc-spring-boot-actuator}/metrics/repository/MetricRepository.{sc-ext}[`MetricRepository`].
A `MetricRepository` is responsible for storing and retrieving metric information. Spring
Boot provides an `InMemoryMessageRespository` and a `RedisMetricRepository` out of the
box (the in-memory repository is the default) but you can also write your own. The
`MetricRepository` interface is actually composed of higher level `MetricReader` and
`MetricWriter` interfaces. For full details refer to the
{dc-spring-boot-actuator}/metrics/repository/MetricRepository.{dc-ext}[Javadoc].
[[production-ready-code-hale-metrics]]
=== Coda Hale Metrics
User of the http://metrics.codahale.com/[Coda Hale ``Metrics'' library] will automatically
find that Spring Boot metrics are published to `com.codahale.metrics.MetricRegistry`. A
default `com.codahale.metrics.MetricRegistry` Spring bean will be created when you declare
a dependency to the `com.codahale.metrics:metrics-core` library; you can also register you
own `@Bean` instance if you need customizations.
Users can create Coda Hale metrics by prefixing their metric names with the appropriate
type (e.g. `histogram.*`, `meter.*`).
[[production-ready-metrics-message-channel-integration]]
=== Message channel integration
If the ``Spring Messaging'' jar is on your classpath a `MessageChannel` called
`metricsChannel` is automatically created (unless one already exists). All metric update
events are additionally published as ``messages'' on that channel. Additional analysis or
actions can be taken by clients subscribing to that channel.
[[production-ready-auditing]]
== Auditing
Spring Boot Actuator has a flexible audit framework that will publish events once Spring
Security is in play (``authentication success'', ``failure'' and ``access denied''
exceptions by default). This can be very useful for reporting, and also to implement a
lock-out policy based on authentication failures.
You can also choose to use the audit services for your own business events. To do that
you can either inject the existing `AuditEventRepository` into your own components and
use that directly, or you can simply publish `AuditApplicationEvent` via the Spring
`ApplicationEventPublisher` (using `ApplicationEventPublisherAware`).
[[production-ready-tracing]]
== Tracing
Tracing is automatically enable for all HTTP requests. You can view the `trace` endpoint
and obtain basic information about the last few requests:
[source,json,indent=0]
----
[{
"timestamp": 1394343677415,
"info": {
"method": "GET",
"path": "/trace",
"headers": {
"request": {
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"Connection": "keep-alive",
"Accept-Encoding": "gzip, deflate",
"User-Agent": "Mozilla/5.0 Gecko/Firefox",
"Accept-Language": "en-US,en;q=0.5",
"Cookie": "_ga=GA1.1.827067509.1390890128; ..."
"Authorization": "Basic ...",
"Host": "localhost:8080"
},
"response": {
"Strict-Transport-Security": "max-age=31536000 ; includeSubDomains",
"X-Application-Context": "application:8080",
"Content-Type": "application/json;charset=UTF-8",
"status": "200"
}
}
}
},{
"timestamp": 1394343684465,
...
}]
----
[[production-ready-custom-tracing]]
=== Custom tracing
If you need to trace additional events you can inject a
{sc-spring-boot-actuator}/trace/TraceRepository.{sc-ext}[`TraceRepository`] into your
Spring Beans. The `add` method accepts a single `Map` structure that will be converted to
JSON and logged.
By default an `InMemoryTraceRepository` will be used that stores the last 100 events. You
can define your own instance of the `InMemoryTraceRepository` bean if you need to expand
the capacity. You can also create your own alternative `TraceRepository` implementation
if needed.
[[production-ready-error-handling]]
== Error Handling
Spring Boot Actuator provides an `/error` mapping by default that handles all errors in a
sensible way. If you want more specific error pages for some conditions, the embedded
servlet containers support a uniform Java DSL for customizing the error handling.
[[production-ready-whats-next]]
== What to read next
If you want to explore some of the concepts discussed in this chapter, you can take a
look at the actuator {github-code}/spring-boot-samples[sample applications]. You also
might want to read about graphing tools such as http://graphite.wikidot.com/[Graphite].
Otherwise, you can continue on, to read about Spring Boot's
<<build-tool-plugins.adoc#build-tool-plugins, ``build tool plugins''>>.

323
spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc Normal file
View File

@ -0,0 +1,323 @@
[[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.

1611
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

597
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc Normal file
View File

@ -0,0 +1,597 @@
[[using-boot]]
= Using Spring Boot
[partintro]
--
This section goes into more detail about how you should use Spring Boot. It covers topics
such as build systems, auto-configuration and run/deployment options. We also cover some
Spring Boot ``best practices''. Although there is nothing particularly special about
Spring Boot (it is just another library that you can consume). There are a few
recommendations that, when followed, will make your development process just a
little easier.
If you're just starting out with Spring Boot, you should probably read the
``<<getting-started.adoc#getting-started, Getting Started>>'' guide before diving into
this section.
--
[[using-boot-build-systems]]
== Build systems
It is strongly recommended that you choose a build system that supports _dependency
management_, and one that can consume artifacts published to the ``Maven Central''
repository. We would recommend that you choose Maven or Gradle. It is possible to get
Spring Boot to work with other build systems (Ant for example), but they will not be
particularly well supported.
[[using-boot-maven]]
=== Maven
Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible
defaults. The parent project provides the following features:
* Java 1.6 as the default compiler level.
* UTF-8 source encoding.
* A Dependency Management section, allowing you to omit `<version>` tags for common
dependencies.
* Generally useful test dependencies (http://junit.org/[JUnit],
https://code.google.com/p/hamcrest/[Hamcrest],
https://code.google.com/p/mockito/[Mockito]).
* Sensible https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html[resource filtering].
* Sensible plugin configuration (http://mojo.codehaus.org/exec-maven-plugin/[exec plugin],
http://maven.apache.org/surefire/maven-surefire-plugin/[surefire],
https://github.com/ktoso/maven-git-commit-id-plugin[Git commit ID],
http://maven.apache.org/plugins/maven-shade-plugin/[shade]).
[[using-boot-maven-parent-pom]]
==== Inheriting the starter parent
To configure your project to inherit from the `spring-boot-starter-parent` simply set
the `parent`:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<!-- Inherit defaults from Spring Boot -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
</parent>
----
NOTE: You should only need to specify the Spring Boot version number on this dependency.
if you import additional starters, you can safely omit the version number.
[[using-boot-maven-your-own-parent]]
==== Using your own parent POM
If you don't want to use the Spring Boot starter parent, you can use your own and still
keep the benefit of the dependency management (but not the plugin management) using a
`scope=import` dependency:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<dependencyManagement>
<dependencies>
<dependency>
<!-- Import dependency management from Spring Boot -->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
----
[[using-boot-maven-java-version]]
==== Changing the Java version
The `spring-boot-starter-parent` chooses fairly conservative Java compatibility. If you
want to follow our recommendation and use a later Java version you can add a
`java.version` property:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<properties>
<java.version>1.8</java.version>
</properties>
----
[[using-boot-maven-plugin]]
==== Using the Spring Boot Maven plugin
Spring Boot includes a <<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>>
that can package the project as an executable jar. Add the plugin to your `<plugins>`
section if you want to use it:
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
----
NOTE: You only need to add the plugin, there is no need for to configure it unless you
want to change the settings defined in the parent.
[[using-boot-gradle]]
=== Gradle
Gradle users can directly import ``starter POMs'' in their `dependencies` section. Unlike
Maven, there is no ``super parent'' to import.
[source,groovy,indent=0,subs="attributes"]
----
apply plugin: 'java'
repositories { mavenCentral() }
dependencies {
compile("org.springframework.boot:spring-boot-starter-web:{spring-boot-version}")
}
----
The <<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, `spring-boot-gradle-plugin`>>
is also available and provides tasks to create executable jars and run projects from
source. It also adds a `ResolutionStrategy` that enables you to omit the version number
for ``blessed'' dependencies:
[source,groovy,indent=0,subs="attributes"]
----
buildscript {
repositories { mavenCentral() }
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}")
}
}
apply plugin: 'java'
apply plugin: 'spring-boot'
repositories { mavenCentral() }
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
}
----
[[using-boot-ant]]
=== Ant
It is possible to build a Spring Boot project using Apache Ant, however, no special
support or plugins are provided. Ant scripts can use the Ivy dependency system to import
starter POMs.
See the ``<<howto.adoc#howto-build-an-executable-archive-with-ant>>'' ``How-to'' for more
complete instructions.
[[using-boot-starter-poms]]
=== Starter POMs
Starter POMs are a set of convenient dependency descriptors that you can include in your
application. You get a one-stop-shop for all the Spring and related technology that you
need, without having to hunt through sample code and copy paste loads of dependency
descriptors. For example, if you want to get started using Spring and JPA for database
access, just include the `spring-boot-starter-data-jpa` dependency in your project, and
you are good to go.
The starters contain a lot of the dependencies that you need to get a project up and
running quickly and with a consistent, supported set of managed transitive dependencies.
.What's in a name
****
All starters follow a similar naming pattern; `spring-boot-starter-*`, where `*` is
a particular type of application. This naming structure is intended to help when you need
to find a starter. The Maven integration in many IDEs allow you to search dependencies by
name. For example, with the appropriate Eclipse or STS plugin installed, you can simply
hit `ctrl-space` in the POM editor and type ''spring-boot-starter'' for a complete list.
****
The following application starters are provided by Spring Boot under the
`org.springframework.boot` group:
.Spring Boot application starters
|===
| Name | Description
|`spring-boot-starter`
|The core Spring Boot starter, including auto-configuration support, logging and YAML.
|`spring-boot-starter-amqp`
|Support for the ``Advanced Message Queuing Protocol'' via `spring-rabbit`.
|`spring-boot-starter-aop`
|Full AOP programming support including `spring-aop` and AspectJ.
|`spring-boot-starter-batch`
|Support for ``Spring Batch'' including HSQLDB database.
|`spring-boot-starter-data-jpa`
|Full support for the ``Java Persistence API'' including `spring-data-jpa`, `spring-orm`
and Hibernate.
|`spring-boot-starter-data-mongodb`
|Support for the MongoDB NoSQL Database, including `spring-data-mongodb`.
|`spring-boot-starter-data-rest`
|Support for exposing Spring Data repositories over REST via `spring-data-rest-webmvc`.
|`spring-boot-starter-integration`
|Support for common `spring-integration` modules.
|`spring-boot-starter-jdbc`
|JDBC Database support.
|`spring-boot-starter-mobile`
|Support for `spring-mobile`
|`spring-boot-starter-redis`
|Support for the REDIS key-value data store, including `spring-redis`.
|`spring-boot-starter-security`
|Support for `spring-security`.
|`spring-boot-starter-test`
|Support for common test dependencies, including JUnit, Hamcrest and Mockito along with
the `spring-test` module.
|`spring-boot-starter-thymeleaf`
|Support for the Thymeleaf templating engine, including integration with Spring.
|`spring-boot-starter-web`
|Support for full-stack web development, including Tomcat and `spring-webmvc`.
|`spring-boot-starter-websocket`
|Support for websocket development with Tomcat.
|===
In addition to the application starters, the following starters can be used to
add ``<<production-ready-features.adoc#production-ready, production ready>>'' features.
.Spring Boot production ready starters
|===
| Name | Description
|`spring-boot-starter-actuator`
|Adds production ready features such as metrics and monitoring.
|`spring-boot-starter-shell-remote`
|Adds remote `ssh` shell support.
|===
Finally, Spring Boot includes some starters that can be used if you want to exclude or
swap specific technical facets.
.Spring Boot technical starters
|===
| Name | Description
|`spring-boot-starter-jetty`
|Imports the Jetty HTTP engine (to be used as an alternative to Tomcat)
|`spring-boot-starter-log4j`
|Support the Log4J looggin framework
|`spring-boot-starter-logging`
|Import Spring Boot's default logging framework (Logback).
|`spring-boot-starter-tomcat`
|Import Spring Boot's default HTTP engine (Tomcat).
|===
[[using-boot-structuring-your-code]]
== Structuring your code
Spring Boot does not require any specific code layout to work, however, there are some
best practices that help.
[[using-boot-using-the-default-package]]
=== Using the ``default'' package
When a class doesn't include a `package` declaration it is considered to be in the
``default package''. The use of the ``default package'' is generally discouraged, and
should be avoided. It can cause particular problems for Spring Boot applications that
use `@ComponentScan` or `@EntityScan` annotations, since every class from every jar,
will be read.
TIP: We recommend that you use the follow Java's recommended package naming conventions
and use a reversed domain name (for example, `com.example.project`).
[[using-boot-locating-the-main-class]]
=== Locating the main application class
We generally recommend that you locate your main application class in a root package
above other classes. The `@EnableAutoConfiguration` annotation is often placed on your
main class, and it implicitly defines a base ``search package'' for certain items. For
example, if you are writing a JPA application, the package of the
`@EnableAutoConfiguration` annotated class will be used to search for `@Entity` items.
Using a root package also allows the `@ComponentScan` annotation to be used without
needing to specify a `basePackage` attribute.
Here is a typical layout:
[indent=0]
----
com
+- example
+- myproject
+- Application.java
|
+- domain
| +- Customer.java
| +- CustomerRepository.java
|
+- service
| +- CustomerService.java
|
+- web
+- CustomerController.java
----
The `Application.java` file would declare the `main` method, along with the basic
`@Configuration`.
[source,java,indent=0]
----
package com.example.myproject;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableAutoConfiguration
@ComponentScan
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
[[using-boot-configuration-classes]]
== Configuration classes
Spring Boot favors Java-based configuration. Although it is possible to call
`SpringApplication.run()` with an XML source, we generally recommend that your primary
source is a `@Configuration` class. Usually the class that defines the `main` method
is also a good candidate as the primary `@Configuration`.
TIP: Many Spring configuration examples have been published on the Internet that use XML
configuration. Always try to use the equivalent Java-base configuration if possible.
Searching for `enable*` annotations can be a good starting point.
[[using-boot-importing-configuration]]
=== Importing additional configuration classes
You don't need to put all your `@Configuration` into a single class. The `@Import`
annotation can be used to import additional configuration classes. Alternatively, you
can use `@ComponentScan` to automatically pickup all Spring components, including
`@Configuration` classes.
[[using-boot-importing-xml-configuration]]
=== Importing XML configuration
If you absolutely must use XML based configuration, we recommend that you still start
with a `@Configuration` class. You can then use an additional `@ImportResource`
annotation to load XML configuration files.
[[using-boot-auto-configuration]]
== Auto-configuration
Spring Boot auto-configuration attempts to automatically configure your Spring
application based on the jar dependencies that you have added. For example, If
`HSQLDB` is on your classpath, and you have not manually configured any database
connection beans, then we will auto-configure an in-memory database.
You need to opt-in to auto-configuration by adding the `@EnableAutoConfiguration`
annotation to one of your `@Configuration` classes.
TIP: You should only ever add one `@EnableAutoConfiguration` annotation. We generally
recommend that you add it to your primary `@Configuration` class.
[[using-boot-replacing-auto-configuration]]
=== Gradually replacing auto-configuration
Auto-configuration is noninvasive, at any point you can start to define your own
configuration to replace specific parts of the auto-configuration. For example, if
you add your own `DataSource` bean, the default embedded database support will back away.
If you need to find out what auto-configuration is currently being applied, and why,
starting your application with the `--debug` switch. This will log an auto-configuration
report to the console.
[[using-boot-disabling-specific-auto-configutation]]
=== Disabling specific auto-configuration
If you find that specific auto-configure classes are being applied that you don't want,
you can use the exclude attribute of `@EnableAutoConfiguration` to disable them.
[source,java,indent=0]
----
import org.springframework.boot.autoconfigure.*;
import org.springframework.boot.autoconfigure.jdbc.*;
import org.springframework.context.annotation.*;
@Configuration
@EnableAutoConfiguration(exclude={EmbeddedDatabaseConfiguration.class})
public class MyConfiguration {
}
----
[[using-boot-spring-beans-and-dependency-injection]]
== Spring Beans and dependency injection
You are free to use any the standard Spring Framework techniques to defines your beans
and their injected dependencies. For simplicity, we often find that using `@ComponentScan`
to find your beans, in combination with `@Autowired` constructor injection works well.
If you structure your code as suggested above (locating your application class in a root
package), you can add `@ComponentScan` without any arguments. All of your application
components (`@Component`, `@Service`, `@Repoistory`, `@Controller` etc.) will be
automatically registered as Spring Beans.
Here is an example `@Service` Bean that uses constructor injection to obtain a
required `RiskAssessor` bean.
[source,java,indent=0]
----
package com.example.service;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class DatabaseAccountService implements AccountService {
private final RiskAssessor riskAssessor;
@Autowired
public DatabaseAccountService(RiskAssessor riskAssessor) {
this.riskAssessor = riskAssessor;
}
// ...
}
----
TIP: Notice how using constructor injection allows the `riskAssessor` field to be marked
as `final`, indicating that it cannot be subsequently changed.
[[using-boot-running-your-application]]
== Running your application
One of the biggest advantages of packaging your application as jar and using an embedded
HTTP server is that you can run your application as you would any other. Debugging Spring
Boot applications is also easy; you don't need any special IDE plugins or extensions.
NOTE: This section only covers jar based packaging, If you choose to package your
application as a war file you should refer to your server and IDE documentation.
[[using-boot-running-from-an-ide]]
=== Running from an IDE
You can run a Spring Boot application from your IDE as a simple Java application, however,
first you will need to import your project. Import steps will vary depending on your IDE
and build system. Most IDEs can import Maven projects directly, for example Eclipse users
can select `Import...` -> `Existing Maven Projects` from the `File` menu.
If you can't directly import your project into your IDE, you may be able to generate IDE
meta-data using a build plugin. Maven includes plugins for
http://maven.apache.org/plugins/maven-eclipse-plugin/[Eclipse] and
http://maven.apache.org/plugins/maven-idea-plugin/[IDEA]; Gradle offers plugins
for http://www.gradle.org/docs/current/userguide/ide_support.html[various IDEs].
TIP: If you accidentally run a web application twice you will see a ``Port already in
use'' error. STS users can use the `Relauch` button rather than `Run` to ensure that
any existing instance is closed.
[[using-boot-running-as-a-packaged-application]]
=== Running as a packaged application
If you use the Spring Boot Maven or Gradle plugins to create an executable jar you can
run your application using `java -jar`. For example:
[indent=0,subs="attributes"]
----
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
----
It is also possible to run a packaged application with remote debugging support enabled.
This allows you to attach a debugger to your packaged application:
[indent=0,subs="attributes"]
----
$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \
-jar target/myproject-0.0.1-SNAPSHOT.jar
----
[[using-boot-running-with-the-maven-plugin]]
=== Using the Maven plugin
The Spring Boot Maven plugin includes a `run` goal which can be used to quickly compile
and run your application. Applications run in an exploded form, and you can edit
resources for instant ``hot'' reload.
[indent=0,subs="attributes"]
----
$ mvn spring-boot:run
----
[[using-boot-running-with-the-gradle-plugin]]
=== Using the Gradle plugin
The Spring Boot Gradle plugin also includes a `run` goal which can be used to run
your application in an exploded form. The `bootRun` task is added whenever you import
the `spring-boot-plugin`
[indent=0,subs="attributes"]
----
$ gradle bootRun
----
[[using-boot-hot-swapping]]
=== Hot swapping
Since Spring Boot applications are just plain Java application, JVM hot-swapping should
work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can
replace, for a more complete solution the
https://github.com/spring-projects/spring-loaded[Spring Loaded] project, or
http://zeroturnaround.com/software/jrebel/[JRebel] can be used.
See the <<howto.adoc#howto-hotswapping, Hot swapping ``How-to''>> section for details.
[[using-boot-packaging-for-production]]
== Packaging your application for production
Executable jars can be used for production deployment. As they are self contained, they
are also ideally suited for cloud-based deployment.
For additional ``production ready'' features, such as health, auditing and metric REST
or JMX end-points; consider adding `spring-boot-actuator`. See
``<<production-ready-features.adoc#production-ready>>'' for details.
[[using-boot-whats-next]]
== What to read next
You should now have good understanding of how you can use Spring Boot along with some best
practices that you should follow. You can now go on to learn about specific
``<<spring-boot-features#boot-features, Spring Boot features>>'' in depth, or you
could skip ahead and read about the
``<<production-ready-features#production-ready, production ready>>'' aspects of Spring
Boot.