platform-core-home/documents/3.1/background_refresh.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (view) (download) (as text)

1 : johna 1.1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 :     <html>
3 :     <head>
4 :     <title>Background project discovery</title>
5 :     <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
6 :     </head>
7 :     <body text="#000000" bgcolor="#FFFFFF">
8 :    
9 :     <table width="100%">
10 :     <tr><td style="background:#0080C0"><b><span style="color:white">Design Overview</span></b></td></tr>
11 :     </table>
12 :    
13 :     <h1>Background project discovery</h1>
14 :     <font size="-1">Last modified: November 12, 2004</font>
15 :     <h3>The Problem</h3>
16 :     <p>
17 :     Projects are often created in Eclipse whose contents already exist on a
18 :     local disk. For example, a user checks out project contents from a repository,
19 :     or unzips some contents into their file system, and then performs either
20 :     <b>File &gt; Import &gt; Existing Project</b> or <b>File &gt; New &gt; Project</b>
21 :     to create a project on that existing location. When the new project is opened,
22 :     the Eclipse workspace automatically performs a refresh (<tt>IResource#refreshLocal</tt>)
23 :     to discover the contents on disk and create a corresponding project representation
24 :     in memory.
25 :     </p>
26 :     <p>
27 :     For very large projects, or for projects stored on a locally mounted network drive,
28 :     this refresh operation on project creation can take a long time. In some scenarios,
29 :     users have reported times of nearly ten minutes for this project discovery to occur.
30 :     During this time, the UI is typically blocked by the project creation or import wizard
31 :     dialog, and Eclipse becomes unusable until the refresh completes. There is no
32 :     technical reason to block the user from continuing to browse and edit other
33 :     files while this project creation is occurring.
34 :     </p>
35 :     <h3>The Solution</h3>
36 :     <p>
37 :     Support has been added in the 3.1 I20041116 build to allow background refreshing
38 :     of projects when they are opened for the first time. Refreshing does not occur
39 :     in the background by default, since this would be a breaking change for headless
40 :     Eclipse applications or plug-ins that assume the refresh is completed as soon as
41 :     the project opens. To enable background refresh, the new <tt>IResource#BACKGROUND_REFRESH</tt>
42 :     update flag should be passed to the <tt>IProject#open(int, IProgressMonitor)</tt> method.
43 :     This flag only has effect when a project is opened for the first time.
44 :     </p>
45 :     <p>
46 :     When the flag is specified, a background job is started when the project opens.
47 :     This job searches for differences between the local file system and the in-memory
48 :     project, and refreshes resources as they are discovered. This is implemented using
49 :     a queue that refreshes the project tree in breadth-first order. When a plug-in tries
50 :     to programmatically access a resouce that has not yet been refreshed, for
51 :     example by calling <tt>IContainer#members</tt> on a folder whose children
52 :     have not been refreshed, that folder is moved to the front of the refresh queue. In
53 :     this way, the refresh job tries to be smart about refreshing the resources that are
54 :     needed as soon as possible. For example, if the user expands an unrefreshed folder in the
55 :     Navigator view, there will initially be no children. In the background, the folder will
56 :     be refreshed immediately, and the next resource delta will tell the Navigator what
57 :     children need to be added. The effect is a very short delay between expanding a folder
58 :     and the children appearing in the tree.
59 :     </p>
60 :     <h3>Action Required</h3>
61 :     <p>
62 :     Project creation and import wizards that create projects against existing contents
63 :     on disk should switch to the use the new <tt>IResource#BACKGROUND_REFRESH</tt>
64 :     update flag when opening projects for the first time. Wizards that create projects
65 :     directly from other sources, such as zip files or repositories, do not need to specify
66 : johna 1.2 this flag. Note that the <tt>open</tt> method optimizes these cases, so the
67 :     background refresh flag will have no effect when creating a project with no existing
68 :     local contents, or when opening a project that has been opened before. It is generally
69 :     safe to always specify the background refresh flag in project creation wizards.
70 : johna 1.1 </p>
71 :     </body>
72 :     </html>