platform-core/documents/3.1/background_refresh.html - www.eclipse.org/eclipse - Git at Google

 <!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 &gt; Import &gt; Existing Project</b> or <b>File &gt; New &gt; 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>
	<!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>