KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 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  *******************************************************************************/

11 package org.eclipse.core.resources;
12
13 import java.util.Map JavaDoc;
14 import org.eclipse.core.runtime.*;
15 import org.eclipse.core.runtime.content.IContentTypeMatcher;
16
17 /**
18  * A project is a type of resource which groups resources
19  * into buildable, reusable units.
20  * <p>
21  * Features of projects include:
22  * <ul>
23  * <li>A project collects together a set of files and folders.</li>
24  * <li>A project's location controls where the project's resources are
25  * stored in the local file system.</li>
26  * <li>A project's build spec controls how building is done on the project.</li>
27  * <li>A project can carry session and persistent properties.</li>
28  * <li>A project can be open or closed; a closed project is
29  * passive and has a minimal in-memory footprint.</li>
30  * <li>A project can carry references to other projects.</li>
31  * <li>A project can have one or more project natures.</li>
32  * </ul>
33  * </p>
34  * <p>
35  * This interface is not intended to be implemented by clients.
36  * </p>
37  * <p>
38  * Projects implement the <code>IAdaptable</code> interface;
39  * extensions are managed by the platform's adapter manager.
40  * </p>
41  *
42  * @see Platform#getAdapterManager()
43  */

44 public interface IProject extends IContainer, IAdaptable {
45     /**
46      * Invokes the <code>build</code> method of the specified builder
47      * for this project. Does nothing if this project is closed. If this project
48      * has multiple builders on its build spec matching the given name, only
49      * the first matching builder will be run.
50      * <p>
51      * The builder name is declared in the extension that plugs in
52      * to the standard <code>org.eclipse.core.resources.builders</code>
53      * extension point. The arguments are builder specific.
54      * </p>
55      * <p>
56      * This method may change resources; these changes will be reported
57      * in a subsequent resource change event.
58      * </p>
59      * <p>
60      * This method is long-running; progress and cancellation are provided
61      * by the given progress monitor.
62      * </p>
63      *
64      * @param kind the kind of build being requested. Valid values are:
65      * <ul>
66      * <li>{@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.</li>
67      * <li>{@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.</li>
68      * <li>{@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does
69      * not actually build anything, but rather discards all problems and build states.</li>
70      * </ul>
71      * @param builderName the name of the builder
72      * @param args a table of builder-specific arguments keyed by argument name
73      * (key type: <code>String</code>, value type: <code>String</code>);
74      * <code>null</code> is equivalent to an empty map
75      * @param monitor a progress monitor, or <code>null</code> if progress
76      * reporting is not desired
77      * @exception CoreException if the build fails.
78      * The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED}
79      * code, but it could also be any other status code; it might
80      * also be a {@link MultiStatus}.
81      * @exception OperationCanceledException if the operation is canceled.
82      * Cancelation can occur even if no progress monitor is provided.
83      *
84      * @see IProjectDescription
85      * @see IncrementalProjectBuilder#build(int, Map, IProgressMonitor)
86      * @see IncrementalProjectBuilder#FULL_BUILD
87      * @see IncrementalProjectBuilder#INCREMENTAL_BUILD
88      * @see IncrementalProjectBuilder#CLEAN_BUILD
89      * @see IResourceRuleFactory#buildRule()
90      */

91     public void build(int kind, String JavaDoc builderName, Map JavaDoc args, IProgressMonitor monitor) throws CoreException;
92
93     /**
94      * Builds this project. Does nothing if the project is closed.
95      * <p>
96      * Building a project involves executing the commands found
97      * in this project's build spec.
98      * </p>
99      * <p>
100      * This method may change resources; these changes will be reported
101      * in a subsequent resource change event.
102      * </p>
103      * <p>
104      * This method is long-running; progress and cancellation are provided
105      * by the given progress monitor.
106      * </p>
107      *
108      * @param kind the kind of build being requested. Valid values are:
109      * <ul>
110      * <li> <code>IncrementalProjectBuilder.FULL_BUILD</code> - indicates a full build.</li>
111      * <li> <code>IncrementalProjectBuilder.INCREMENTAL_BUILD</code> - indicates an incremental build.</li>
112      * <li><code>CLEAN_BUILD</code>- indicates a clean request. Clean does
113      * not actually build anything, but rather discards all problems and build states.
114      * </ul>
115      * @param monitor a progress monitor, or <code>null</code> if progress
116      * reporting is not desired
117      * @exception CoreException if the build fails.
118      * The status contained in the exception may be a generic <code>BUILD_FAILED</code>
119      * code, but it could also be any other status code; it might
120      * also be a multi-status.
121      * @exception OperationCanceledException if the operation is canceled.
122      * Cancelation can occur even if no progress monitor is provided.
123      *
124      * @see IProjectDescription
125      * @see IncrementalProjectBuilder#FULL_BUILD
126      * @see IncrementalProjectBuilder#INCREMENTAL_BUILD
127      * @see IResourceRuleFactory#buildRule()
128      */

129     public void build(int kind, IProgressMonitor monitor) throws CoreException;
130
131     /**
132      * Closes this project. The project need not be open. Closing
133      * a closed project does nothing.
134      * <p>
135      * Closing a project involves ensuring that all important project-related
136      * state is safely stored on disk, and then discarding the in-memory
137      * representation of its resources and other volatile state,
138      * including session properties.
139      * After this method, the project continues to exist in the workspace
140      * but its member resources (and their members, etc.) do not.
141      * A closed project can later be re-opened.
142      * </p>
143      * <p>
144      * This method changes resources; these changes will be reported
145      * in a subsequent resource change event that includes
146      * an indication that this project has been closed and its members
147      * have been removed.
148      * </p>
149      * <p>
150      * This method is long-running; progress and cancellation are provided
151      * by the given progress monitor.
152      * </p>
153      *
154      * @param monitor a progress monitor, or <code>null</code> if progress
155      * reporting is not desired
156      * @exception CoreException if this method fails. Reasons include:
157      * <ul>
158      * <li> This resource does not exist.</li>
159      * <li> Resource changes are disallowed during certain types of resource change
160      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
161      * </ul>
162      * @exception OperationCanceledException if the operation is canceled.
163      * Cancelation can occur even if no progress monitor is provided.
164      * @see #open(IProgressMonitor)
165      * @see #isOpen()
166      * @see IResourceRuleFactory#modifyRule(IResource)
167      */

168     public void close(IProgressMonitor monitor) throws CoreException;
169
170     /**
171      * Creates a new project resource in the workspace using the given project
172      * description. Upon successful completion, the project will exist but be closed.
173      * <p>
174      * Newly created projects have no session or persistent properties.
175      * </p>
176      * <p>
177      * If the project content area given in the project description does not
178      * contain a project description file, a project description file is written
179      * in the project content area with the natures, build spec, comment, and
180      * referenced projects as specified in the given project description.
181      * If there is an existing project description file, it is not overwritten. In either
182      * case, this method does not cause natures to be configured.
183      * </p>
184      * <p>
185      * This method changes resources; these changes will be reported
186      * in a subsequent resource change event, including an indication
187      * that the project has been added to the workspace.
188      * </p>
189      * <p>
190      * This method is long-running; progress and cancellation are provided
191      * by the given progress monitor.
192      * </p>
193      *
194      * @param description the project description
195      * @param monitor a progress monitor, or <code>null</code> if progress
196      * reporting is not desired
197      * @exception CoreException if this method fails. Reasons include:
198      * <ul>
199      * <li> This project already exists in the workspace.</li>
200      * <li> The name of this resource is not valid (according to
201      * <code>IWorkspace.validateName</code>).</li>
202      * <li> The project location is not valid (according to
203      * <code>IWorkspace.validateProjectLocation</code>).</li>
204      * <li> The project description file could not be created in the project
205      * content area.</li>
206      * <li> Resource changes are disallowed during certain types of resource change
207      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
208      * </ul>
209      * @exception OperationCanceledException if the operation is canceled.
210      * Cancelation can occur even if no progress monitor is provided.
211      *
212      * @see IWorkspace#validateProjectLocation(IProject, IPath)
213      * @see IResourceRuleFactory#createRule(IResource)
214      */

215     public void create(IProjectDescription description, IProgressMonitor monitor) throws CoreException;
216
217     /**
218      * Creates a new project resource in the workspace with files in the default
219      * location in the local file system. Upon successful completion, the project
220      * will exist but be closed.
221      * <p>
222      * Newly created projects have no session or persistent properties.
223      * </p>
224      * <p>
225      * If the project content area does not contain a project description file,
226      * an initial project description file is written in the project content area
227      * with the following information:
228      * <ul>
229      * <li>no references to other projects</li>
230      * <li>no natures</li>
231      * <li>an empty build spec</li>
232      * <li>an empty comment</li>
233      * </ul>
234      * If there is an existing project description file, it is not overwritten.
235      * </p>
236      * <p>
237      * This method changes resources; these changes will be reported
238      * in a subsequent resource change event, including an indication
239      * that this project has been added to the workspace.
240      * </p>
241      * <p>
242      * This method is long-running; progress and cancellation are provided
243      * by the given progress monitor.
244      * </p>
245      *
246      * @param monitor a progress monitor, or <code>null</code> if progress
247      * reporting is not desired
248      * @exception CoreException if this method fails. Reasons include:
249      * <ul>
250      * <li> This project already exists in the workspace.</li>
251      * <li> The name of this resource is not valid (according to
252      * <code>IWorkspace.validateName</code>).</li>
253      * <li> The project location is not valid (according to
254      * <code>IWorkspace.validateProjectLocation</code>).</li>
255      * <li> The project description file could not be created in the project
256      * content area.</li>
257      * <li> Resource changes are disallowed during certain types of resource change
258      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
259      * </ul>
260      * @exception OperationCanceledException if the operation is canceled.
261      * Cancelation can occur even if no progress monitor is provided.
262      *
263      * @see IWorkspace#validateProjectLocation(IProject, IPath)
264      * @see IResourceRuleFactory#createRule(IResource)
265      */

266     public void create(IProgressMonitor monitor) throws CoreException;
267
268     /**
269      * Deletes this project from the workspace.
270      * No action is taken if this project does not exist.
271      * <p>
272      * This is a convenience method, fully equivalent to:
273      * <pre>
274      * delete(
275      * (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT )
276      * | (force ? FORCE : IResource.NONE),
277      * monitor);
278      * </pre>
279      * </p>
280      * <p>
281      * This method is long-running; progress and cancellation are provided
282      * by the given progress monitor.
283      * </p>
284      *
285      * @param deleteContent a flag controlling how whether content is
286      * aggressively deleted
287      * @param force a flag controlling whether resources that are not
288      * in sync with the local file system will be tolerated
289      * @param monitor a progress monitor, or <code>null</code> if progress
290      * reporting is not desired
291      * @exception CoreException if this method fails. Reasons include:
292      * <ul>
293      * <li> This project could not be deleted.</li>
294      * <li> This project's contents could not be deleted.</li>
295      * <li> Resource changes are disallowed during certain types of resource change
296      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
297      * </ul>
298      * @exception OperationCanceledException if the operation is canceled.
299      * Cancelation can occur even if no progress monitor is provided.
300      * @see IResource#delete(int, IProgressMonitor)
301      * @see #open(IProgressMonitor)
302      * @see #close(IProgressMonitor)
303      * @see IResource#delete(int,IProgressMonitor)
304      * @see IResourceRuleFactory#deleteRule(IResource)
305      */

306     public void delete(boolean deleteContent, boolean force, IProgressMonitor monitor) throws CoreException;
307     
308     /**
309      * Returns this project's content type matcher. This content type matcher takes
310      * project specific preferences and nature-content type associations into
311      * account.
312      *
313      * @return the content type matcher for this project
314      * @exception CoreException if this method fails. Reasons include:
315      * <ul>
316      * <li> This project does not exist.</li>
317      * <li> This project is not open.</li>
318      * </ul>
319      * @see IContentTypeMatcher
320      * @since 3.1
321      */

322     public IContentTypeMatcher getContentTypeMatcher() throws CoreException;
323
324     /**
325      * Returns the description for this project.
326      * The returned value is a copy and cannot be used to modify
327      * this project. The returned value is suitable for use in creating,
328      * copying and moving other projects.
329      *
330      * @return the description for this project
331      * @exception CoreException if this method fails. Reasons include:
332      * <ul>
333      * <li> This project does not exist.</li>
334      * <li> This project is not open.</li>
335      * </ul>
336      * @see #create(IProgressMonitor)
337      * @see #create(IProjectDescription, IProgressMonitor)
338      * @see IResource#copy(IProjectDescription, int, IProgressMonitor)
339      * @see #move(IProjectDescription, boolean, IProgressMonitor)
340      */

341     public IProjectDescription getDescription() throws CoreException;
342
343     /**
344      * Returns a handle to the file with the given name in this project.
345      * <p>
346      * This is a resource handle operation; neither the resource nor
347      * the result need exist in the workspace.
348      * The validation check on the resource name/path is not done
349      * when the resource handle is constructed; rather, it is done
350      * automatically as the resource is created.
351      * </p>
352      *
353      * @param name the string name of the member file
354      * @return the (handle of the) member file
355      * @see #getFolder(String)
356      */

357     public IFile getFile(String JavaDoc name);
358
359     /**
360      * Returns a handle to the folder with the given name in this project.
361      * <p>
362      * This is a resource handle operation; neither the container
363      * nor the result need exist in the workspace.
364      * The validation check on the resource name/path is not done
365      * when the resource handle is constructed; rather, it is done
366      * automatically as the resource is created.
367      * </p>
368      *
369      * @param name the string name of the member folder
370      * @return the (handle of the) member folder
371      * @see #getFile(String)
372      */

373     public IFolder getFolder(String JavaDoc name);
374
375     /**
376      * Returns the specified project nature for this project or <code>null</code> if
377      * the project nature has not been added to this project.
378      * Clients may downcast to a more concrete type for more nature-specific methods.
379      * The documentation for a project nature specifies any such additional protocol.
380      * <p>
381      * This may cause the plug-in that provides the given nature to be activated.
382      * </p>
383      *
384      * @param natureId the fully qualified nature extension identifier, formed
385      * by combining the nature extension id with the id of the declaring plug-in.
386      * (e.g. <code>"com.example.acmeplugin.coolnature"</code>)
387      * @return the project nature object
388      * @exception CoreException if this method fails. Reasons include:
389      * <ul>
390      * <li> This project does not exist.</li>
391      * <li> This project is not open.</li>
392      * <li> The project nature extension could not be found.</li>
393      * </ul>
394      */

395     public IProjectNature getNature(String JavaDoc natureId) throws CoreException;
396
397     /**
398      * Returns the location in the local file system of the project-specific
399      * working data area for use by the given plug-in or <code>null</code>
400      * if the project does not exist.
401      * <p>
402      * The content, structure, and management of this area is
403      * the responsibility of the plug-in. This area is deleted when the
404      * project is deleted.
405      * </p><p>
406      * This project needs to exist but does not need to be open.
407      * </p>
408      * @param plugin the plug-in
409      * @return a local file system path
410      * @deprecated Use <code>IProject.getWorkingLocation(plugin.getUniqueIdentifier())</code>.
411      */

412     public IPath getPluginWorkingLocation(IPluginDescriptor plugin);
413
414     /**
415      * Returns the location in the local file system of the project-specific
416      * working data area for use by the bundle/plug-in with the given identifier,
417      * or <code>null</code> if the project does not exist.
418      * <p>
419      * The content, structure, and management of this area is
420      * the responsibility of the bundle/plug-in. This area is deleted when the
421      * project is deleted.
422      * </p><p>
423      * This project needs to exist but does not need to be open.
424      * </p>
425      * @param id the bundle or plug-in's identifier
426      * @return a local file system path
427      * @since 3.0
428      */

429     public IPath getWorkingLocation(String JavaDoc id);
430
431     /**
432      * Returns the projects referenced by this project. This includes
433      * both the static and dynamic references of this project.
434      * The returned projects need not exist in the workspace.
435      * The result will not contain duplicates. Returns an empty
436      * array if there are no referenced projects.
437      *
438      * @return a list of projects
439      * @exception CoreException if this method fails. Reasons include:
440      * <ul>
441      * <li> This project does not exist.</li>
442      * <li> This project is not open.</li>
443      * </ul>
444      * @see IProjectDescription#getReferencedProjects()
445      * @see IProjectDescription#getDynamicReferences()
446      */

447     public IProject[] getReferencedProjects() throws CoreException;
448
449     /**
450      * Returns the list of all open projects which reference
451      * this project. This project may or may not exist. Returns
452      * an empty array if there are no referencing projects.
453      *
454      * @return a list of open projects referencing this project
455      */

456     public IProject[] getReferencingProjects();
457
458     /**
459      * Returns whether the project nature specified by the given
460      * nature extension id has been added to this project.
461      *
462      * @param natureId the nature extension identifier
463      * @return <code>true</code> if the project has the given nature
464      * @exception CoreException if this method fails. Reasons include:
465      * <ul>
466      * <li> This project does not exist.</li>
467      * <li> This project is not open.</li>
468      * </ul>
469      */

470     public boolean hasNature(String JavaDoc natureId) throws CoreException;
471
472     /**
473      * Returns true if the project nature specified by the given
474      * nature extension id is enabled for this project, and false otherwise.
475      * <p>
476      * <ul>Reasons for a nature not to be enabled include:
477      * <li> The nature is not available in the install.</li>
478      * <li> The nature has not been added to this project.</li>
479      * <li> The nature has a prerequisite that is not enabled
480      * for this project.</li>
481      * <li> The nature specifies "one-of-nature" membership in
482      * a set, and there is another nature on this project belonging
483      * to that set.</li>
484      * <li> The prerequisites for the nature form a cycle.</li>
485      * </ul>
486      * </p>
487      * @param natureId the nature extension identifier
488      * @return <code>true</code> if the given nature is enabled for this project
489      * @exception CoreException if this method fails. Reasons include:
490      * <ul>
491      * <li> This project does not exist.</li>
492      * <li> This project is not open.</li>
493      * </ul>
494      * @since 2.0
495      * @see IWorkspace#validateNatureSet(String[])
496      */

497     public boolean isNatureEnabled(String JavaDoc natureId) throws CoreException;
498
499     /**
500      * Returns whether this project is open.
501      * <p>
502      * A project must be opened before it can be manipulated.
503      * A closed project is passive and has a minimal memory
504      * footprint; a closed project has no members.
505      * </p>
506      *
507      * @return <code>true</code> if this project is open, <code>false</code> if
508      * this project is closed or does not exist
509      * @see #open(IProgressMonitor)
510      * @see #close(IProgressMonitor)
511      */

512     public boolean isOpen();
513
514     /**
515      * Renames this project so that it is located at the name in
516      * the given description.
517      * <p>
518      * This is a convenience method, fully equivalent to:
519      * <pre>
520      * move(description, (force ? FORCE : IResource.NONE), monitor);
521      * </pre>
522      * </p>
523      * <p>
524      * This method changes resources; these changes will be reported
525      * in a subsequent resource change event that will include
526      * an indication that the resource has been removed from its parent
527      * and that a corresponding resource has been added to its new parent.
528      * Additional information provided with resource delta shows that these
529      * additions and removals are related.
530      * </p>
531      * <p>
532      * This method is long-running; progress and cancellation are provided
533      * by the given progress monitor.
534      * </p>
535      *
536      * @param description the description for the destination project
537      * @param force a flag controlling whether resources that are not
538      * in sync with the local file system will be tolerated
539      * @param monitor a progress monitor, or <code>null</code> if progress
540      * reporting is not desired
541      * @exception CoreException if this resource could not be moved. Reasons include:
542      * <ul>
543      * <li> This resource is not accessible.</li>
544      * <li> This resource or one of its descendents is not local.</li>
545      * <li> This resource or one of its descendents is out of sync with the local file system
546      * and <code>force</code> is <code>false</code>.</li>
547      * <li> The workspace and the local file system are out of sync
548      * at the destination resource or one of its descendents.</li>
549      * <li> Resource changes are disallowed during certain types of resource change
550      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
551      * </ul>
552      * @exception OperationCanceledException if the operation is canceled.
553      * Cancelation can occur even if no progress monitor is provided.
554      * @see IResourceDelta#getFlags()
555      * @see IResource#move(IProjectDescription,int,IProgressMonitor)
556      * @see IResourceRuleFactory#moveRule(IResource, IResource)
557      */

558     public void move(IProjectDescription description, boolean force, IProgressMonitor monitor) throws CoreException;
559
560     /**
561      * Opens this project. No action is taken if the project is already open.
562      * <p>
563      * Opening a project constructs an in-memory representation
564      * of its resources from information stored on disk.
565      * </p>
566      * <p>
567      * The <code>BACKGROUND_REFRESH</code> update flag controls how
568      * this method behaves when a project is opened for the first time on a location
569      * that has existing resources on disk. If this flag is specified, resources on disk
570      * will be added to the project in the background after this method returns.
571      * Child resources of the project may not be available until this background
572      * refresh completes. If this flag is not specified, resources on disk are added
573      * to the project in the foreground before this method returns.
574      * </p>
575      * This method changes resources; these changes will be reported
576      * in a subsequent resource change event that includes
577      * an indication that the project has been opened and its resources
578      * have been added to the tree. If the <code>BACKGROUND_REFRESH</code>
579      * update flag is specified, multiple resource change events may occur as
580      * resources on disk are discovered and added to the tree.
581      * </p>
582      * <p>
583      * This method is long-running; progress and cancellation are provided
584      * by the given progress monitor.
585      * </p>
586      *
587      * @param monitor a progress monitor, or <code>null</code> if progress
588      * reporting is not desired
589      * @exception CoreException if this method fails. Reasons include:
590      * <ul>
591      * <li> Resource changes are disallowed during certain types of resource change
592      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
593      * </ul>
594      * @exception OperationCanceledException if the operation is canceled.
595      * Cancelation can occur even if no progress monitor is provided.
596      * @see #close(IProgressMonitor)
597      * @see IResource#BACKGROUND_REFRESH
598      * @see IResourceRuleFactory#modifyRule(IResource)
599      * @since 3.1
600      */

601     public void open(int updateFlags, IProgressMonitor monitor) throws CoreException;
602     
603     /**
604      * Opens this project. No action is taken if the project is already open.
605      * <p>
606      * This is a convenience method, fully equivalent to
607      * <code>open(IResource.NONE, monitor)</code>.
608      * </p>
609      * <p>
610      * This method changes resources; these changes will be reported
611      * in a subsequent resource change event that includes
612      * an indication that the project has been opened and its resources
613      * have been added to the tree.
614      * </p>
615      * <p>
616      * This method is long-running; progress and cancellation are provided
617      * by the given progress monitor.
618      * </p>
619      *
620      * @param monitor a progress monitor, or <code>null</code> if progress
621      * reporting is not desired
622      * @exception CoreException if this method fails. Reasons include:
623      * <ul>
624      * <li> Resource changes are disallowed during certain types of resource change
625      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
626      * </ul>
627      * @exception OperationCanceledException if the operation is canceled.
628      * Cancelation can occur even if no progress monitor is provided.
629      * @see #close(IProgressMonitor)
630      * @see IResourceRuleFactory#modifyRule(IResource)
631      */

632     public void open(IProgressMonitor monitor) throws CoreException;
633
634     /**
635      * Changes this project resource to match the given project
636      * description. This project should exist and be open.
637      * <p>
638      * This is a convenience method, fully equivalent to:
639      * <pre>
640      * setDescription(description, KEEP_HISTORY, monitor);
641      * </pre>
642      * </p>
643      * <p>
644      * This method changes resources; these changes will be reported
645      * in a subsequent resource change event, including an indication
646      * that the project's content has changed.
647      * </p>
648      * <p>
649      * This method is long-running; progress and cancellation are provided
650      * by the given progress monitor.
651      * </p>
652      *
653      * @param description the project description
654      * @param monitor a progress monitor, or <code>null</code> if progress
655      * reporting is not desired
656      * @exception CoreException if this method fails. Reasons include:
657      * <ul>
658      * <li> This project does not exist in the workspace.</li>
659      * <li> This project is not open.</li>
660      * <li> The location in the local file system corresponding to the project
661      * description file is occupied by a directory.</li>
662      * <li> The workspace is out of sync with the project description file
663      * in the local file system .</li>
664      * <li> Resource changes are disallowed during certain types of resource change
665      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
666      * <li> The file modification validator disallowed the change.</li>
667      * </ul>
668      * @exception OperationCanceledException if the operation is canceled.
669      * Cancelation can occur even if no progress monitor is provided.
670      *
671      * @see #getDescription()
672      * @see IProjectNature#configure()
673      * @see IProjectNature#deconfigure()
674      * @see #setDescription(IProjectDescription,int,IProgressMonitor)
675      * @see IResourceRuleFactory#modifyRule(IResource)
676      */

677     public void setDescription(IProjectDescription description, IProgressMonitor monitor) throws CoreException;
678
679     /**
680      * Changes this project resource to match the given project
681      * description. This project should exist and be open.
682      * <p>
683      * The given project description is used to change the project's
684      * natures, build spec, comment, and referenced projects.
685      * The name and location of a project cannot be changed using this method;
686      * these settings in the project description are ignored. To change a project's
687      * name or location, use {@link IResource#move(IProjectDescription, int, IProgressMonitor)}.
688      * The project's session and persistent properties are not affected.
689      * </p>
690      * <p>
691      * If the new description includes nature ids of natures that the project
692      * did not have before, these natures will be configured in automatically,
693      * which involves instantiating the project nature and calling
694      * {@link IProjectNature#configure()} on it. An internal reference to the
695      * nature object is retained, and will be returned on subsequent calls to
696      * <code>getNature</code> for the specified nature id. Similarly, any natures
697      * the project had which are no longer required will be automatically
698      * de-configured by calling {@link IProjectNature#deconfigure}
699      * on the nature object and letting go of the internal reference to it.
700      * </p>
701      * <p>
702      * The <code>FORCE</code> update flag controls how this method deals with
703      * cases where the workspace is not completely in sync with the local file
704      * system. If <code>FORCE</code> is not specified, the method will only attempt
705      * to overwrite the project's description file in the local file system
706      * provided it is in sync with the workspace. This option ensures there is no
707      * unintended data loss; it is the recommended setting.
708      * However, if <code>FORCE</code> is specified, an attempt will be made
709      * to write the project description file in the local file system, overwriting
710      * any existing one if need be.
711      * </p>
712      * <p>
713      * The <code>KEEP_HISTORY</code> update flag controls whether or not a copy of
714      * current contents of the project description file should be captured in the
715      * workspace's local history. The local history mechanism serves as a safety net
716      * to help the user recover from mistakes that might otherwise result in data
717      * loss. Specifying <code>KEEP_HISTORY</code> is recommended. Note that local
718      * history is maintained with each individual project, and gets discarded when
719      * a project is deleted from the workspace.
720      * </p>
721      * <p>
722      * The <code>AVOID_NATURE_CONFIG</code> update flag controls whether or
723      * not added and removed natures should be configured or de-configured. If this
724      * flag is not specified, then added natures will be configured and removed natures
725      * will be de-configured. If this flag is specified, natures can still be added or
726      * removed, but they will not be configured or de-configured.
727      * </p>
728      * <p>
729      * Update flags other than <code>FORCE</code>, <code>KEEP_HISTORY</code>,
730      * and <code>AVOID_NATURE_CONFIG</code> are ignored.
731      * </p>
732      * <p>
733      * Prior to modifying the project description file, the file modification
734      * validator (if provided by the Team plug-in), will be given a chance to
735      * perform any last minute preparations. Validation is performed by calling
736      * <code>IFileModificationValidator.validateSave</code> on the project
737      * description file. If the validation fails, then this operation will fail.
738      * </p>
739      * <p>
740      * This method changes resources; these changes will be reported
741      * in a subsequent resource change event, including an indication
742      * that the project's content has changed.
743      * </p>
744      * <p>
745      * This method is long-running; progress and cancellation are provided
746      * by the given progress monitor.
747      * </p>
748      *
749      * @param description the project description
750      * @param updateFlags bit-wise or of update flag constants
751      * (<code>FORCE</code>, <code>KEEP_HISTORY</code> and
752      * <code>AVOID_NATURE_CONFIG</code>)
753      * @param monitor a progress monitor, or <code>null</code> if progress
754      * reporting is not desired
755      * @exception CoreException if this method fails. Reasons include:
756      * <ul>
757      * <li> This project does not exist in the workspace.</li>
758      * <li> This project is not open.</li>
759      * <li> The location in the local file system corresponding to the project
760      * description file is occupied by a directory.</li>
761      * <li> The workspace is not in sync with the project
762      * description file in the local file system and <code>FORCE</code> is not
763      * specified.</li>
764      * <li> Resource changes are disallowed during certain types of resource change
765      * event notification. See <code>IResourceChangeEvent</code> for more details.</li>
766      * <li> The file modification validator disallowed the change.</li>
767      * </ul>
768      * @exception OperationCanceledException if the operation is canceled.
769      * Cancelation can occur even if no progress monitor is provided.
770      *
771      * @see #getDescription()
772      * @see IProjectNature#configure()
773      * @see IProjectNature#deconfigure()
774      * @see IResource#FORCE
775      * @see IResource#KEEP_HISTORY
776      * @see IResource#AVOID_NATURE_CONFIG
777      * @see IResourceRuleFactory#modifyRule(IResource)
778      * @since 2.0
779      */

780     public void setDescription(IProjectDescription description, int updateFlags, IProgressMonitor monitor) throws CoreException;
781
782 }
783
Popular Tags