| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html> | |
| <head> | |
| <title>Auto-refresh overview</title> | |
| <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> | |
| </head> | |
| <body text="#000000" bgcolor="#FFFFFF"> | |
| <h1>Auto-refresh overview</h1> | |
| <font size="-1">Last modified: February 20, 2004</font> | |
| <p> | |
| In Eclipse 3.0 an auto-refresh facility was added to the | |
| org.eclipse.core.resources plugin. This feature, when enabled, searches | |
| the file system for changes that have been made externally, and then | |
| automatically refreshes the workspace when new changes are discovered. This | |
| document briefly describes the architecture of auto-refresh. | |
| </p> | |
| <p> | |
| Plug-ins provide change notification to the workspace by hooking into the | |
| new <tt>refreshProviders</tt> extension point. Extensions to this extension | |
| point implement subclasses of the following abstract class: | |
| <pre> | |
| public abstract class RefreshProvider { | |
| public abstract IRefreshMonitor installMonitor(IResource resource, IRefreshResult result); | |
| } | |
| </pre> | |
| </p> | |
| <p> | |
| When a new project or linked resource is added to the workspace, each installed | |
| refresh provider is asked to install a refresh monitor on that location. If for any | |
| reason a refresh provider is not able to monitor a given location, it can opt not to | |
| return a monitor. If no installed refresh providers are willing to monitor the location | |
| (or if no refresh providers are installed), a default refresh provider is implemented | |
| by the platform. This default refresh provider uses a naive Java-based polling | |
| loop that manually checks for changes in the location at a specified interval | |
| (by default, 30 seconds). | |
| </p> | |
| <p> | |
| Once installed, a monitor is responsible for notifying the workspace when external | |
| changes are made to that file system location by invoking methods on the provided | |
| callback interface (<tt>IRefreshResult</tt>). The results are collected by the | |
| workspace, and the workspace will synchronize the changed resources in | |
| a periodic background job. Note that this hand-off is entirely asynchronous. | |
| The monitor is responsible for identifying out of sync resources, and in a separate | |
| thread the workspace will process those changes and reconcile them with | |
| the workspace tree. | |
| </p> | |
| <p> | |
| The Eclipse SDK includes refresh provider implementations for both Win32 and Linux | |
| platforms. On all other platforms, the default Java-based polling refresh provider | |
| is used, unless another plug-in is installed that provides a more efficient | |
| platform-specific implementation. On Windows, the refresh provider uses win32 | |
| API calls to install a native file system monitor (FindFirstChangeNotificationW | |
| in windows.h). File system monitors in win32 are <b>deep</b>, i.e., they report | |
| changes on an entire file sub-tree. | |
| </p> | |
| <p> | |
| On Linux, the refresh provider use a standard Unix utility | |
| called FAM (File Alteration Monitor), that is installed by default on most Linux | |
| distributions. FAM runs a daemon that uses a native polling loop to detect changes in | |
| the file system. Clients can install a monitor on individual directories, and they are | |
| provided with a change event queue that they can process at will (either with a blocking | |
| dequeue operation or by peaking at the queue in their own polling loop). FAM | |
| monitors are <b>shallow</b>, i.e., you need to install separate monitors on | |
| each folder of a sub-tree. | |
| </p> | |
| </body> | |
| </html> |