Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve devtools documentation

Browse Source 
Clarify known limitations and document how to use the
`META-INF/spring-devtools.properties` file.

Fixes gh-4235
Closes gh-3316
This commit is contained in:
Phillip Webb
2015-11-13 21:35:15 -08:00
parent 4aaab6c2a1
commit 9a666d3366
1 changed files with 53 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
View File

@@ -965,6 +965,7 @@ NOTE: DevTools relies on the application context's shutdown hook to close it dur
restart. It will not work correctly if you have disabled the shutdown hook (
`SpringApplication.setRegisterShutdownHook(false)`).
[[using-spring-boot-restart-vs-reload]]
.Restart vs Reload
****
The restart technology provided by Spring Boot works by using two classloaders.
@@ -975,12 +976,12 @@ and a new one is created. This approach means that application restarts are typi
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.
If you find that restarts aren't quick enough for your applications, or you encounter
classloading issues, 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.
****
@@ -1052,6 +1053,52 @@ in the same way.
[[using-boot-devtools-customizing-classload]]
==== Customizing the restart classloader
As described in the <<using-spring-boot-restart-vs-reload>> section above, restart
functionality is implemented by using two classloaders. For most applications this
approach works well, however, sometimes in can cause classloading issues.
By default, any open project in your IDE will be loaded using the "`restart`" classloader,
and any regular `.jar` file will be loaded using the "`base`" classloader. If you work on
a multi-module project, and not each module is imported into your IDE, you may need to
customize things. To do this you can create a `META-INF/spring-devtools.properties` file.
The `spring-devtools.properties` file can contain `restart.exclude.` and
`restart.include.` prefixed properties. The `include` elements are items that should be
pulled-up into the "`restart`" classloader, and the `exclude` elements are items that
should be pushed down into the "`base`" classloader. The value of the property is a regex
pattern that will be applied to the classpath.
For example:
[source,properties,indent=0]
----
restart.include.companycommonlibs=/mycorp-common-[\\w-]+\.jar
restart.include.projectcommon=/mycorp-myproj-[\\w-]+\.jar
----
NOTE: All property keys must be unique. As long as a property starts with
`restart.include.` or `restart.exclude.` it will be considered.
TIP: All `META-INF/spring-devtools.properties` from the classpath will be loaded. You can
package files inside your project, or in the libraries that the project consumes.
[[using-boot-devtools-known-restart-limitations]]
==== Known limitations
Restart functionality does not work well with objects that are deserialized using a
standard `ObjectInputStream`. If you need to deserialize data, you may need to use Spring's
`ConfigurableObjectInputStream` in combination with
`Thread.currentThread().getContextClassLoader()`.
Unfortunately, several third-party libraries deserialize without considering the context
classloader. If you find such a problem, you will need to request a fix with the original
authors.
[[using-boot-devtools-livereload]]
=== LiveReload
The `spring-boot-devtools` module includes an embedded LiveReload server that can be used