Live Class and Template Reloading

One of the best features of Tapestry is automatic reloading of changed classes and templates. Page and component classes will automatically reload when changed. Likewise, changes to component templates and other related resources will also be picked up immediately. In addition, starting in version 5.2, your service classes will also be reloaded automatically after changes (if you're using Tapestry IoC). Starting in version 5.8.3, you enable multiple classloader mode, which allows smarter page class invalidation.

Contents

Template Reloading

When a template changes, all page instances (as well as the hierarchy of components below them) are discarded and reconstructed with the new template. However, classes are not reloaded in this case.

Class Reloading

On a change to any loaded class from inside a controlled package (or any sub-package of a controlled package), Tapestry will discard all page instances, and discard the class loader.

Persistent field data on the pages will usually not be affected (as it is stored separately, usually in the session). This allows you to make fairly significant changes to a component class even while the application continues to run.

Packages Scanned

Only certain classes are subject to reload. Reloading is based on package name; the packages that are reloaded are derived from the application configuration.

If your root package is org.example.myapp, then only classes in the following packages (and their sub-packages) will be scanned for automatic reloads:

• org.example.myapp.pages
• org.example.myapp.components
• org.example.myapp.mixins
• org.example.myapp.base
• org.example.myapp.services (Tapestry 5.2 and later, with restrictions)

Starting in Tapestry 5.2, live class reloading includes service implementation classes. There are some limitations to this. See Service Implementation Reloading for more details.

File System Only

Reloading of classes and other files applies only to files that are actually on the file system, and not files obtained from JAR files. This is perfect during development, where the files in question are in your local workspace. In a deployed application, you are somewhat subject to the implementation of your servlet container or application server.

Class Loader Issues

Tapestry uses an extra class loader to load page and component classes.

When a change to an underlying Java class file is detected, Tapestry discards the class loader.

You should be careful to not hold any references to Tapestry pages or components in other code, such as Tapestry IoC services. Holding such references can cause significant memory leaks, as they can prevent the class loader from being reclaimed by the garbage collector.

ClassCastExceptions

Tapestry's class loader architecture can sometimes cause a minor problem when you make use of a services layer without interfaces, or if that you pass component instances to objects that are not themselves components.

In such cases you may see ClassCastException errors. This is because the same class name, say org.example.myapp.pages.Start, exists as two different class instances. One class instance is loaded by the web application's default class loader. A second class instance has been loaded and transformed by Tapestry's reloading class loader.

Ordinary classes, such as Tapestry IoC Services, will be loaded by the default class loader and expect instances to be loaded by the same class loader (or a parent).

The solution to this problem is to introduce an interface; the component class should implement the interface, and the service should expect an instance of the interface, rather than a specific type.

It is important that the interface be loaded by the default class loader. It should not be in the pages or components package, but instead be in another package, such as services.

Handling Reloads in your Code

On occasion, you may need to know when invalidations occur, to clear your own cache. For example, if you have a binding that creates new classes, the way PropertyConduitSource does, you need to discard any cached classes or instances when a change is detected in component classes.

You do this by registering a listener with the correct InvalidationEventHub service.

For example, your service may be in the business of creating new classes based on component classes, and keep a cache of those classes:

public class MyServiceImpl implements MyService, InvalidationEventListener
{
  public final Map<String,Class> cache = new ConcurrentHashMap<String,Class>();

  . . .

  public void objectWasInvalidated() { cache.clear(); }
}

Here, the service implementation implements the InvalidationEventListener interface, as well as its service interface. The question is: how does it register for notifications?

In your module, you will want to use a service builder method, such as:

public static MyService buildMyService(@Autobuild MyServiceImpl service, @ComponentClasses InvalidationEventHub hub)
{
  hub.addInvalidationListener(service);

  return service;
}

This is the intent of service builder methods; to do more than just injecting dependencies.

Checking For Updates

The built in InvalidationEventHub services provide notifications of changes to component classes, to component templates, and to component message catalogs. If you wish to check some other resources (for example, files in a directory of the file system or rows in a database table), you should register as an UpdateListener with the UpdateListenerHub service.

Periodically (the frequency is configurable), UpdateListeners are notified that they should check for updates. Typically, UpdateListeners are also InvalidationEventHubs (or provide InvalidationEventHubs), so that other interested parties can be alerted when underlying data changes.

Troubleshooting Live Class Reloading

Quick Checklist

• "Production Mode" must be false (in Tapestry 5.3 and later)
• The class must be one that Tapestry instantiates (a page, component, or mixin class, or a Tapestry IOC service implementation that implements an interface)
• Turn on "Build Automatically" in your IDE, or remember to build manually.
• Turn off JVM hot code swapping, if your servlet container supports it.
• Eclipse: Uncheck the "derived" checkbox for the Target dir (in the Project Explorer view, right click on "target", select properties, uncheck "derived" on the Resource tab)

Some of these issues are described in more detail below.

If Live Class Reloading doesn't work

Production Mode

Starting with Tapestry 5.3, Live Class Reloading only works when not in "Production Mode". Check your application module (usually AppModule.java) to be sure you have:

configuration.add(SymbolConstants.PRODUCTION_MODE, "false");

and that this isn't being overridden to "true" on your application's startup command line.

Build Path Issues

Live Class Reloading can fail if your build path isn't set correctly, and the exact configuration may differ between Maven plugin versions and Eclipse versions. The build process must be set to create classes in a folder which is in the servlet container's classpath.

Live Class Reloading won't work correctly with vanilla Tomcat without some tweaks (see below).

Non-Tapestry filters can interfere with LCR. Try disabling other filters in your web.xml file to see if that helps.

Building Automatically

Although LCR allows you to see changes without restarting your app, you still need to "build" your project (to compile the Java source into byte code). Your IDE can be set to do this automatically every time you save a file. (In Eclipse, this is done using Project > Build Automatically.) Alternatively, you can manually trigger a build after you save a file. (In Eclipse, this is done using Project > Build, or by pressing Control-B.)

Turn off JVM hot code swapping & automatic restarts

Many servlet containers, including Tomcat and Jetty, support various forms of hot code swapping and/or automatic restarts when file changes are detected. These are generally much slower than LCR and usually should be turned off with Tapestry applications. If you're using RunJettyRun plugin for Eclipse, for example, edit your Run Configuration, and on the Jetty tab, click Show Advanced Options and uncheck the Enable Scanner checkbox.

Tomcat Specifics

See these Tomcat-specific hints

If Live Class Reloading works but is slow

If LCR works for you but is slow (more than a second or two), consider the following.

• Be sure your project source files (your workspace in Eclipse, for example), are on a local drive, NOT a network location. Network drives are always slower, and the file system scanning needed for LCR can add a noticable lag if I/O is slow. If you use Maven, be sure to put your local repository (e.g. ~/.m2/repository) on a local drive for similar reasons.

• Java 7 and below: Since LCR adds classes to your PermGen space, you may be running low on PermGen memory (and may eventually get a "java.lang.OutOfMemoryError: PermGen space" error). Try increasing PermGen size with a JVM argument of something like -XX:MaxPermSize=400m. (PermGen settings are not relevant for Java 8 and above.)

[5.8.3+] Multiple Classloader Mode/Smarter Page Class Invalidation

Since Tapestry 5.8.3, you can run Tapestry in multiple classloader mode, which implements smarter page class invalidation in live class reloading. In addition, other caches are also invalidated in smarter way when something changes, avoiding throwing away everything. Multiple classloader mode isn't available when production mode is on.

To enable multiple classloader mode, you need to tapestry.multiple-classloaders symbol to true and run the webapp with production mode disabled. With production mode on, tapestry.multiple-classloaders is ignored.

When multiple classloaders are enabled, when a class in a controlled component, template, message properties file or asset is changed, Tapestry tries to invalidate as few cached objects as possible. This include page instances, processed templates, asset information, property bindings, etc. This is possible by 2 new internal features:

1. A component dependency registry, which gathers and stores information about how component, page, mixin and base classes depend on each other. There are 3 kinds of dependencies: usage (i.e. a component or mixin used in a class), superclass (i.e. one class extending the other) and @InjectPage (i.e. one class injecting a page class using @InjectPage.
2. The usage of multiple classloader instances, organized in a tree, instead of a single one. For example: if a component A is used in pages B and C, when B has its class changed, there's no need to invalidate a cached instance of C since Tapestry knows there's no dependency of B and C. On the other hand, if A is changed, both B and C instances need to be invalidated.

You can find a graph of all known dependencies at a time by going to the /t5dashboard/pagedependencygraph URL of your webapp. You can view the dependencies for one specific page by going to /t5dashboard/ and clicking the page's Structure Info link. Here's one partial example:

How It Works

First of all, when production mode is off and multiple classloaders mode is also off, Tapestry reacts to file (including classes in controlled packages, templates, message properties files and assets) changes in the same way as before and described above in this page: all cached information or objects about classes, templates, message properties files, assets, property bindings, etc is invalidated (i.e. thrown away). The internal services that track changes to these files notify all their listeners that they should invalidate their caches completely.

When multiple classloaders mode is on, these internal services notify their listeners what changed, so they can invalidate just the objects or information that is actually affected by the changes. Sometimes this listeners notify the services that more stuff needs to be invalidated, For example, if one asset is changed and it's associated with a class, the asset service notifies the listeners that that class needs to be invalidated. For example, the component dependency registry, when notified that a given class was invalidated, besides invalidating information about that class, it informs the service that it also needs to invalidates the classes that depend on the changed one. This process repeats until there's no other class to be invalidated.

Additional logging was added so all files found as changed result in log entries. Same for the invalidation chain described in the paragraph above.

Now that it knows the class dependency graph, Tapestry needs to map that into a classloader tree, since each classloader instance can only have one parent. Internally, the framework has one class, PageClassLoaderContext (PCLC or context, for short), that stores all information about one classloader in the tree: the classloader itself, a name, the set of names of the classes beloging to it, the parent PCLC and children PCLCs. When a class is invalidated, the classes in the context are invalidated, then the context itself is invalidated, including its classloader, then the child contexts are recursively invalidated too.

There are 2 special PCLC contexts: the root one, which is never invalidated, and the unknown one, where classes without dependency information go initially.

The PCLC tree is created class by class, starting from pages and then on its dependencies on them in a recursive manner. For each class, if there's no PCLC already containing it, Tapestry checks its dependency list. Its basic algorithm is this:

1. If there are dependencies that belong to a PCLC yet, run the algorithm on it.
2. All the PCLCs of dependencies are gathered.
   1. If there are no PCLCs found, a new one is created with that class and the root context is its parent.
   2. If there is exactly one PCLC found, a new one is created with that class and the found PCLC will be its parent.
   3. If more than one PCLC is found, these PCLCs are merged by creating a new one containing all the classes in the PCLCs. The old PCLCs are invalidated recursively and an event about its invalidation is sent to the listeners. One of them is PageSource, the service that manages, creates and caches page instances, so the merging of PCLCs can cause page invalidation, as keeping these instances could potentially cause ClassCastExceptions later due to class instances belonging to different versions of the same class.

Loading, Storing and Preloading Dependency Information

When a page instance is finished building, it's processed by the component dependency registry, which gathers the dependencies this page has, then the dependencies of its dependencies recursively. The registry doesn't process classes it already has information.

When starting up, Tapestry checks whether a file named tapestryComponentDependencies.json exists in the folder where the webapp is running. If it does, component dependency is loaded from it.

The T5Dashboard page has 2 new buttons related to dependencies, Store dependency information, writes all the dependency information as known at that moment.

Preload dependency information and page classloader contexts goes through all known pages, gathers its dependencies, also doing the same for all the components used directly and indirectly by them, and the preloads page the page classloader contexts, thus avoiding context invalidations when page instances are created. Notice this process won't work if any of the pages or their templates are invalid for any reason.

Caveats

Unfortunately, it wasn't possible to make the multiple classloader mode to work with all situations and code. Some known issues:

1. On Java 9 and later, classes belonging to one classloader cannot call package-private methods of other classes even when both are in the same package. The solution is to change the method visibility to public.
2. If you don't have component dependency information already loaded for a given class, problems, usually in the form of a ClassCastException claiming an object of a given type cannot be assigned to a variable of the same type. The best way to deal with this is to use the T5Dashboard to write the component dependency information to a file and restart the webapp. In some cases, it helps to preload dependency information for all classes.
3. If you start your webapp without component dependency information, page instances may be created and invalidated a few times even when they didn't have any changes due to the page classloader context creation. The solution for this is the same one as the above.
4. When one asset is imported into a class through @Import, the class and the asset are considered associated. When an asset is changed and it's associated with at least one class, the classes associated with it, including pages, are invalidated. If an asset is changed and it's not associated with any class, then multiple classloader mode works the same as single classloader one, invalidating everything.