Java > Open Source Codes > org > eclipse > core > resources > IWorkspace


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  * Red Hat Incorporated - loadProjectDescription(InputStream)
11  *******************************************************************************/
12 package org.eclipse.core.resources;
13
14 import java.io.InputStream ;
15 import java.net.URI ;
16 import java.util.Map ;
17 import org.eclipse.core.resources.team.FileModificationValidationContext;
18 import org.eclipse.core.runtime.*;
19 import org.eclipse.core.runtime.jobs.ISchedulingRule;
20 import org.eclipse.core.runtime.jobs.LockListener;
21
22 /**
23  * Workspaces are the basis for Eclipse Platform resource management. There is
24  * only one workspace per running platform. All resources exist in the context
25  * of this workspace.
26  * <p>
27  * A workspace corresponds closely to discreet areas in the local file system.
28  * Each project in a workspace maps onto a specific area of the file system. The
29  * folders and files within a project map directly onto the corresponding
30  * directories and files in the file system. One sub-directory, the workspace
31  * metadata area, contains internal information about the workspace and its
32  * resources. This metadata area should be accessed only by the Platform or via
33  * Platform API calls.
34  * </p>
35  * <p>
36  * Workspaces add value over using the file system directly in that they allow
37  * for comprehensive change tracking (through <code>IResourceDelta</code> s),
38  * various forms of resource metadata (e.g., markers and properties) as well as
39  * support for managing application/tool state (e.g., saving and restoring).
40  * </p>
41  * <p>
42  * The workspace as a whole is thread safe and allows one writer concurrent with
43  * multiple readers. It also supports mechanisms for saving and snapshooting the
44  * current resource state.
45  * </p>
46  * <p>
47  * The workspace is provided by the Resources plug-in and is automatically
48  * created when that plug-in is activated. The default workspace data area
49  * (i.e., where its resources are stored) overlap exactly with the platform's
50  * data area. That is, by default, the workspace's projects are found directly
51  * in the platform's data area. Individual project locations can be specified
52  * explicitly.
53  * </p>
54  * <p>
55  * The workspace resource namespace is always case-sensitive and
56  * case-preserving. Thus the workspace allows multiple sibling resources to exist
57  * with names that differ only in case. The workspace also imposes no
58  * restrictions on valid characters in resource names, the length of resource names,
59  * or the size of resources on disk. In situations where one or more resources
60  * are stored in a file system that is not case-sensitive, or that imposes restrictions
61  * on resource names, any failure to store or retrieve those resources will
62  * be propagated back to the caller of workspace API.
63  * </p>
64  * <p>
65  * This interface is not intended to be implemented by clients.
66  * </p>
67  * <p>
68  * Workspaces implement the <code>IAdaptable</code> interface; extensions are
69  * managed by the platform's adapter manager.
70  * </p>
71  */
72 public interface IWorkspace extends IAdaptable {
73     /**
74      * flag constant (bit mask value 1) indicating that resource change
75      * notifications should be avoided during the invocation of a compound
76      * resource changing operation.
77      *
78      * @see IWorkspace#run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor)
79      * @since 3.0
80      */
81     public static final int AVOID_UPDATE = 1;
82
83     /**
84      * Constant that can be passed to {@link #validateEdit(org.eclipse.core.resources.IFile[], Object)}
85      * to indicate that the caller does not have access to a UI context but would still
86      * like to have UI-based validation if possible.
87      * @since 3.3
88      * @see #validateEdit(IFile[], Object)
89      */
90     public static final Object VALIDATE_PROMPT = FileModificationValidationContext.VALIDATE_PROMPT;
91
92     /**
93      * Adds the given listener for resource change events to this workspace. Has
94      * no effect if an identical listener is already registered.
95      * <p>
96      * This method is equivalent to:
97      *
98      * <pre>
99      * addResourceChangeListener(listener, IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE | IResourceChangeEvent.POST_CHANGE);
100      * </pre>
101      *
102      * </p>
103      *
104      * @param listener the listener
105      * @see IResourceChangeListener
106      * @see IResourceChangeEvent
107      * @see #addResourceChangeListener(IResourceChangeListener, int)
108      * @see #removeResourceChangeListener(IResourceChangeListener)
109      */
110     public void addResourceChangeListener(IResourceChangeListener listener);
111
112     /**
113      * Adds the given listener for the specified resource change events to this
114      * workspace. Has no effect if an identical listener is already registered
115      * for these events. After completion of this method, the given listener
116      * will be registered for exactly the specified events. If they were
117      * previously registered for other events, they will be de-registered.
118      * <p>
119      * Once registered, a listener starts receiving notification of changes to
120      * resources in the workspace. The resource deltas in the resource change
121      * event are rooted at the workspace root. Most resource change
122      * notifications occur well after the fact; the exception is
123      * pre-notification of impending project closures and deletions. The
124      * listener continues to receive notifications until it is replaced or
125      * removed.
126      * </p>
127      * <p>
128      * Listeners can listen for several types of event as defined in
129      * <code>IResourceChangeEvent</code>. Clients are free to register for
130      * any number of event types however if they register for more than one, it
131      * is their responsibility to ensure they correctly handle the case where
132      * the same resource change shows up in multiple notifications. Clients are
133      * guaranteed to receive only the events for which they are registered.
134      * </p>
135      *
136      * @param listener the listener
137      * @param eventMask the bit-wise OR of all event types of interest to the
138      * listener
139      * @see IResourceChangeListener
140      * @see IResourceChangeEvent
141      * @see #removeResourceChangeListener(IResourceChangeListener)
142      */
143     public void addResourceChangeListener(IResourceChangeListener listener, int eventMask);
144
145     /**
146      * Registers the given plug-in's workspace save participant, and returns an
147      * object describing the workspace state at the time of the last save in
148      * which the plug-in participated.
149      * <p>
150      * Once registered, the workspace save participant will actively participate
151      * in the saving of this workspace.
152      * </p>
153      *
154      * @param plugin the plug-in
155      * @param participant the participant
156      * @return the last saved state in which the plug-in participated, or
157      * <code>null</code> if the plug-in has not participated before
158      * @exception CoreException if the method fails to add the participant.
159      * Reasons include:
160      * <ul>
161      * <li>The previous state could not be recovered.</li>
162      * </ul>
163      * @see ISaveParticipant
164      * @see #removeSaveParticipant(Plugin)
165      */
166     public ISavedState addSaveParticipant(Plugin plugin, ISaveParticipant participant) throws CoreException;
167
168     /**
169      * Builds all projects in this workspace. Projects are built in the order
170      * specified in this workspace's description. Projects not mentioned in the
171      * order or for which the order cannot be determined are built in an
172      * undefined order after all other projects have been built. If no order is
173      * specified, the workspace computes an order determined by project
174      * references.
175      * <p>
176      * This method may change resources; these changes will be reported in a
177      * subsequent resource change event.
178      * </p>
179      * <p>
180      * This method is long-running; progress and cancellation are provided by
181      * the given progress monitor.
182      * </p>
183      *
184      * @param kind the kind of build being requested. Valid values are
185      * <ul>
186      * <li>{@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.</li>
187      * <li>{@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.</li>
188      * <li>{@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does
189      * not actually build anything, but rather discards all problems and build states.</li>
190      * </ul>
191      * @param monitor a progress monitor, or <code>null</code> if progress
192      * reporting is not desired
193      * @exception CoreException if the build fails.
194      * The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED}
195      * code, but it could also be any other status code; it might
196      * also be a {@link MultiStatus}.
197      * @exception OperationCanceledException if the operation is canceled.
198      * Cancelation can occur even if no progress monitor is provided.
199      *
200      * @see IProject#build(int, IProgressMonitor)
201      * @see #computeProjectOrder(IProject[])
202      * @see IncrementalProjectBuilder#FULL_BUILD
203      * @see IncrementalProjectBuilder#INCREMENTAL_BUILD
204      * @see IncrementalProjectBuilder#CLEAN_BUILD
205      * @see IResourceRuleFactory#buildRule()
206      */
207     public void build(int kind, IProgressMonitor monitor) throws CoreException;
208
209     /**
210      * Checkpoints the operation currently in progress. This method is used in
211      * the middle of a group of operations to force a background autobuild (if
212      * the build argument is true) and send an interim notification of resource
213      * change events.
214      * <p>
215      * When invoked in the dynamic scope of a call to the
216      * <code>IWorkspace.run</code> method, this method reports a single
217      * resource change event describing the net effect of all changes done to
218      * resources since the last round of notifications. When the outermost
219      * <code>run</code> method eventually completes, it will do another
220      * autobuild (if enabled) and report the resource changes made after this
221      * call.
222      * </p>
223      * <p>
224      * This method has no effect if invoked outside the dynamic scope of a call
225      * to the <code>IWorkspace.run</code> method.
226      * </p>
227      * <p>
228      * This method should be used under controlled circumstance (e.g., to break
229      * up extremely long-running operations).
230      * </p>
231      *
232      * @param build whether or not to run a build
233      * @see IWorkspace#run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor)
234      */
235     public void checkpoint(boolean build);
236
237     /**
238      * Returns the prerequisite ordering of the given projects. The computation
239      * is done by interpreting project references as dependency relationships.
240      * For example if A references B and C, and C references B, this method,
241      * given the list A, B, C will return the order B, C, A. That is, projects
242      * with no dependencies are listed first.
243      * <p>
244      * The return value is a two element array of project arrays. The first
245      * project array is the list of projects which could be sorted (as outlined
246      * above). The second element of the return value is an array of the
247      * projects which are ambiguously ordered (e.g., they are part of a cycle).
248      * </p>
249      * <p>
250      * Cycles and ambiguities are handled by elimination. Projects involved in
251      * cycles are simply cut out of the ordered list and returned in an
252      * undefined order. Closed and non-existent projects are ignored and do not
253      * appear in the returned value at all.
254      * </p>
255      *
256      * @param projects the projects to order
257      * @return the projects in sorted order and a list of projects which could
258      * not be ordered
259      * @deprecated Replaced by <code>IWorkspace.computeProjectOrder</code>,
260      * which produces a more usable result when there are cycles in project
261      * reference graph.
262      */
263     public IProject[][] computePrerequisiteOrder(IProject[] projects);
264
265     /**
266      * Data structure for holding the multi-part outcome of
267      * <code>IWorkspace.computeProjectOrder</code>.
268      * <p>
269      * This class is not intended to be instantiated by clients.
270      * </p>
271      *
272      * @see IWorkspace#computeProjectOrder(IProject[])
273      * @since 2.1
274      */
275     public final class ProjectOrder {
276         /**
277          * Creates an instance with the given values.
278          * <p>
279          * This class is not intended to be instantiated by clients.
280          * </p>
281          *
282          * @param projects initial value of <code>projects</code> field
283          * @param hasCycles initial value of <code>hasCycles</code> field
284          * @param knots initial value of <code>knots</code> field
285          */
286         public ProjectOrder(IProject[] projects, boolean hasCycles, IProject[][] knots) {
287             this.projects = projects;
288             this.hasCycles = hasCycles;
289             this.knots = knots;
290         }
291
292         /**
293          * A list of projects ordered so as to honor the project reference
294          * relationships between these projects wherever possible. The elements
295          * are a subset of the ones passed as the <code>projects</code>
296          * parameter to <code>IWorkspace.computeProjectOrder</code>, where
297          * inaccessible (closed or non-existent) projects have been omitted.
298          */
299         public IProject[] projects;
300         /**
301          * Indicates whether any of the accessible projects in
302          * <code>projects</code> are involved in non-trivial cycles.
303          * <code>true</code> if the project reference graph contains at least
304          * one cycle involving two or more of the projects in
305          * <code>projects</code>, and <code>false</code> if none of the
306          * projects in <code>projects</code> are involved in cycles.
307          */
308         public boolean hasCycles;
309         /**
310          * A list of knots in the project reference graph. This list is empty if
311          * the project reference graph does not contain cycles. If the project
312          * reference graph contains cycles, each element is a knot of two or
313          * more accessible projects from <code>projects</code> that are
314          * involved in a cycle of mutually dependent references.
315          */
316         public IProject[][] knots;
317     }
318
319     /**
320      * Computes a total ordering of the given projects based on both static and
321      * dynamic project references. If an existing and open project P references
322      * another existing and open project Q also included in the list, then Q
323      * should come before P in the resulting ordering. Closed and non-existent
324      * projects are ignored, and will not appear in the result. References to
325      * non-existent or closed projects are also ignored, as are any
326      * self-references. The total ordering is always consistent with the global
327      * total ordering of all open projects in the workspace.
328      * <p>
329      * When there are choices, the choice is made in a reasonably stable way.
330      * For example, given an arbitrary choice between two projects, the one with
331      * the lower collating project name is usually selected.
332      * </p>
333      * <p>
334      * When the project reference graph contains cyclic references, it is
335      * impossible to honor all of the relationships. In this case, the result
336      * ignores as few relationships as possible. For example, if P2 references
337      * P1, P4 references P3, and P2 and P3 reference each other, then exactly
338      * one of the relationships between P2 and P3 will have to be ignored. The
339      * outcome will be either [P1, P2, P3, P4] or [P1, P3, P2, P4]. The result
340      * also contains complete details of any cycles present.
341      * </p>
342      * <p>
343      * This method is time-consuming and should not be called unnecessarily.
344      * There are a very limited set of changes to a workspace that could affect
345      * the outcome: creating, renaming, or deleting a project; opening or
346      * closing a project; adding or removing a project reference.
347      * </p>
348      *
349      * @param projects the projects to order
350      * @return result describing the project order
351      * @since 2.1
352      */
353     public ProjectOrder computeProjectOrder(IProject[] projects);
354
355     /**
356      * Copies the given sibling resources so that they are located as members of
357      * the resource at the given path; the names of the copies are the same as
358      * the corresponding originals.
359      * <p>
360      * This is a convenience method, fully equivalent to:
361      *
362      * <pre>
363      * copy(resources, destination, (force ? IResource.FORCE : IResource.NONE), monitor);
364      * </pre>
365      *
366      * </p>
367      * <p>
368      * This method changes resources; these changes will be reported in a
369      * subsequent resource change event that will include an indication that the
370      * resources have been added to the new parent.
371      * </p>
372      * <p>
373      * This method is long-running; progress and cancellation are provided by
374      * the given progress monitor.
375      * </p>
376      *
377      * @param resources the resources to copy
378      * @param destination the destination container path
379      * @param force a flag controlling whether resources that are not in sync
380      * with the local file system will be tolerated
381      * @param monitor a progress monitor, or <code>null</code> if progress
382      * reporting is not desired
383      * @return a status object with code <code>OK</code> if there were no
384      * problems; otherwise a description (possibly a multi-status) consisting of
385      * low-severity warnings or informational messages
386      * @exception CoreException if the method fails to copy some resources. The
387      * status contained in the exception may be a multi-status indicating where
388      * the individual failures occurred.
389      * @exception OperationCanceledException if the operation is canceled.
390      * Cancelation can occur even if no progress monitor is provided.
391      * @see #copy(IResource[],IPath,int,IProgressMonitor)
392      */
393     public IStatus copy(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;
394
395     /**
396      * Copies the given sibling resources so that they are located as members of
397      * the resource at the given path; the names of the copies are the same as
398      * the corresponding originals.
399      * <p>
400      * This method can be expressed as a series of calls to
401      * <code>IResource.copy(IPath,int,IProgressMonitor)</code>, with "best
402      * effort" semantics:
403      * <ul>
404      * <li>Resources are copied in the order specified, using the given update
405      * flags.</li>
406      * <li>Duplicate resources are only copied once.</li>
407      * <li>The method fails if the resources are not all siblings.</li>
408      * <li>The failure of an individual copy does not necessarily prevent the
409      * method from attempting to copy other resources.</li>
410      * <li>The method fails if there are projects among the resources.</li>
411      * <li>The method fails if the path of the resources is a prefix of the
412      * destination path.</li>
413      * <li>This method also fails if one or more of the individual resource
414      * copy steps fails.</li>
415      * </ul>
416      * </p>
417      * <p>
418      * After successful completion, corresponding new resources will now exist
419      * as members of the resource at the given path.
420      * </p>
421      * <p>
422      * The supplied path may be absolute or relative. Absolute paths fully
423      * specify the new location for the resource, including its project.
424      * Relative paths are considered to be relative to the container of the
425      * resources being copied. A trailing separator is ignored.
426      * </p>
427      * <p>
428      * This method changes resources; these changes will be reported in a
429      * subsequent resource change event that will include an indication that the
430      * resources have been added to the new parent.
431      * </p>
432      * <p>
433      * This method is long-running; progress and cancellation are provided by
434      * the given progress monitor.
435      * </p>
436      *
437      * @param resources the resources to copy
438      * @param destination the destination container path
439      * @param updateFlags bit-wise or of update flag constants
440      * @param monitor a progress monitor, or <code>null</code> if progress
441      * reporting is not desired
442      * @return a status object with code <code>OK</code> if there were no
443      * problems; otherwise a description (possibly a multi-status) consisting of
444      * low-severity warnings or informational messages
445      * @exception CoreException if the method fails to copy some resources. The
446      * status contained in the exception may be a multi-status indicating where
447      * the individual failures occurred. Reasons include:
448      * <ul>
449      * <li>One of the resources does not exist.</li>
450      * <li>The resources are not siblings.</li>
451      * <li>One of the resources, or one of its descendents, is not local.</li>
452      * <li>The resource corresponding to the destination path does not exist.
453      * </li>
454      * <li>The resource corresponding to the parent destination path is a
455      * closed project.</li>
456      * <li>A corresponding target resource does exist.</li>
457      * <li>A resource of a different type exists at the target path.</li>
458      * <li>One of the resources is a project.</li>
459      * <li>The path of one of the resources is a prefix of the destination
460      * path.</li>
461      * <li>One of the resources, or one of its descendents, is out of sync with
462      * the local file system and <code>FORCE</code> is not specified.</li>
463      * <li>Resource changes are disallowed during certain types of resource
464      * change event notification. See <code>IResourceChangeEvent</code> for
465      * more details.</li>
466      * </ul>
467      * @exception OperationCanceledException if the operation is canceled.
468      * Cancelation can occur even if no progress monitor is provided.
469      * @see IResource#copy(IPath,int,IProgressMonitor)
470      * @see IResourceRuleFactory#copyRule(IResource, IResource)
471      * @since 2.0
472      */
473     public IStatus copy(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;
474
475     /**
476      * Deletes the given resources.
477      * <p>
478      * This is a convenience method, fully equivalent to:
479      *
480      * <pre>
481      * delete(resources, IResource.KEEP_HISTORY | (force ? IResource.FORCE : IResource.NONE), monitor);
482      * </pre>
483      *
484      * </p>
485      * <p>
486      * This method changes resources; these changes will be reported in a
487      * subsequent resource change event.
488      * </p>
489      * <p>
490      * This method is long-running; progress and cancellation are provided by
491      * the given progress monitor.
492      * </p>
493      *
494      * @param resources the resources to delete
495      * @param force a flag controlling whether resources that are not in sync
496      * with the local file system will be tolerated
497      * @param monitor a progress monitor, or <code>null</code> if progress
498      * reporting is not desired
499      * @return status with code <code>OK</code> if there were no problems;
500      * otherwise a description (possibly a multi-status) consisting of
501      * low-severity warnings or informational messages
502      * @exception CoreException if the method fails to delete some resource. The
503      * status contained in the exception is a multi-status indicating where the
504      * individual failures occurred.
505      * @exception OperationCanceledException if the operation is canceled.
506      * Cancelation can occur even if no progress monitor is provided.
507      * @see #delete(IResource[],int,IProgressMonitor)
508      */
509     public IStatus delete(IResource[] resources, boolean force, IProgressMonitor monitor) throws CoreException;
510
511     /**
512      * Deletes the given resources.
513      * <p>
514      * This method can be expressed as a series of calls to
515      * <code>IResource.delete(int,IProgressMonitor)</code>.
516      * </p>
517      * <p>
518      * The semantics of multiple deletion are:
519      * <ul>
520      * <li>Resources are deleted in the order presented, using the given update
521      * flags.</li>
522      * <li>Resources that do not exist are ignored.</li>
523      * <li>An individual deletion fails if the resource still exists
524      * afterwards.</li>
525      * <li>The failure of an individual deletion does not prevent the method
526      * from attempting to delete other resources.</li>
527      * <li>This method fails if one or more of the individual resource
528      * deletions fails; that is, if at least one of the resources in the list
529      * still exists at the end of this method.</li>
530      * </ul>
531      * </p>
532      * <p>
533      * This method changes resources; these changes will be reported in a
534      * subsequent resource change event.
535      * </p>
536      * <p>
537      * This method is long-running; progress and cancellation are provided by
538      * the given progress monitor.
539      * </p>
540      *
541      * @param resources the resources to delete
542      * @param updateFlags bit-wise or of update flag constants
543      * @param monitor a progress monitor, or <code>null</code> if progress
544      * reporting is not desired
545      * @return status with code <code>OK</code> if there were no problems;
546      * otherwise a description (possibly a multi-status) consisting of
547      * low-severity warnings or informational messages
548      * @exception CoreException if the method fails to delete some resource. The
549      * status contained in the exception is a multi-status indicating where the
550      * individual failures occurred.
551      * @exception OperationCanceledException if the operation is canceled.
552      * Cancelation can occur even if no progress monitor is provided.
553      * @see IResource#delete(int,IProgressMonitor)
554      * @see IResourceRuleFactory#deleteRule(IResource)
555      * @since 2.0
556      */
557     public IStatus delete(IResource[] resources, int updateFlags, IProgressMonitor monitor) throws CoreException;
558
559     /**
560      * Removes the given markers from the resources with which they are
561      * associated. Markers that do not exist are ignored.
562      * <p>
563      * This method changes resources; these changes will be reported in a
564      * subsequent resource change event.
565      * </p>
566      *
567      * @param markers the markers to remove
568      * @exception CoreException if this method fails. Reasons include:
569      * <ul>
570      * <li>Resource changes are disallowed during certain types of resource
571      * change event notification. See <code>IResourceChangeEvent</code> for
572      * more details.</li>
573      * </ul>
574      * @see IResourceRuleFactory#markerRule(IResource)
575      */
576     public void deleteMarkers(IMarker[] markers) throws CoreException;
577
578     /**
579      * Forgets any resource tree being saved for the plug-in with the given
580      * name. If the plug-in id is <code>null</code>, all trees are forgotten.
581      * <p>
582      * Clients should not call this method unless they have a reason to do so. A
583      * plug-in which uses <code>ISaveContext.needDelta</code> in the process
584      * of a save indicates that it would like to be fed the resource delta the
585      * next time it is reactivated. If a plug-in never gets reactivated (or if
586      * it fails to successfully register to participate in workspace saves), the
587      * workspace nevertheless retains the necessary information to generate the
588      * resource delta if asked. This method allows such a long term leak to be
589      * plugged.
590      * </p>
591      *
592      * @param pluginId the unique identifier of the plug-in
593      * @see ISaveContext#needDelta()
594      */
595     public void forgetSavedTree(String pluginId);
596
597     /**
598      * Returns all nature descriptors known to this workspace. Returns an empty
599      * array if there are no installed natures.
600      *
601      * @return the nature descriptors known to this workspace
602      * @since 2.0
603      */
604     public IProjectNatureDescriptor[] getNatureDescriptors();
605
606     /**
607      * Returns the nature descriptor with the given unique identifier, or
608      * <code>null</code> if there is no such nature.
609      *
610      * @param natureId the nature extension identifier (e.g.
611      * <code>"com.example.coolNature"</code>).
612      * @return the nature descriptor, or <code>null</code>
613      * @since 2.0
614      */
615     public IProjectNatureDescriptor getNatureDescriptor(String natureId);
616
617     /**
618      * Finds all dangling project references in this workspace. Projects which
619      * are not open are ignored. Returns a map with one entry for each open
620      * project in the workspace that has at least one dangling project
621      * reference; the value of the entry is an array of projects which are
622      * referenced by that project but do not exist in the workspace. Returns an
623      * empty Map if there are no projects in the workspace.
624      *
625      * @return a map (key type: <code>IProject</code>, value type:
626      * <code>IProject[]</code>) from project to dangling project references
627      */
628     public Map getDanglingReferences();
629
630     /**
631      * Returns the workspace description. This object is responsible for
632      * defining workspace preferences. The returned value is a modifiable copy
633      * but changes are not automatically applied to the workspace. In order to
634      * changes take effect, <code>IWorkspace.setDescription</code> needs to be
635      * called. The workspace description values are store in the preference
636      * store.
637      *
638      * @return the workspace description
639      * @see #setDescription(IWorkspaceDescription)
640      */
641     public IWorkspaceDescription getDescription();
642
643     /**
644      * Returns the root resource of this workspace.
645      *
646      * @return the workspace root
647      */
648     public IWorkspaceRoot getRoot();
649
650     /**
651      * Returns a factory for obtaining scheduling rules prior to modifying
652      * resources in the workspace.
653      *
654      * @see IResourceRuleFactory
655      * @return a resource rule factory
656      * @since 3.0
657      */
658     public IResourceRuleFactory getRuleFactory();
659
660     /**
661      * Returns the synchronizer for this workspace.
662      *
663      * @return the synchronizer
664      * @see ISynchronizer
665      */
666     public ISynchronizer getSynchronizer();
667
668     /**
669      * Returns whether this workspace performs autobuilds.
670      *
671      * @return <code>true</code> if autobuilding is on, <code>false</code>
672      * otherwise
673      */
674     public boolean isAutoBuilding();
675
676     /**
677      * Returns whether the workspace tree is currently locked. Resource changes
678      * are disallowed during certain types of resource change event
679      * notification. See <code>IResourceChangeEvent</code> for more details.
680      *
681      * @return boolean <code>true</code> if the workspace tree is locked,
682      * <code>false</code> otherwise
683      * @see IResourceChangeEvent
684      * @since 2.1
685      */
686     public boolean isTreeLocked();
687
688     /**
689      * Reads the project description file (".project") from the given location
690      * in the local file system. This object is useful for discovering the
691      * correct name for a project before importing it into the workspace.
692      * <p>
693      * The returned value is writeable.
694      * </p>
695      *
696      * @param projectDescriptionFile the path in the local file system of an
697      * existing project description file
698      * @return a new project description
699      * @exception CoreException if the operation failed. Reasons include:
700      * <ul>
701      * <li>The project description file does not exist.</li>
702      * <li>The file cannot be opened or read.</li>
703      * <li>The file cannot be parsed as a legal project description.</li>
704      * </li>
705      * @see #newProjectDescription(String)
706      * @see IProject#getDescription()
707      * @since 2.0
708      */
709     public IProjectDescription loadProjectDescription(IPath projectDescriptionFile) throws CoreException;
710
711     /**
712      * Reads the project description file (".project") from the given InputStream.
713      * This object will not attempt to set the location since the project may not
714      * have a valid location on the local file system.
715      * This object is useful for discovering the correct name for a project before
716      * importing it into the workspace.
717      * <p>
718      * The returned value is writeable.
719      * </p>
720      *
721      * @param projectDescriptionFile an InputStream pointing to an existing project
722      * description file
723      * @return a new project description
724      * @exception CoreException if the operation failed. Reasons include:
725      * <ul>
726      * <li>The stream could not be read.</li>
727      * <li>The stream does not contain a legal project description.</li>
728      * </li>
729      * @see #newProjectDescription(String)
730      * @see IProject#getDescription()
731      * @see IWorkspace#loadProjectDescription(IPath)
732      * @since 3.1
733      */
734     public IProjectDescription loadProjectDescription(InputStream projectDescriptionFile) throws CoreException;
735
736     /**
737      * Moves the given sibling resources so that they are located as members of
738      * the resource at the given path; the names of the new members are the
739      * same.
740      * <p>
741      * This is a convenience method, fully equivalent to:
742      *
743      * <pre>
744      * move(resources, destination, IResource.KEEP_HISTORY | (force ? IResource.FORCE : IResource.NONE), monitor);
745      * </pre>
746      *
747      * </p>
748      * <p>
749      * This method changes resources; these changes will be reported in a
750      * subsequent resource change event that will include an indication that the
751      * resources have been removed from their parent and that corresponding
752      * resources have been added to the new parent. Additional information
753      * provided with resource delta shows that these additions and removals are
754      * pairwise related.
755      * </p>
756      * <p>
757      * This method is long-running; progress and cancellation are provided by
758      * the given progress monitor.
759      * </p>
760      *
761      * @param resources the resources to move
762      * @param destination the destination container path
763      * @param force a flag controlling whether resources that are not in sync
764      * with the local file system will be tolerated
765      * @param monitor a progress monitor, or <code>null</code> if progress
766      * reporting is not desired
767      * @return status with code <code>OK</code> if there were no problems;
768      * otherwise a description (possibly a multi-status) consisting of
769      * low-severity warnings or informational messages.
770      * @exception CoreException if the method fails to move some resources. The
771      * status contained in the exception may be a multi-status indicating where
772      * the individual failures occurred.
773      * @exception OperationCanceledException if the operation is canceled.
774      * Cancelation can occur even if no progress monitor is provided.
775      * @see #move(IResource[],IPath,int,IProgressMonitor)
776      */
777     public IStatus move(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;
778
779     /**
780      * Moves the given sibling resources so that they are located as members of
781      * the resource at the given path; the names of the new members are the
782      * same.
783      * <p>
784      * This method can be expressed as a series of calls to
785      * <code>IResource.move</code>, with "best effort" semantics:
786      * <ul>
787      * <li>Resources are moved in the order specified.</li>
788      * <li>Duplicate resources are only moved once.</li>
789      * <li>The <code>force</code> flag has the same meaning as it does on the
790      * corresponding single-resource method.</li>
791      * <li>The method fails if the resources are not all siblings.</li>
792      * <li>The method fails the path of any of the resources is a prefix of the
793      * destination path.</li>
794      * <li>The failure of an individual move does not necessarily prevent the
795      * method from attempting to move other resources.</li>
796      * <li>This method also fails if one or more of the individual resource
797      * moves fails; that is, if at least one of the resources in the list still
798      * exists at the end of this method.</li>
799      * <li>History is kept for moved files. When projects are moved, no history
800      * is kept</li>
801      * </ul>
802      * </p>
803      * <p>
804      * After successful completion, the resources and descendents will no longer
805      * exist; but corresponding new resources will now exist as members of the
806      * resource at the given path.
807      * </p>
808      * <p>
809      * The supplied path may be absolute or relative. Absolute paths fully
810      * specify the new location for the resource, including its project.
811      * Relative paths are considered to be relative to the container of the
812      * resources being moved. A trailing separator is ignored.
813      * </p>
814      * <p>
815      * This method changes resources; these changes will be reported in a
816      * subsequent resource change event that will include an indication that the
817      * resources have been removed from their parent and that corresponding
818      * resources have been added to the new parent. Additional information
819      * provided with resource delta shows that these additions and removals are
820      * pairwise related.
821      * </p>
822      * <p>
823      * This method is long-running; progress and cancellation are provided by
824      * the given progress monitor.
825      * </p>
826      *
827      * @param resources the resources to move
828      * @param destination the destination container path
829      * @param updateFlags bit-wise or of update flag constants
830      * @param monitor a progress monitor, or <code>null</code> if progress
831      * reporting is not desired
832      * @return status with code <code>OK</code> if there were no problems;
833      * otherwise a description (possibly a multi-status) consisting of
834      * low-severity warnings or informational messages.
835      * @exception CoreException if the method fails to move some resources. The
836      * status contained in the exception may be a multi-status indicating where
837      * the individual failures occurred. Reasons include:
838      * <ul>
839      * <li>One of the resources does not exist.</li>
840      * <li>The resources are not siblings.</li>
841      * <li>One of the resources, or one of its descendents, is not local.</li>
842      * <li>The resource corresponding to the destination path does not exist.
843      * </li>
844      * <li>The resource corresponding to the parent destination path is a
845      * closed project.</li>
846      * <li>A corresponding target resource does exist.</li>
847      * <li>A resource of a different type exists at the target path.</li>
848      * <li>The path of one of the resources is a prefix of the destination
849      * path.</li>
850      * <li>One of the resources, or one of its descendents, is out of sync with
851      * the local file system and <code>FORCE</code> is <code>false</code>.
852      * </li>
853      * <li>Resource changes are disallowed during certain types of resource
854      * change event notification. See <code>IResourceChangeEvent</code> for
855      * more details.</li>
856      * </ul>
857      * @exception OperationCanceledException if the operation is canceled.
858      * Cancelation can occur even if no progress monitor is provided.
859      * @see IResource#move(IPath,int,IProgressMonitor)
860      * @see IResourceRuleFactory#moveRule(IResource, IResource)
861      * @since 2.0
862      */
863     public IStatus move(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;
864
865     /**
866      * Creates and returns a new project description for a project with the
867      * given name. This object is useful when creating, moving or copying
868      * projects.
869      * <p>
870      * The project description is initialized to:
871      * <ul>
872      * <li>the given project name</li>
873      * <li>no references to other projects</li>
874      * <li>an empty build spec</li>
875      * <li>an empty comment</li>
876      * </ul>
877      * </p>
878      * <p>
879      * The returned value is writeable.
880      * </p>
881      *
882      * @param projectName the name of the project
883      * @return a new project description
884      * @see IProject#getDescription()
885      * @see IProject#create(IProjectDescription, IProgressMonitor)
886      * @see IResource#copy(IProjectDescription, int, IProgressMonitor)
887      * @see IProject#move(IProjectDescription, boolean, IProgressMonitor)
888      */
889     public IProjectDescription newProjectDescription(String projectName);
890
891     /**
892      * Removes the given resource change listener from this workspace. Has no
893      * effect if an identical listener is not registered.
894      *
895      * @param listener the listener
896      * @see IResourceChangeListener
897      * @see #addResourceChangeListener(IResourceChangeListener)
898      */
899     public void removeResourceChangeListener(IResourceChangeListener listener);
900
901     /**
902      * Removes the workspace save participant for the given plug-in from this
903      * workspace. If no such participant is registered, no action is taken.
904      * <p>
905      * Once removed, the workspace save participant no longer actively
906      * participates in any future saves of this workspace.
907      * </p>
908      *
909      * @param plugin the plug-in
910      * @see ISaveParticipant
911      * @see #addSaveParticipant(Plugin, ISaveParticipant)
912      */
913     public void removeSaveParticipant(Plugin plugin);
914
915     /**
916      * Runs the given action as an atomic workspace operation.
917      * <p>
918      * After running a method that modifies resources in the workspace,
919      * registered listeners receive after-the-fact notification of what just
920      * transpired, in the form of a resource change event. This method allows
921      * clients to call a number of methods that modify resources and only have
922      * resource change event notifications reported at the end of the entire
923      * batch.
924      * </p>
925      * <p>
926      * If this method is called outside the dynamic scope of another such call,
927      * this method runs the action and then reports a single resource change
928      * event describing the net effect of all changes done to resources by the
929      * action.
930      * </p>
931      * <p>
932      * If this method is called in the dynamic scope of another such call, this
933      * method simply runs the action.
934      * </p>
935      * <p>
936      * The supplied scheduling rule is used to determine whether this operation
937      * can be run simultaneously with workspace changes in other threads. If the
938      * scheduling rule conflicts with another workspace change that is currently
939      * running, the calling thread will be blocked until that change completes.
940      * If the action attempts to make changes to the workspace that were not
941      * specified in the scheduling rule, it will fail. If no scheduling rule is
942      * supplied, then any attempt to change resources will fail. If a non-<code>null</code>
943      * scheduling rule is supplied, this operation must always support cancelation
944      * in the case where this operation becomes blocked by a long running background
945      * operation.
946      * </p>
947      * <p>
948      * The AVOID_UPDATE flag controls whether periodic resource change
949      * notifications should occur during the scope of this call. If this flag is
950      * specified, and no other threads modify the workspace concurrently, then
951      * all resource change notifications will be deferred until the end of this
952      * call. If this flag is not specified, the platform may decide to broadcast
953      * periodic resource change notifications during the scope of this call.
954      * </p>
955      * <p>
956      * Flags other than <code>AVOID_UPDATE</code> are ignored.
957      * </p>
958      *
959      * @param action the action to perform
960      * @param rule the scheduling rule to use when running this operation, or
961      * <code>null</code> if there are no scheduling restrictions for this
962      * operation.
963      * @param flags bit-wise or of flag constants (only AVOID_UPDATE is relevant
964      * here)
965      * @param monitor a progress monitor, or <code>null</code> if progress
966      * reporting is not desired.
967      * @exception CoreException if the operation failed.
968      * @exception OperationCanceledException if the operation is canceled. If a
969      * non-<code>null</code> scheduling rule is supplied, cancelation can occur
970      * even if no progress monitor is provided.
971      *
972      * @see #AVOID_UPDATE
973      * @see IResourceRuleFactory
974      * @since 3.0
975      */
976     public void run(IWorkspaceRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException;
977
978     /**
979      * Runs the given action as an atomic workspace operation.
980      * <p>
981      * This is a convenience method, fully equivalent to:
982      *
983      * <pre>
984      * workspace.run(action, workspace.getRoot(), IWorkspace.AVOID_UPDATE, monitor);
985      * </pre>
986      *
987      * </p>
988      *
989      * @param action the action to perform
990      * @param monitor a progress monitor, or <code>null</code> if progress
991      * reporting is not desired
992      * @exception CoreException if the operation failed.
993      * @exception OperationCanceledException if the operation is canceled.
994      * Cancelation can occur even if no progress monitor is provided.
995      */
996     public void run(IWorkspaceRunnable action, IProgressMonitor monitor) throws CoreException;
997
998     /**
999      * Saves this workspace's valuable state on disk. Consults with all
1000     * registered plug-ins so that they can coordinate the saving of their
1001     * persistent state as well.
1002     * <p>
1003     * The <code>full</code> parameter indicates whether a full save or a
1004     * snapshot is being requested. Snapshots save the workspace information
1005     * that is considered hard to be recomputed in the unlikely event of a
1006     * crash. It includes parts of the workspace tree, workspace and projects
1007     * descriptions, markers and sync information. Full saves are heavy weight
1008     * operations which save the complete workspace state.
1009     * </p>
1010     * <p>
1011     * To ensure that all outstanding changes to the workspace have been
1012     * reported to interested parties prior to saving, a full save cannot be
1013     * used within the dynamic scope of an <code>IWorkspace.run</code>
1014     * invocation. Snapshots can be called any time and are interpreted by the
1015     * workspace