How You've Changed!

Responding to resource changes in the Eclipse workspace

Summary
Many tools and user interface elements are interested in processing resource changes as they happen. For example, the task list wants to update new or changed markers, the navigator wants to reflect added and deleted resources, and the Java compiler wants to recompile modified Java files. Such notifications are potentially costly to compute, manage and broadcast. The Eclipse Platform resource model includes a series of mechanisms for efficiently notifying clients of resource changes. This article outlines these facilities and gives some examples of their use.

By John Arthorne, OTI
August 23, 2002
Updated November 23, 2004 for Eclipse 3.0

Listeners must implement the IResourceChangeListener interface, and are registered using the method addResourceChangeListener on IWorkspace. It is also important to remove your resource change listener when it is no longer needed, using IWorkspace.removeResourceChangeListener.

During a resource change notification, the workspace is locked to prevent further modification while the notifications are happening. This is necessary to ensure that all listeners are notified of all workspace changes. Otherwise, a change made by one listener would have to be broadcast to all other listeners, easily creating the possibility of an infinite loop. There is a special exception to this rule for the PRE_BUILD and POST_BUILD event types that will be discussed later on.

Before we get into the details, let's start with a simple example that shows how to add and remove a resource change listener:

   IWorkspace workspace = ResourcesPlugin.getWorkspace();
   IResourceChangeListener listener = new IResourceChangeListener() {
      public void resourceChanged(IResourceChangeEvent event) {
         System.out.println("Something changed!");
      }
   };
   workspace.addResourceChangeListener(listener);

   //... some time later one ...
   workspace.removeResourceChangeListener(listener);

   * This method changes resources; these changes will be reported
   * in a subsequent resource change event.

Clients of the resources API are strongly encouraged to follow this nested operation behavior, also called batched changes, for their own high-level operations. This is achieved by wrapping the operation code inside an instance of IWorkspaceRunnable, and passing it to IWorkspace.run(IWorkspaceRunnable). Wrapping high-level operations inside an IWorkspaceRunnable can lead to a substantial performance improvement, because it ensures that only one resource change broadcast occurs, instead of potentially thousands.

Below is an example of an operation that is nested using the IWorkspaceRunnable mechanism. In this case, a single resource change event will be broadcast, indicating that one project and ten files have been created. To keep it simple, progress monitoring and exception handling have been omitted from this example.

   IWorkspace workspace = ResourcesPlugin.getWorkspace();
   final IProject project = workspace.getRoot().getProject("My Project");
   IWorkspaceRunnable operation = new IWorkspaceRunnable() {
      public void run(IProgressMonitor monitor) throws CoreException {
         int fileCount = 10;
         project.create(null);
         project.open(null);
         for (int i = 0; i < fileCount; i++) {
            IFile file = project.getFile("File" + i);
            file.create(null, IResource.NONE, null);
         }
      }
   };
   workspace.run(operation, null);

Since Eclipse 3.0, it is no longer guaranteed that an IWorkspaceRunnable will prevent notifications for the entire duration of an operation. The workspace can now decide to perform notifications during an operation to ensure UI responsiveness. This is particularly important when several workspace modifying operations are running simultaneously. The use of IWorkspaceRunnable is still strongly encouraged, functioning as a strong hint to the workspace that a set of changes is occurring that can be batched. Also in Eclipse 3.0, a background equivant to IWorkspaceRunnable was introduced. WorkspaceJob will batch a set of workspace changes that occur inside a Job running in the background. Read the Concurrency infrastructure documentation for more details on jobs.

A very powerful feature of the resource change infrastructure is that listeners will even be notified of changes that occur outside the workspace API. If some external editor or tool makes changes to resources in the workspace directly from the filesystem, resource change listeners will still receive the same notification describing exactly what changed and how they changed. The drawback is that since most operating systems don't have such a resource change mechanism of their own, the eclipse workspace may not "discover" the change until later on. Specifically, the workspace will not send the notification until someone performs a IResource.refreshLocal operation on a resource subtree that has changed in the filesystem. After the refreshLocal operation, the workspace will send resource change notification to all listeners, describing everything that has changed since the last local refresh.

The contents of a resource change event

Now that we know how to add listeners and when to expect them to be called, let's take a closer look at what these change events look like. The object passed to a resource change listener is an instance of IResourceChangeEvent. The most important bits of information in the event are the event type, and the resource delta. The event type is simply an integer that describes what kind of event occurred. Listeners are typically mainly interested in the POST_CHANGE event type, and that is the one we will focus on here. The resource delta is actually the root of a tree of IResourceDelta objects. The tree of deltas is structured much like the tree of IResource objects that makes up the workspace, so that each delta object corresponds to exactly one resource. The top-most delta object, provided by the event object, corresponds to the IWorkspaceRoot resource obtained by IWorkspace.getRoot. The resource delta hierarchy will include deltas for all affected resources that existed prior to the resource changing operation, and all affected resources that existed after the operation. Think of it as the union of the workspace contents before and after a particular operation, with all unchanged sub-trees pruned out. Each delta object provides the following information:

• The resource it corresponds to.
• The kind of modification (added, removed, or changed).
• The precise nature of the change (the change flags).
• A summary of what markers changed on the resource.
• Deltas for any added, removed, or changed children.

In the case where a resource has moved, the delta for the destination also supplies the path it moved from, and the delta for the source supplies the path it moved to. This allows listeners to accurately track moved resources.

To give an example of the structure of a resource delta, assume we begin with a workspace with the following contents:

Now, say we perform a workspace operation that does all of the following changes:

• Delete "Folder1", which causes deletion of "File1" as well.
• Modify the contents of "File2"
• Create a folder called "NewFolder" inside "Project1"
• Create a file called "NewFile" inside "NewFolder"

It is worth giving a bit more detail about what the delta change flags ( IResourceDelta.getFlags()), are all about. More than one flag may be applicable for a given resource, in which case the flag values are masked together to form a single flag integer. The following table summarizes the different flags and what they signify:

In the interest of making resource change listeners faster, some convenience methods exist on IResourceDelta and IResourceChangeEvent that allow you to do your updates faster. If you are only interested in changes to a single resource (or a very small set of resources), you can use IResourceDelta.findMember(IPath) to quickly locate the resource you are interested in updating. The supplied path is considered as relative to the path of the resource delta that it is called on. Another common case is resource change listeners that are only interested in processing changes to markers ( IMarker objects). These listeners can use IResourceChangeEvent.findMarkerDeltas to quickly collect all changed markers of a given type.

There is also a visitor mechanism (IResourceDelta.accept(IResourceDeltaVisitor)) for easily processing all changed resources in a given sub-tree. However, visitors should only be used where appropriate. Using a visitor to process two or three resources doesn't make sense, as the overhead of visiting the entire delta tree is incurred for no good reason. Since it's so easy to write a visitor, there is a tendency for programmers to use them too liberally, even in cases where they only want to process a well-defined subset of a tree. The return value from the visitor's visit method is used to indicate if that resource's children should be traversed. This can be used to short-circuit the traversal to avoid visiting sub-trees that you know you are not interested in.

Thread safety. There are some multi-threading issues to keep in mind when writing listeners. First, you have no control over what thread your listener will run in. Workspace operations can occur in any thread, and resource change listeners will run in whatever thread that triggered the operation. So, if some of your update code must be run in a particular thread, you'll have to make sure your code gets posted to that thread. The most common example of this is UI updates. With the Standard Widget Toolkit (SWT), the UI toolkit that is included with Eclipse, there is only a single UI thread per display. If your resource change listener needs to update the UI, you will need to use the methods syncExec or asyncExec in class org.eclipse.swt.widgets.Display to post the update code to the UI thread.

If any of your update code runs asynchronously (i.e., you used asyncExec or some similar mechanism to post your code to another thread), there is another consideration to keep in mind. The resource delta objects supplied to your listener are designed to "expire" when the resourceChanged method returns. So, if you pass references to IResourceDelta objects to another thread, they may cause failures if they are accessed after the listener method has returned back in the other thread. The reason for this resource delta "expiry date", is to ensure that listeners don't hold onto resource delta references indefinitely. These delta structures are potentially quite large, and if a listener holds onto them, it essentially causes a memory leak because these structures can no longer be garbage collected.

   public class DocIndexUpdater implements IResourceChangeListener {
      private TableViewer table; //assume this gets initialized somewhere
      private static final IPath DOC_PATH = new Path("MyProject/doc");
      public void resourceChanged(IResourceChangeEvent event) {
         //we are only interested in POST_CHANGE events
         if (event.getType() != IResourceChangeEvent.POST_CHANGE)
            return;
         IResourceDelta rootDelta = event.getDelta();
         //get the delta, if any, for the documentation directory
         IResourceDelta docDelta = rootDelta.findMember(DOC_PATH);
         if (docDelta == null)
            return;
         final ArrayList changed = new ArrayList();
         IResourceDeltaVisitor visitor = new IResourceDeltaVisitor() {
            public boolean visit(IResourceDelta delta) {
               //only interested in changed resources (not added or removed)
               if (delta.getKind() != IResourceDelta.CHANGED)
                  return true;
               //only interested in content changes
               if ((delta.getFlags() & IResourceDelta.CONTENT) == 0)
                  return true;
               IResource resource = delta.getResource();
               //only interested in files with the "txt" extension
               if (resource.getType() == IResource.FILE && 
				"txt".equalsIgnoreCase(resource.getFileExtension())) {
                  changed.add(resource);
               }
               return true;
            }
         };
         try {
            docDelta.accept(visitor);
         } catch (CoreException e) {
            //open error dialog with syncExec or print to plugin log file
         }
         //nothing more to do if there were no changed text files
         if (changed.size() == 0)
            return;
         //post this update to the table
         Display display = table.getControl().getDisplay();
         if (!display.isDisposed()) {
            display.asyncExec(new Runnable() {
               public void run() {
                  //make sure the table still exists
                  if (table.getControl().isDisposed())
                     return;
                  table.update(changed.toArray(), null);
               }
            });
         }
      }
   }

The solution to this problem is to take advantage of the save participant mechanism. Save participants implement the ISaveParticipant interface, and are installed using IWorkspace.addSaveParticipant. The main purpose of save participants is to allow plug-ins to save their important model state at the same time that the workspace saves its state. This ensures that the persisted workspace state stays synchronized with any domain model state that relies on it. Once a save participant is registered with the workspace, subsequent calls to addSaveParticipant will return an ISavedState object. By passing a resource change listener to ISavedState.processResourceChangeEvents, participants are given the opportunity to process the changes that have occurred since the last save occurred. This fills in the "blind spot" between workspace startup and activation of the plug-in that the listener belongs to. To find out about other facilities provided by the save participant mechanism, read the API Javadoc for ISaveParticipant, ISavedState, and ISaveContext.

Builders are another mechanism provided by the platform core for processing resource changes. Where change listeners are intended as a light-weight update mechanism, builders are designed to be a more powerful and flexible way of processing resource changes. Although builders are discussed in greater detail in a companion builder article, it is useful to know about the major differences between resource change listeners and builders:

• Builders are always allowed to modify the workspace.
• Builders have support for progress monitoring, cancellation, and error reporting.
• Listeners operate on the entire workspace; builders are installed on a per-project basis.
• Builders are run in a concrete order that can be specified individually on each project. Builders can enforce dependency relationships with other builders (my builder must run after the "Foo" builder). Projects are also built in a specified order. With resource change listeners, there is no way to ensure or even discover the order in which listeners receive the change events.
• There are different build policies: incremental build, full build, and auto-build.
• Builder lifecycle and persistence is managed by the platform. Once a builder is installed on a project, it will remain on that project across sessions.
• Builder configurations can easily be shared with other users, since the information is contained in the shareable project description file (called ".project").

These differences aside, the principle behind project builders and resource change listeners is the same. Builders are provided with a similar IResourceDelta hierarchy that describes what has changed since the last time that builder was called. This gives builders a chance to incrementally update the resources they operate on in response to changes made by others. For more details on builders, see the eclipse.org article Project Natures and Builders.