Improve devtools documentation

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

Fixes gh-4235
Closes gh-3316

Author: philwebb

spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

@@ -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