Phillip Webb
parent
f0bba46d45
commit
992a56957f
|
|
@ -1809,10 +1809,23 @@ support running from the command line with reloading of static files. You can us
|
|||
with an external css/js compiler process if you are writing that code with higher level
|
||||
tools.
|
||||
|
||||
The <<using-spring-boot.adoc#using-boot-devtools,`spring-boot-devtools`>> module is also
|
||||
available with support for fast application restarts and LiveReload.
|
||||
|
||||
|
||||
|
||||
[[howto-reload-thymeleaf-template-content]]
|
||||
=== Reload templates without restarting the container
|
||||
Most of the templating technologies supported by Spring Boot include a configuration
|
||||
option to disable caching (see below for details). If you're using the
|
||||
`spring-boot-devtools` module these properties will be
|
||||
<<using-spring-boot.adoc#using-boot-devtools-property-defaults,automatically configured>>
|
||||
for you at developement time.
|
||||
|
||||
|
||||
|
||||
[[howto-reload-thymeleaf-content]]
|
||||
=== Reload Thymeleaf templates without restarting the container
|
||||
==== Thymeleaf templates
|
||||
If you are using Thymeleaf, then set `spring.thymeleaf.cache` to `false`. See
|
||||
{sc-spring-boot-autoconfigure}/thymeleaf/ThymeleafAutoConfiguration.{sc-ext}[`ThymeleafAutoConfiguration`]
|
||||
for other Thymeleaf customization options.
|
||||
|
|
@ -1820,7 +1833,7 @@ for other Thymeleaf customization options.
|
|||
|
||||
|
||||
[[howto-reload-freemarker-content]]
|
||||
=== Reload FreeMarker templates without restarting the container
|
||||
==== FreeMarker templates
|
||||
If you are using FreeMarker, then set `spring.freemarker.cache` to `false`. See
|
||||
{sc-spring-boot-autoconfigure}/freemarker/FreeMarkerAutoConfiguration.{sc-ext}[`FreeMarkerAutoConfiguration`]
|
||||
for other FreeMarker customization options.
|
||||
|
|
@ -1828,7 +1841,7 @@ for other FreeMarker customization options.
|
|||
|
||||
|
||||
[[howto-reload-groovy-template-content]]
|
||||
=== Reload Groovy templates without restarting the container
|
||||
==== Groovy templates
|
||||
If you are using Groovy templates, then set `spring.groovy.template.cache` to `false`. See
|
||||
{sc-spring-boot-autoconfigure}/groovy/template/GroovyTemplateAutoConfiguration.{sc-ext}[`GroovyTemplateAutoConfiguration`]
|
||||
for other Groovy customization options.
|
||||
|
|
@ -1836,13 +1849,24 @@ for other Groovy customization options.
|
|||
|
||||
|
||||
[[howto-reload-velocity-content]]
|
||||
=== Reload Velocity templates without restarting the container
|
||||
==== Velocity templates
|
||||
If you are using Velocity, then set `spring.velocity.cache` to `false`. See
|
||||
{sc-spring-boot-autoconfigure}/velocity/VelocityAutoConfiguration.{sc-ext}[`VelocityAutoConfiguration`]
|
||||
for other Velocity customization options.
|
||||
|
||||
|
||||
|
||||
[[howto-reload-fast-restart]]
|
||||
=== Fast application restarts
|
||||
The `spring-boot-devtools` module includes support for automatic application restarts.
|
||||
Whilst not as fast a technologies such as http://zeroturnaround.com/software/jrebel/[JRebel]
|
||||
or https://github.com/spring-projects/spring-loaded[Spring Loaded] it's usually
|
||||
significantly faster that a "`cold start`". You should probably give it a try before
|
||||
investigating some of the more complex reload options discussed bellow.
|
||||
|
||||
For more details see the <<using-spring-boot.adoc#using-boot-devtools>> section.
|
||||
|
||||
|
||||
[[howto-reload-java-classes-without-restarting]]
|
||||
=== Reload Java classes without restarting the container
|
||||
Modern IDEs (Eclipse, IDEA, etc.) all support hot swapping of bytecode, so if you make a
|
||||
|
|
|
|||
|
|
@ -22,6 +22,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
|
|||
:sc-spring-boot-autoconfigure: {github-code}/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure
|
||||
:sc-spring-boot-actuator: {github-code}/spring-boot-actuator/src/main/java/org/springframework/boot/actuate
|
||||
:sc-spring-boot-cli: {github-code}/spring-boot-cli/src/main/java/org/springframework/boot/cli
|
||||
:sc-spring-boot-devtools: {github-code}/spring-boot-devtools/src/main/java/org/springframework/boot/devtools
|
||||
:dc-ext: html
|
||||
:dc-root: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/api
|
||||
:dc-spring-boot: {dc-root}/org/springframework/boot
|
||||
|
|
|
|||
|
|
@ -731,11 +731,290 @@ You might also want to use this useful operating system environment variable:
|
|||
=== Hot swapping
|
||||
Since Spring Boot applications are just plain Java applications, 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.
|
||||
replace, for a more complete solution
|
||||
http://zeroturnaround.com/software/jrebel/[JRebel] or the
|
||||
https://github.com/spring-projects/spring-loaded[Spring Loaded] project can be used. The
|
||||
`spring-boot-devtools` module also includes support for quick application restarts.
|
||||
|
||||
See the <<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> section for details.
|
||||
See the <<using-boot-devtools>> section below and the
|
||||
<<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> for details.
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools]]
|
||||
== Developer tools
|
||||
Spring Boot includes an additional set of tools that can make the application
|
||||
development experience a little more pleasant. The `spring-boot-devtools` module can be
|
||||
included in any project to provide additional development-time features. To include
|
||||
devtools support, simply add the module dependency to your build:
|
||||
|
||||
.Maven
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-devtools</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
----
|
||||
|
||||
.Gradle
|
||||
[source,groovy,indent=0,subs="attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile("org.springframework.boot:spring-boot-devtools")
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
NOTE: Developer tools are automatically disabled when running a fully packaged
|
||||
application. If your application is launched using `java -jar` or if it's started using a
|
||||
special classloader, then it is considered a "`production application`".
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-property-defaults]]
|
||||
=== Property defaults
|
||||
Several of the libraries supported by Spring Boot use caches to improve performance. For
|
||||
example, Thymeleaf will cache templates to save repeatedly parsing XML source files.
|
||||
Whilst caching is very beneficial in production, it can be counter productive during
|
||||
development. If you make a change to a template file in your IDE, you'll likely want to
|
||||
immediately see the result.
|
||||
|
||||
Cache options are usually configured by settings in your `application.properties` file.
|
||||
For example, Thymeleaf offers the `spring.thymeleaf.cache` property. Rather than needing
|
||||
to set these properties manually, the `spring-boot-devtools` module will automatically
|
||||
apply sensible development-time configuration.
|
||||
|
||||
TIP: For a complete list of the properties that are applied see
|
||||
{sc-spring-boot-devtools}/autoconfigure/DevToolsPropertyDefaultsPostProcessor.{sc-ext}[DevToolsPropertyDefaultsPostProcessor].
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-restart]]
|
||||
=== Automatic restart
|
||||
Applications that use `spring-boot-devtools` will automatically restart whenever files
|
||||
on the classpath change. This can be a useful feature when working in an IDE as it gives
|
||||
a very fast feedback loop for code changes. By default, any entry on the classpath that
|
||||
points to a folder will be monitored for changes.
|
||||
|
||||
TIP: Automatic restart work very well when used with with LiveReload.
|
||||
<<using-boot-devtools-livereload,See below>> for details.
|
||||
|
||||
.Restart vs Reload
|
||||
****
|
||||
The restart technology provided by Spring Boot works by using two classloaders.
|
||||
Classes that don't change (for example, those from third-party jars) are loaded into a
|
||||
_base_ classloader. Classes that you're actively developing are loaded into a _restart_
|
||||
classloader. When the application is restarted, the _restart_ classloader is thrown away
|
||||
and a new one is created. This approach means that application restarts are typically much
|
||||
faster than "`cold starts`" since the _base_ classloader is already available and
|
||||
populated.
|
||||
|
||||
If you find that restarts aren't quick enough for your applications, you could consider
|
||||
reloading technologies such as http://zeroturnaround.com/software/jrebel/[JRebel] from
|
||||
ZeroTurnaround. These work by rewriting classes as they are loaded to make them more
|
||||
amenable to reloading. https://github.com/spring-projects/spring-loaded[Spring Loaded]
|
||||
provides another option, however it doesn't support as many frameworks and it isn't
|
||||
commercially supported.
|
||||
****
|
||||
|
||||
|
||||
|
||||
==== Excluding resources
|
||||
Certain resources don't necessarily need to trigger a restart when they are changed. For
|
||||
example, Thymeleaf templates can just be edited in-place. By default changing resources
|
||||
in `/META-INF/resources` ,`/resources` ,`/static` ,`/public` or `/templates` will not
|
||||
trigger a restart. If you want to customize these exclusions you can use the
|
||||
`spring.devtools.restart.exclude` property. For example, to exclude only `/static` and
|
||||
`/public` you would set the following:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
spring.devtools.restart.exclude=static/**,public/**
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-restart-disable]]
|
||||
==== Disabling restart
|
||||
If you don't want to use the restart feature you can disable it using the
|
||||
`spring.devtools.restart.enabled` property. In most cases you can set this in your
|
||||
`application.properties` (this will still initialize the restart classloader but it won't
|
||||
watch for file changes).
|
||||
|
||||
If you need to _completely_ disable restart support, for example, because it doesn't work
|
||||
with a specific library, you need to set a `System` property before calling
|
||||
`SpringApplication.run(...)`. For example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
public static void main(String[] args) {
|
||||
System.setProperty("spring.devtools.restart.enabled", "false");
|
||||
SpringApplication.run(MyApp.class, args);
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-restart-triggerfile]]
|
||||
==== Using a trigger file
|
||||
If you work with an IDE that continuously compiles changed files, you might prefer to
|
||||
trigger restarts only at specific times. To do this you can use a "`trigger file`", which
|
||||
is a special file that must be modified when you want to actually trigger a restart check.
|
||||
The trigger file could be updated manually, or via an IDE plugin.
|
||||
|
||||
To use a trigger file use the `spring.devtools.restart.trigger-file` property.
|
||||
|
||||
TIP: You might want to set `spring.devtools.restart.trigger-file` as a
|
||||
<<using-boot-devtools-globalsettings,global setting>> so that all your projects behave
|
||||
in the same way.
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-livereload]]
|
||||
=== LiveReload
|
||||
The `spring-boot-devtools` module includes an embedded LiveReload server that can be used
|
||||
to trigger a browser refresh when a resource is changed. LiveReload browser extensions are
|
||||
freely available for Chrome, Firefox and Safari from
|
||||
http://livereload.com/extensions/[livereload.com].
|
||||
|
||||
If you don't want to start the LiveReload server when your application runs you can set
|
||||
the `spring.devtools.livereload.enabled` property to `false`.
|
||||
|
||||
NOTE: You can only run one LiveReload server at a time, if you start multiple applications
|
||||
from your IDE only the first will have livereload support.
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-globalsettings]]
|
||||
=== Global settings
|
||||
You can configure global devtools settings by adding a file named
|
||||
`.spring-boot-devtools.properties` to your `$HOME` folder (note that the filename starts
|
||||
with "`.`"). Any properties added to this file will apply to _all_ Spring Boot
|
||||
applications on your machine that use devtools. For example, to configure restart to
|
||||
always use a <<using-boot-devtools-restart-triggerfile, trigger file>>, you would add
|
||||
the following:
|
||||
|
||||
.~/.spring-boot-devtools.properties
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
spring.devtools.reload.trigger-file=.reloadtrigger
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-remote]]
|
||||
=== Remote applications
|
||||
The Spring Boot developer tools are not just limited to local development. You can also
|
||||
use several features when running applications remotely. Remote support is opt-in, to
|
||||
enable it you need set a `spring.devtools.remote.password` property. For example:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
spring.devtools.remote.password=mysecret
|
||||
----
|
||||
|
||||
WARNING: Enabling `spring-boot-devtools` on a remote application is a security risk. You
|
||||
should never enable support on a production deployment.
|
||||
|
||||
Remote devtools support is provided in two parts; there is a server side endpoint that
|
||||
accepts connections, and a client application that you run in your IDE. The server
|
||||
component is automatically enabled when the `spring.devtools.remote.password` property
|
||||
is set. The client component must be launched manually.
|
||||
|
||||
|
||||
|
||||
==== Running the remote client application
|
||||
The remote client application is designed to be run from within you IDE. You need to run
|
||||
`org.springframework.boot.devtools.RemoteSpringApplication` using the same classpath as
|
||||
the remote project that you're connecting to. The _non-option_ argument passed to the
|
||||
application should be the remote URL that you are connecting to.
|
||||
|
||||
For example, if you are using Eclipse or STS, and you have a project named `my-app` that
|
||||
you've deployed to Cloud Foundry, you would do the following:
|
||||
|
||||
* Select `Run Configurations...` from the `Run` menu.
|
||||
* Create a new `Java Application` "`launch configuration`".
|
||||
* Browse for the `my-app` project.
|
||||
* Use `org.springframework.boot.devtools.RemoteSpringApplication` as the main class.
|
||||
* Add `+++http://myapp.cfapps.io+++` to the `Program arguments` (or whatever your remote
|
||||
URL is).
|
||||
|
||||
A running remote client will look like this:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
. ____ _ __ _ _
|
||||
/\\ / ___'_ __ _ _(_)_ __ __ _ ___ _ \ \ \ \
|
||||
( ( )\___ | '_ | '_| | '_ \/ _` | | _ \___ _ __ ___| |_ ___ \ \ \ \
|
||||
\\/ ___)| |_)| | | | | || (_| []::::::[] / -_) ' \/ _ \ _/ -_) ) ) ) )
|
||||
' |____| .__|_| |_|_| |_\__, | |_|_\___|_|_|_\___/\__\___|/ / / /
|
||||
=========|_|==============|___/===================================/_/_/_/
|
||||
:: Spring Boot Remote :: {spring-boot-version}
|
||||
|
||||
2015-06-10 18:25:06.632 INFO 14938 --- [ main] o.s.b.devtools.RemoteSpringApplication : Starting RemoteSpringApplication on pwmbp with PID 14938 (/Users/pwebb/projects/spring-boot/code/spring-boot-devtools/target/classes started by pwebb in /Users/pwebb/projects/spring-boot/code/spring-boot-samples/spring-boot-sample-devtools)
|
||||
2015-06-10 18:25:06.671 INFO 14938 --- [ main] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@2a17b7b6: startup date [Wed Jun 10 18:25:06 PDT 2015]; root of context hierarchy
|
||||
2015-06-10 18:25:07.043 WARN 14938 --- [ main] o.s.b.d.r.c.RemoteClientConfiguration : The connection to http://localhost:8080 is insecure. You should use a URL starting with 'https://'.
|
||||
2015-06-10 18:25:07.074 INFO 14938 --- [ main] o.s.b.d.a.OptionalLiveReloadServer : LiveReload server is running on port 35729
|
||||
2015-06-10 18:25:07.130 INFO 14938 --- [ main] o.s.b.devtools.RemoteSpringApplication : Started RemoteSpringApplication in 0.74 seconds (JVM running for 1.105)
|
||||
----
|
||||
|
||||
NOTE: Because the remote client is using the same classpath as the real application it
|
||||
can directly read application properties. This is how the `spring.devtools.remote.password`
|
||||
property is read and passed to the server for authentication.
|
||||
|
||||
TIP: It's always advisable to use `https://` as the connection protocol so that traffic is
|
||||
encrypted and passwords cannot be intercepted.
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-remote-update]]
|
||||
==== Remote update
|
||||
The remote client will monitor your application classpath for changes in the same way as
|
||||
the <<using-boot-devtools-restart,local restart>>. Any updated resource will be pushed
|
||||
to the remote application and _(if required)_ trigger a restart. This can be quite helpful
|
||||
if you are iterating on a feature that uses a cloud service that you don't have locally.
|
||||
Generally remote updates and restarts are much quicker than a full rebuild and deploy
|
||||
cycle.
|
||||
|
||||
NOTE: Files are only monitored when the remote client is running. If you change a file
|
||||
before starting the remote client, it won't be pushed to the remote server.
|
||||
|
||||
|
||||
|
||||
[[using-boot-devtools-remote-debugtunnel]]
|
||||
==== Remote debug tunnel
|
||||
Java remote debugging is useful tool when diagnosing issues on a remote application.
|
||||
Unfortunately, it's not always possible to enable remote debugging when your application
|
||||
is deployed outside of your data center. Remote debugging can also be tricky to setup if
|
||||
you are using a container based technology such as Docker.
|
||||
|
||||
To help work around these limitations, devtools supports tunneling of remote debug traffic
|
||||
over HTTP. The remote client provides a local server on port `8000` that you can attach
|
||||
a remote debugger to. Once a connection is established, debug traffic is sent over HTTP
|
||||
to the remote application. You can use the `spring.devtools.remote.debug.local-port`
|
||||
property if you want to use a different port.
|
||||
|
||||
You'll need to ensure that your remote application is started with remote debugging
|
||||
enabled. Often this can be achieved by configuring `JAVA_OPTS`. For example, with
|
||||
Cloud Foundry you can add the following to your `manifest.yml`:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
---
|
||||
env:
|
||||
JAVA_OPTS: "-Xdebug -Xrunjdwp:server=y,transport=dt_socket,suspend=n"
|
||||
----
|
||||
|
||||
TIP: Notice that you don't need to pass an `address=NNNN` option to `-Xrunjdwp`. If
|
||||
omitted Java will simply pick a random free port.
|
||||
|
||||
NOTE: Debugging a remote service over the Internet can be slow and you might need to
|
||||
increase timeouts in your IDE. For example, in Eclipse you can select `Java` -> `Debug`
|
||||
from `Preferences...` and change the `Debugger timeout (ms)` to a more suitable value
|
||||
(`60000` works well in most situations).
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue