Basic usage information

Out of the box SpringLoaded should be usable without extra configuration, it has sensible defaults. Trying it out is as simple as:

java -javaagent:<pathto>/springloaded.jar -noverify SomeJavaClass

What is the default behaviour?

Making a type reloadable is quite expensive so not everything the JVM loads goes through the process. When the JVM loads a type it can determine where the class was loaded from - this information is used to make a simple choice. If the class came from a .class file on disk, it is considered a piece of the application and made reloadable. If the class came from inside a zip/jar, it is considered a piece of the infrastructure and not made reloadable. Now, it is sometimes expensive to track down where types have been loaded from so the process for rejecting some infrastructure types is accelerated by considering just the name of the type. The following packages are considered 'infrastructure':

antlr/
org/springsource/loaded/
com/springsource/tcserver/
com/springsource/insight/
groovy/
groovyjarjarantlr/
groovyjarjarasm/
grails/
java/
javassist/
org/codehaus/groovy/
org/apache/
org/springframework/
org/hibernate/
org/hsqldb/
org/aspectj/
org/xml/
org/h2/

If you use one of these packages as your application package prefix, it will not be made reloadable at the moment. An aid in trying to diagnose when this is happening is the explain mode for springloaded, see Configuration Options for more information, but basically specifying this:

java -Dspringloaded=explain -javaagent:<pathto>/springloaded.jar -noverify SomeJavaClass

will cause logging to come out explaining the decision process in springloaded:

Feb 05, 2014 11:00:51 AM org.springsource.loaded.TypeRegistry couldBeReloadable
INFO: WhyNotReloadable? The type org/apache/maven/model/building/ModelBuilder is using a package name 'org/apache/' which is 
     considered infrastructure and types within it are not made reloadable

Once a type is made reloadable the .class file it came from is watched for changes by a file system watcher thread. If there is a change (e.g. your IDE or maven build recompiles the code) the file system watcher kicks springloaded and tells it to load the new version. To see this actually occurring you can turn on the verbose mode for SpringLoaded:

java -Dspringloaded=verbose -javaagent:<pathto>/springloaded.jar -noverify SomeJavaClass

(Beware, verbose mode is very....verbose!)

Watcher Observed last modification time change for /Users/aclement/play/grails10411/jira-reload/target/classes/br/
        com/app/domains/CategoryController.class (lastScanTime=1391628759166)
Watcher Firing file changed event /Users/aclement/play/grails10411/jira-reload/target/classes/br/
        com/app/domains/CategoryController.class
ReloadableType Loading new version of br/com/app/domains/CategoryController, identifying suffix OV1YS1A,
               new data length is 27209bytes