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 as a hint that a snapshot is required. The workspace will
1016     * perform the snapshot when possible. Even as a hint, snapshots should only
1017     * be called when necessary as they impact system performance. Although
1018     * saving does not change the workspace per se, its execution is serialized
1019     * like methods that write the workspace.
1020     * </p>
1021     * <p>
1022     * The workspace is comprised of several different kinds of data with
1023     * varying degrees of importance. The most important data, the resources
1024     * themselves and their persistent properties, are written to disk
1025     * immediately; other data are kept in volatile memory and only written to
1026     * disk periodically; and other data are maintained in memory and never
1027     * written out. The following table summarizes what gets saved when:
1028     * <ul>
1029     * <li>creating or deleting resource - immediately</li>
1030     * <li>setting contents of file - immediately</li>
1031     * <li>changes to project description - immediately</li>
1032     * <li>session properties - never</li>
1033     * <li>changes to persistent properties - immediately</li>
1034     * <li>markers -<code>save</code></li>
1035     * <li>synchronizer info -<code>save</code></li>
1036     * <li>shape of the workspace resource tree -<code>save</code></li>
1037     * <li>list of active plug-ins - never</li>
1038     * </ul>
1039     * Resource-based plug-in also have data with varying degrees of importance.
1040     * Each plug-in gets to decide the policy for protecting its data, either
1041     * immediately, never, or at <code>save</code> time. For the latter, the
1042     * plug-in coordinates its actions with the workspace (see
1043     * <code>ISaveParticipant</code> for details).
1044     * </p>
1045     * <p>
1046     * If the platform is shutdown (or crashes) after saving the workspace, any
1047     * information written to disk by the last successful workspace
1048     * <code>save</code> will be restored the next time the workspace is
1049     * reopened for the next session. Naturally, information that is written to
1050     * disk immediately will be as of the last time it was changed.
1051     * </p>
1052     * <p>
1053     * The workspace provides a general mechanism for keeping concerned parties
1054     * apprised of any and all changes to resources in the workspace (
1055     * <code>IResourceChangeListener</code>). It is even possible for a
1056     * plug-in to find out about changes to resources that happen between
1057     * workspace sessions (see <code>IWorkspace.addSaveParticipant</code>).
1058     * </p>
1059     * <p>
1060     * At certain points during this method, the entire workspace resource tree
1061     * must be locked to prevent resources from being changed (read access to
1062     * resources is permitted).
1063     * </p>
1064     * <p>
1065     * Implementation note: The execution sequence is as follows.
1066     * <ul>
1067     * <li>A long-term lock on the workspace is taken out to prevent further
1068     * changes to workspace until the save is done.</li>
1069     * <li>The list of saveable resource tree snapshots is initially empty.
1070     * </li>
1071     * <li>A different <code>ISaveContext</code> object is created for each
1072     * registered workspace save participant plug-in, reflecting the kind of
1073     * save (<code>ISaveContext.getKind</code>), the previous save number in
1074     * which this plug-in actively participated, and the new save number (=
1075     * previous save number plus 1).</li>
1076     * <li>Each registered workspace save participant is sent
1077     * <code>prepareToSave(context)</code>, passing in its own context
1078     * object.
1079     * <ul>
1080     * <li>Plug-in suspends all activities until further notice.</li>
1081     * </ul>
1082     * If <code>prepareToSave</code> fails (throws an exception), the problem
1083     * is logged and the participant is marked as unstable.</li>
1084     * <li>In dependent-before-prerequisite order, each registered workspace
1085     * save participant is sent <code>saving(context)</code>, passing in its
1086     * own context object.
1087     * <ul>
1088     * <li>Plug-in decides whether it wants to actively participate in this
1089     * save. The plug-in only needs to actively participate if some of its
1090     * important state has changed since the last time it actively participated.
1091     * If it does decide to actively participate, it writes its important state
1092     * to a brand new file in its plug-in state area under a generated file name
1093     * based on <code>context.getStateNumber()</code> and calls
1094     * <code>context.needStateNumber()</code> to indicate that it has actively
1095     * participated. If upon reactivation the plug-in will want a resource delta
1096     * covering all changes between now and then, the plug-in should invoke
1097     * <code>context.needDelta()</code> to request this now; otherwise, a
1098     * resource delta for the intervening period will not be available on
1099     * reactivation.</li>
1100     * </ul>
1101     * If <code>saving</code> fails (throws an exception), the problem is
1102     * logged and the participant is marked as unstable.</li>
1103     * <li>The plug-in save table contains an entry for each plug-in that has
1104     * registered to participate in workspace saves at some time in the past
1105     * (the list of plug-ins increases monotonically). Each entry records the
1106     * save number of the last successful save in which that plug-in actively
1107     * participated, and, optionally, a saved resource tree (conceptually, this
1108     * is a complete tree; in practice, it is compressed into a special delta
1109     * tree representation). A copy of the plug-in save table is made. Entries
1110     * are created or modified for each registered plug-in to record the
1111     * appropriate save number (either the previous save number, or the previous
1112     * save number plus 1, depending on whether the participant was active and
1113     * asked for a new number).</li>
1114     * <li>The workspace tree, the modified copy of the plug-in save table, all
1115     * markers, etc. and all saveable resource tree snapshots are written to
1116     * disk as <b>one atomic operation </b>.</li>
1117     * <li>The long-term lock on the workspace is released.</li>
1118     * <li>If the atomic save succeeded:
1119     * <ul>
1120     * <li>The modified copy of the plug-in save table becomes the new plug-in
1121     * save table.</li>
1122     * <li>In prerequisite-before-dependent order, each registered workspace
1123     * save participant is sent <code>doneSaving(context)</code>, passing in
1124     * its own context object.
1125     * <ul>
1126     * <li>Plug-in may perform clean up by deleting obsolete state files in its
1127     * plug-in state area.</li>
1128     * <li>Plug-in resumes its normal activities.</li>
1129     * </ul>
1130     * If <code>doneSaving</code> fails (throws an exception), the problem is
1131     * logged and the participant is marked as unstable. (The state number in
1132     * the save table is not rolled back just because of this instability.)
1133     * </li>
1134     * <li>The workspace save operation returns.</li>
1135     * </ul>
1136     * <li>If it failed:
1137     * <ul>
1138     * <li>The workspace previous state is restored.</li>
1139     * <li>In prerequisite-before-dependent order, each registered workspace
1140     * save participant is sent <code>rollback(context)</code>, passing in
1141     * its own context object.
1142     * <ul>
1143     * <li>Plug-in may perform clean up by deleting newly-created but obsolete
1144     * state file in its plug-in state area.</li>
1145     * <li>Plug-in resumes its normal activities.</li>
1146     * </ul>
1147     * If <code>rollback</code> fails (throws an exception), the problem is
1148     * logged and the participant is marked as unstable. (The state number in
1149     * the save table is rolled back anyway.)</li>
1150     * <li>The workspace save operation fails.</li>
1151     * </ul>
1152     * </li>
1153     * </ul>
1154     * </p>
1155     * <p>
1156     * After a full save, the platform can be shutdown. This will cause the
1157     * Resources plug-in and all the other plug-ins to shutdown, without
1158     * disturbing the saved workspace on disk.
1159     * </p>
1160     * <p>
1161     * When the platform is later restarted, activating the Resources plug-in
1162     * opens the saved workspace. This reads into memory the workspace's
1163     * resource tree, plug-in save table, and saved resource tree snapshots
1164     * (everything that was written to disk in the atomic operation above).
1165     * Later, when a plug-in gets reactivated and registers to participate in
1166     * workspace saves, it is handed back the info from its entry in the plug-in
1167     * save table, if it has one. It gets back the number of the last save in
1168     * which it actively participated and, possibly, a resource delta.
1169     * </p>
1170     * <p>
1171     * The only source of long term garbage would come from a plug-in that never
1172     * gets reactivated, or one that gets reactivated but fails to register for
1173     * workspace saves. (There is no such problem with a plug-in that gets
1174     * uninstalled; its easy enough to scrub its state areas and delete its
1175     * entry in the plug-in save table.)
1176     * </p>
1177     *
1178     * @param full <code>true</code> if this is a full save, and
1179     * <code>false</code> if this is only a snapshot for protecting against
1180     * crashes
1181     * @param monitor a progress monitor, or <code>null</code> if progress
1182     * reporting is not desired
1183     * @return a status that may contain warnings, such as the failure of an
1184     * individual participant
1185     * @exception CoreException if this method fails to save the state of this
1186     * workspace. Reasons include:
1187     * <ul>
1188     * <li>The operation cannot be batched with others.</li>
1189     * </ul>
1190     * @exception OperationCanceledException if the operation is canceled.
1191     * Cancelation can occur even if no progress monitor is provided.
1192     * @see #addSaveParticipant(Plugin, ISaveParticipant)
1193     */
1194    public IStatus save(boolean full, IProgressMonitor monitor) throws CoreException;
1195
1196    /**
1197     * Sets the workspace description. Its values are stored in the preference
1198     * store.
1199     *
1200     * @param description the new workspace description.
1201     * @see #getDescription()
1202     * @exception CoreException if the method fails. Reasons include:
1203     * <ul>
1204     * <li>There was a problem setting the workspace description.</li>
1205     * </ul>
1206     */
1207    public void setDescription(IWorkspaceDescription description) throws CoreException;
1208
1209    /**
1210     * Sets the lock to use for controlling write access to this workspace. The
1211     * lock must only be set once.
1212     * <p>
1213     * This method is for internal use by the platform-related plug-ins. Clients
1214     * should not call this method.
1215     * </p>
1216     *
1217     * @param lock the lock to install on this workspace.
1218     *
1219     * @deprecated it is no longer possible to override the workspace lock
1220     * behavior. This functionality is now provided in the platform API by
1221     * subclassing the {@link LockListener} class.
1222     */
1223    public void setWorkspaceLock(WorkspaceLock lock);
1224
1225    /**
1226     * Returns a copy of the given set of natures sorted in prerequisite order.
1227     * For each nature, it is guaranteed that all of its prerequisites will
1228     * precede it in the resulting array.
1229     *
1230     * <p>
1231     * Natures that are missing from the install or are involved in a
1232     * prerequisite cycle are sorted arbitrarily. Duplicate nature IDs are
1233     * removed, so the returned array may be smaller than the original.
1234     * </p>
1235     *
1236     * @param natureIds a valid set of nature extension identifiers
1237     * @return the set of nature Ids sorted in prerequisite order
1238     * @see #validateNatureSet(String[])
1239     * @since 2.0
1240     */
1241    public String [] sortNatureSet(String [] natureIds);
1242
1243    /**
1244     * Advises that the caller intends to modify the contents of the given files
1245     * in the near future and asks whether modifying all these files would be
1246     * reasonable. The files must all exist. This method is used to give the VCM
1247     * component an opportunity to check out (or otherwise prepare) the files if
1248     * required. (It is provided in this component rather than in the UI so that
1249     * "core" (i.e., head-less) clients can use it. Similarly, it is located
1250     * outside the VCM component for the convenience of clients that must also
1251     * operate in configurations without VCM.)
1252     * </p>
1253     * <p>
1254     * A client (such as an editor) should perform a <code>validateEdit</code>
1255     * on a file whenever it finds itself in the following position: (a) the
1256     * file is marked read-only, and (b) the client believes it likely (not
1257     * necessarily certain) that it will modify the file's contents at some
1258     * point. A case in point is an editor that has a buffer opened on a file.
1259     * When the user starts to dirty the buffer, the editor should check to see
1260     * whether the file is read-only. If it is, it should call
1261     * <code>validateEdit</code>, and can reasonably expect this call, when
1262     * successful, to cause the file to become read-write. An editor should also
1263     * be sensitive to a file becoming read-only again even after a successful
1264     * <code>validateEdit</code> (e.g., due to the user checking in the file
1265     * in a different view); the editor should again call
1266     * <code>validateEdit</code> if the file is read-only before attempting to
1267     * save the contents of the file.
1268     * </p>
1269     * <p>
1270     * By passing a UI context, the caller indicates that the VCM component may
1271     * contact the user to help decide how best to proceed. If no UI context is
1272     * provided, the VCM component will make its decision without additional
1273     * interaction with the user. If OK is returned, the caller can safely
1274     * assume that all of the given files haven been prepared for modification
1275     * and that there is good reason to believe that
1276     * <code>IFile.setContents</code> (or <code>appendContents</code>)
1277     * would be successful on any of them. If the result is not OK, modifying
1278     * the given files might not succeed for the reason(s) indicated.
1279     * </p>
1280     * <p>
1281     * If a shell is passed in as the context, the VCM component may bring up a
1282     * dialogs to query the user or report difficulties; the shell should be
1283     * used to parent any such dialogs; the caller may safely assume that the
1284     * reasons for failure will have been made clear to the user. If
1285     * {@link IWorkspace#VALIDATE_PROMPT} is passed
1286     * as the context, this indicates that the caller does not have access to
1287     * a UI context but would still like the user to be prompted if required.
1288     * If <code>null</code> is passed, the user should not be contacted; any
1289     * failures should be reported via the result; the caller may chose to
1290     * present these to the user however they see fit. The ideal implementation
1291     * of this method is transactional; no files would be affected unless the
1292     * go-ahead could be given. (In practice, there may be no feasible way to
1293     * ensure such changes get done atomically.)
1294     * </p>
1295     * <p>
1296     * The method calls <code>FileModificationValidator.validateEdit</code>
1297     * for the file modification validator (if provided by the VCM plug-in).
1298     * When there is no file modification validator, this method returns a
1299     * status with an <code>IResourceStatus.READ_ONLY_LOCAL</code> code if one
1300     * of the files is read-only, and a status with an <code>IStatus.OK</code>
1301     * code otherwise.
1302     * </p>
1303     * <p>
1304     * This method may be called from any thread. If the UI context is used, it
1305     * is the responsibility of the implementor of
1306     * <code>FileModificationValidator.validateEdit</code> to interact with
1307     * the UI context in an appropriate thread.
1308     * </p>
1309     *
1310     * @param files the files that are to be modified; these files must all
1311     * exist in the workspace
1312     * @param context either {@link IWorkspace#VALIDATE_PROMPT},
1313     * or the <code>org.eclipse.swt.widgets.Shell</code> that is
1314     * to be used to parent any dialogs with the user, or <code>null</code> if
1315     * there is no UI context (declared as an <code>Object</code> to avoid any
1316     * direct references on the SWT component)
1317     * @return a status object that is <code>OK</code> if things are fine,
1318     * otherwise a status describing reasons why modifying the given files is not
1319     * reasonable. A status with a severity of <code>CANCEL</code> is returned
1320     * if the validation was canceled, indicating the edit should not proceed.
1321     * @see IResourceRuleFactory#validateEditRule(IResource[])
1322     * @since 2.0
1323     */
1324    public IStatus validateEdit(IFile[] files, Object context);
1325
1326    /**
1327     * Validates the given path as the location of the given resource on disk.
1328     * The path must be either an absolute file system path, or a relative path
1329     * whose first segment is the name of a defined workspace path variable. In
1330     * addition to the restrictions for paths in general (see <code>IPath.
1331     * isValidPath</code>),
1332     * a link location must also obey the following rules:
1333     * <ul>
1334     * <li>must not overlap with the platform's metadata directory</li>
1335     * <li>must not be the same as or a parent of the root directory of the
1336     * project the linked resource is contained in</li>
1337     * </ul>
1338     * <p>
1339     * This method also checks that the given resource can legally become a
1340     * linked resource. This includes the following restrictions:
1341     * <ul>
1342     * <li>must have a project as its immediate parent</li>
1343     * <li>project natures and the team hook may disallow linked resources on
1344     * projects they are associated with</li>
1345     * <li>the global workspace preference to disable linking,
1346     * <code>ResourcesPlugin.PREF_DISABLE_LINKING</code> must not be set to
1347     * &quot;true&quot;</li>.
1348     * </ul>
1349     * </p>
1350     * <p>
1351     * This method will return a status with severity <code>IStatus.ERROR</code>
1352     * if the location does not obey the above rules. Also, this method will
1353     * return a status with severity <code>IStatus.WARNING</code> if the
1354     * location overlaps the location of any existing resource in the workspace.
1355     * </p>
1356     * <p>
1357     * Note: this method does not consider whether files or directories exist in
1358     * the file system at the specified path.
1359     *
1360     * @param resource the resource to validate the location for
1361     * @param location the location of the linked resource contents on disk
1362     * @return a status object with code <code>IStatus.OK</code> if the given
1363     * location is valid as the linked resource location, otherwise a status
1364     * object with severity <code>IStatus.WARNING</code> or
1365     * <code>IStatus.ERROR</code> indicating what is wrong with the location
1366     * @see IStatus#OK
1367     * @see ResourcesPlugin#PREF_DISABLE_LINKING
1368     * @since 2.1
1369     */
1370    public IStatus validateLinkLocation(IResource resource, IPath location);
1371
1372    /**
1373     * Validates the given {@link URI} as the location of the given resource on disk.
1374     * The location must be either an absolute URI, or a relative URI
1375     * whose first segment is the name of a defined workspace path variable.
1376     * A link location must obey the following rules:
1377     * <ul>
1378     * <li>must not overlap with the platform's metadata directory</li>
1379     * <li>must not be the same as or a parent of the root directory of the
1380     * project the linked resource is contained in</li>
1381     * </ul>
1382     * <p>
1383     * This method also checks that the given resource can legally become a
1384     * linked resource. This includes the following restrictions:
1385     * <ul>
1386     * <li>must have a project as its immediate parent</li>
1387     * <li>project natures and the team hook may disallow linked resources on
1388     * projects they are associated with</li>
1389     * <li>the global workspace preference to disable linking,
1390     * <code>ResourcesPlugin.PREF_DISABLE_LINKING</code> must not be set to
1391     * &quot;true&quot;</li>.
1392     * </ul>
1393     * </p>
1394     * <p>
1395     * This method will return a status with severity <code>IStatus.ERROR</code>
1396     * if the location does not obey the above rules. Also, this method will
1397     * return a status with severity <code>IStatus.WARNING</code> if the
1398     * location overlaps the location of any existing resource in the workspace.
1399     * </p>
1400     * <p>
1401     * Note: this method does not consider whether files or directories exist in
1402     * the file system at the specified location.
1403     *
1404     * @param resource the resource to validate the location for
1405     * @param location the location of the linked resource contents in some file system
1406     * @return a status object with code <code>IStatus.OK</code> if the given
1407     * location is valid as the linked resource location, otherwise a status
1408     * object with severity <code>IStatus.WARNING</code> or
1409     * <code>IStatus.ERROR</code> indicating what is wrong with the location
1410     * @see IStatus#OK
1411     * @see ResourcesPlugin#PREF_DISABLE_LINKING
1412     * @since 3.2
1413     */
1414    public IStatus validateLinkLocationURI(IResource resource, URI location);
1415
1416    /**
1417     * Validates the given string as the name of a resource valid for one of the
1418     * given types.
1419     * <p>
1420     * In addition to the basic restrictions on paths in general (see
1421     * {@link IPath#isValidSegment(String)}), a resource name must also not
1422     * contain any characters or substrings that are not valid on the file system
1423     * on which workspace root is located. In addition, the names "." and ".."
1424     * are reserved due to their special meaning in file system paths.
1425     * </p>
1426     * <p>
1427     * This validation check is done automatically as a resource is created (but
1428     * not when the resource handle is constructed); this means that any
1429     * resource that exists can be safely assumed to have a valid name and path.
1430     * Note that the name of the workspace root resource is inherently invalid.
1431     * </p>
1432     *
1433     * @param segment the name segment to be checked
1434     * @param typeMask bitwise-or of the resource type constants (
1435     * <code>FILE</code>,<code>FOLDER</code>,<code>PROJECT</code> or
1436     * <code>ROOT</code>) indicating expected resource type(s)
1437     * @return a status object with code <code>IStatus.OK</code> if the given
1438     * string is valid as a resource name, otherwise a status object indicating
1439     * what is wrong with the string
1440     * @see IResource#PROJECT
1441     * @see IResource#FOLDER
1442     * @see IResource#FILE
1443     * @see IStatus#OK
1444     */
1445    public IStatus validateName(String segment, int typeMask);
1446
1447    /**
1448     * Validates that each of the given natures exists, and that all nature
1449     * constraints are satisfied within the given set.
1450     * <p>
1451     * The following conditions apply to validation of a set of natures:
1452     * <ul>
1453     * <li>all natures in the set exist in the plug-in registry
1454     * <li>all prerequisites of each nature are present in the set
1455     * <li>there are no cycles in the prerequisite graph of the set
1456     * <li>there are no two natures in the set that specify one-of-nature
1457     * inclusion in the same group.
1458     * <li>there are no two natures in the set with the same id
1459     * </ul>
1460     * </p>
1461     * <p>
1462     * An empty nature set is always valid.
1463     * </p>
1464     *
1465     * @param natureIds an array of nature extension identifiers
1466     * @return a status object with code <code>IStatus.OK</code> if the given
1467     * set of natures is valid, otherwise a status object indicating what is
1468     * wrong with the set
1469     * @since 2.0
1470     */
1471    public IStatus validateNatureSet(String [] natureIds);
1472
1473    /**
1474     * Validates the given string as a path for a resource of the given type(s).
1475     * <p>
1476     * In addition to the restrictions for paths in general (see
1477     * <code>IPath.isValidPath</code>), a resource path should also obey the
1478     * following rules:
1479     * <ul>
1480     * <li>a resource path should be an absolute path with no device id
1481     * <li>its segments should be valid names according to
1482     * <code>validateName</code>
1483     * <li>a path for the workspace root must be the canonical root path
1484     * <li>a path for a project should have exactly 1 segment
1485     * <li>a path for a file or folder should have more than 1 segment
1486     * <li>the first segment should be a valid project name
1487     * <li>the second through penultimate segments should be valid folder names
1488     * <li>the last segment should be a valid name of the given type
1489     * </ul>
1490     * </p>
1491     * <p>
1492     * Note: this method does not consider whether a resource at the specified
1493     * path exists.
1494     * </p>
1495     * <p>
1496     * This validation check is done automatically as a resource is created (but
1497     * not when the resource handle is constructed); this means that any
1498     * resource that exists can be safely assumed to have a valid name and path.
1499     * </p>
1500     *
1501     * @param path the path string to be checked
1502     * @param typeMask bitwise-or of the resource type constants (
1503     * <code>FILE</code>,<code>FOLDER</code>,<code>PROJECT</code>, or
1504     * <code>ROOT</code>) indicating expected resource type(s)
1505     * @return a status object with code <code>IStatus.OK</code> if the given
1506     * path is valid as a resource path, otherwise a status object indicating
1507     * what is wrong with the string
1508     * @see IResource#PROJECT
1509     * @see IResource#FOLDER
1510     * @see IResource#FILE
1511     * @see IStatus#OK
1512     * @see IResourceStatus#getPath()
1513     */
1514    public IStatus validatePath(String path, int typeMask);
1515
1516    /**
1517     * Validates the given path as the location of the given project on disk.
1518     * The path must be either an absolute file system path, or a relative path
1519     * whose first segment is the name of a defined workspace path variable. In
1520     * addition to the restrictions for paths in general (see <code>IPath.
1521     * isValidPath</code>),
1522     * a location path should also obey the following rules:
1523     * <ul>
1524     * <li>must not be the same as another open or closed project</li>
1525     * <li>must not occupy the default location for any project, whether existing or not</li>
1526     * <li>must not be the same as or a parent of the platform's working directory</li>
1527     * <li>must not be the same as or a child of the location of any existing
1528     * linked resource in the given project</li>
1529     * </ul>
1530     * </p>
1531     * <p>
1532     * Note: this method does not consider whether files or directories exist in
1533     * the file system at the specified path.
1534     *
1535     * @param project the project to validate the location for
1536     * @param location the location of the project contents on disk
1537     * @return a status object with code <code>IStatus.OK</code> if the given
1538     * location is valid as the project content location, otherwise a status
1539     * object indicating what is wrong with the location
1540     * @see IProjectDescription#getLocationURI()
1541     * @see IProjectDescription#setLocation(IPath)
1542     * @see IStatus#OK
1543     */
1544    public IStatus validateProjectLocation(IProject project, IPath location);
1545
1546    /**
1547     * Validates the given URI as the location of the given project.
1548     * The location must be either an absolute URI, or a relative URI
1549     * whose first segment is the name of a defined workspace path variable.
1550     * A project location must obey the following rules:
1551     * <ul>
1552     * <li>must not be the same as another open or closed project</li>
1553     * <li>must not occupy the default location for any project, whether existing or not</li>
1554     * <li>must not be the same as or a parent of the platform's working directory</li>
1555     * <li>must not be the same as or a child of the location of any existing
1556     * linked resource in the given project</li>
1557     * </ul>
1558     * </p>
1559     * <p>
1560     * Note: this method does not consider whether files or directories exist in
1561     * the file system at the specified path.
1562     *
1563     * @param project the project to validate the location for
1564     * @param location the location of the project contents on disk
1565     * @return a status object with code <code>IStatus.OK</code> if the given
1566     * location is valid as the project content location, otherwise a status
1567     * object indicating what is wrong with the location
1568     * @see IProjectDescription#getLocationURI()
1569     * @see IProjectDescription#setLocationURI(URI)
1570     * @see IStatus#OK
1571     * @since 3.2
1572     */
1573    public IStatus validateProjectLocationURI(IProject project, URI location);
1574
1575    /**
1576     * Returns the path variable manager for this workspace.
1577     *
1578     * @return the path variable manager
1579     * @see IPathVariableManager
1580     * @since 2.1
1581     */
1582    public IPathVariableManager getPathVariableManager();
1583}
1584

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags