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  ;
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   builderName, Map   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   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags