| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Background project discovery</title> |
| <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> |
| </head> |
| <body text="#000000" bgcolor="#FFFFFF"> |
| |
| <table width="100%"> |
| <tr><td style="background:#0080C0"><b><span style="color:white">Design Overview</span></b></td></tr> |
| </table> |
| |
| <h1>Background project discovery</h1> |
| <font size="-1">Last modified: November 12, 2004</font> |
| <h3>The Problem</h3> |
| <p> |
| Projects are often created in Eclipse whose contents already exist on a |
| local disk. For example, a user checks out project contents from a repository, |
| or unzips some contents into their file system, and then performs either |
| <b>File > Import > Existing Project</b> or <b>File > New > Project</b> |
| to create a project on that existing location. When the new project is opened, |
| the Eclipse workspace automatically performs a refresh (<tt>IResource#refreshLocal</tt>) |
| to discover the contents on disk and create a corresponding project representation |
| in memory. |
| </p> |
| <p> |
| For very large projects, or for projects stored on a locally mounted network drive, |
| this refresh operation on project creation can take a long time. In some scenarios, |
| users have reported times of nearly ten minutes for this project discovery to occur. |
| During this time, the UI is typically blocked by the project creation or import wizard |
| dialog, and Eclipse becomes unusable until the refresh completes. There is no |
| technical reason to block the user from continuing to browse and edit other |
| files while this project creation is occurring. |
| </p> |
| <h3>The Solution</h3> |
| <p> |
| Support has been added in the 3.1 I20041116 build to allow background refreshing |
| of projects when they are opened for the first time. Refreshing does not occur |
| in the background by default, since this would be a breaking change for headless |
| Eclipse applications or plug-ins that assume the refresh is completed as soon as |
| the project opens. To enable background refresh, the new <tt>IResource#BACKGROUND_REFRESH</tt> |
| update flag should be passed to the <tt>IProject#open(int, IProgressMonitor)</tt> method. |
| This flag only has effect when a project is opened for the first time. |
| </p> |
| <p> |
| When the flag is specified, a background job is started when the project opens. |
| This job searches for differences between the local file system and the in-memory |
| project, and refreshes resources as they are discovered. This is implemented using |
| a queue that refreshes the project tree in breadth-first order. When a plug-in tries |
| to programmatically access a resouce that has not yet been refreshed, for |
| example by calling <tt>IContainer#members</tt> on a folder whose children |
| have not been refreshed, that folder is moved to the front of the refresh queue. In |
| this way, the refresh job tries to be smart about refreshing the resources that are |
| needed as soon as possible. For example, if the user expands an unrefreshed folder in the |
| Navigator view, there will initially be no children. In the background, the folder will |
| be refreshed immediately, and the next resource delta will tell the Navigator what |
| children need to be added. The effect is a very short delay between expanding a folder |
| and the children appearing in the tree. |
| </p> |
| <h3>Action Required</h3> |
| <p> |
| Project creation and import wizards that create projects against existing contents |
| on disk should switch to the use the new <tt>IResource#BACKGROUND_REFRESH</tt> |
| update flag when opening projects for the first time. Wizards that create projects |
| directly from other sources, such as zip files or repositories, do not need to specify |
| this flag. Note that the <tt>open</tt> method optimizes these cases, so the |
| background refresh flag will have no effect when creating a project with no existing |
| local contents, or when opening a project that has been opened before. It is generally |
| safe to always specify the background refresh flag in project creation wizards. |
| </p> |
| </body> |
| </html> |