/*******************************************************************************
* Copyright (c) 2000, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Francis Lynch (Wind River) - [301563] Save and load tree snapshots
*******************************************************************************/
package org.eclipse.core.resources;
import java.net.URI;
import java.util.Map;
import org.eclipse.core.runtime.*;
import org.eclipse.core.runtime.content.IContentTypeMatcher;
/**
* A project is a type of resource which groups resources into buildable, reusable units.
* <p>
* Features of projects include:
* <ul>
* <li>A project collects together a set of files and folders.</li>
* <li>A project's location controls where the project's resources are stored in the local file
* system.</li>
* <li>A project's build spec controls how building is done on the project.</li>
* <li>A project can carry session and persistent properties.</li>
* <li>A project can be open or closed; a closed project is passive and has a minimal in-memory
* footprint.</li>
* <li>A project can carry references to other projects.</li>
* <li>A project can have one or more project natures.</li>
* </ul>
* </p>
* <p>
* Projects implement the <code>IAdaptable</code> interface; extensions are managed by the
* platform's adapter manager.
* </p>
*
* @see Platform#getAdapterManager()
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IProject extends IContainer, IAdaptable {
/**
* Option constant (value 1) indicating that a snapshot to be loaded or saved contains a
* resource tree (refresh information).
*
* @see #loadSnapshot(int, URI, IProgressMonitor)
* @see #saveSnapshot(int, URI, IProgressMonitor)
* @since 3.6
*/
public static final int SNAPSHOT_TREE= 1;
/**
* Invokes the <code>build</code> method of the specified builder for this project. Does nothing
* if this project is closed. If this project has multiple builders on its build spec matching
* the given name, only the first matching builder will be run.
* <p>
* The builder name is declared in the extension that plugs in to the standard
* <code>org.eclipse.core.resources.builders</code> extension point. The arguments are builder
* specific.
* </p>
* <p>
* This method may change resources; these changes will be reported in a subsequent resource
* change event.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param kind the kind of build being requested. Valid values are:
* <ul>
* <li>{@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.</li>
* <li>{@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental
* build.</li>
* <li>{@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request.
* Clean does not actually build anything, but rather discards all problems and build
* states.</li>
* </ul>
* @param builderName the name of the builder
* @param args a table of builder-specific arguments keyed by argument name (key type:
* <code>String</code>, value type: <code>String</code>); <code>null</code> is
* equivalent to an empty map
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if the build fails. The status contained in the exception may be a
* generic {@link IResourceStatus#BUILD_FAILED} code, but it could also be any
* other status code; it might also be a {@link MultiStatus}.
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see IProjectDescription
* @see IncrementalProjectBuilder#build(int, Map, IProgressMonitor)
* @see IncrementalProjectBuilder#FULL_BUILD
* @see IncrementalProjectBuilder#INCREMENTAL_BUILD
* @see IncrementalProjectBuilder#CLEAN_BUILD
* @see IResourceRuleFactory#buildRule()
*/
public void build(int kind, String builderName, Map args, IProgressMonitor monitor) throws CoreException;
/**
* Builds this project. Does nothing if the project is closed.
* <p>
* Building a project involves executing the commands found in this project's build spec.
* </p>
* <p>
* This method may change resources; these changes will be reported in a subsequent resource
* change event.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param kind the kind of build being requested. Valid values are:
* <ul>
* <li> <code>IncrementalProjectBuilder.FULL_BUILD</code> - indicates a full build.</li>
* <li> <code>IncrementalProjectBuilder.INCREMENTAL_BUILD</code> - indicates an
* incremental build.</li>
* <li><code>CLEAN_BUILD</code>- indicates a clean request. Clean does not actually
* build anything, but rather discards all problems and build states.
* </ul>
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if the build fails. The status contained in the exception may be a
* generic <code>BUILD_FAILED</code> code, but it could also be any other status
* code; it might also be a multi-status.
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see IProjectDescription
* @see IncrementalProjectBuilder#FULL_BUILD
* @see IncrementalProjectBuilder#INCREMENTAL_BUILD
* @see IResourceRuleFactory#buildRule()
*/
public void build(int kind, IProgressMonitor monitor) throws CoreException;
/**
* Closes this project. The project need not be open. Closing a closed project does nothing.
* <p>
* Closing a project involves ensuring that all important project-related state is safely stored
* on disk, and then discarding the in-memory representation of its resources and other volatile
* state, including session properties. After this method, the project continues to exist in the
* workspace but its member resources (and their members, etc.) do not. A closed project can
* later be re-opened.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event that includes an indication that this project has been closed and its members have been
* removed.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This resource does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see #open(IProgressMonitor)
* @see #isOpen()
* @see IResourceRuleFactory#modifyRule(IResource)
*/
public void close(IProgressMonitor monitor) throws CoreException;
/**
* Creates a new project resource in the workspace using the given project description. Upon
* successful completion, the project will exist but be closed.
* <p>
* Newly created projects have no session or persistent properties.
* </p>
* <p>
* If the project content area given in the project description does not contain a project
* description file, a project description file is written in the project content area with the
* natures, build spec, comment, and referenced projects as specified in the given project
* description. If there is an existing project description file, it is not overwritten. In
* either case, this method does not cause natures to be configured.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that the project has been added to the workspace.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param description the project description
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project already exists in the workspace.</li>
* <li>The name of this resource is not valid (according to
* <code>IWorkspace.validateName</code>).</li>
* <li>The project location is not valid (according to
* <code>IWorkspace.validateProjectLocation</code>).</li>
* <li>The project description file could not be created in the project content
* area.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see IWorkspace#validateProjectLocation(IProject, IPath)
* @see IResourceRuleFactory#createRule(IResource)
*/
public void create(IProjectDescription description, IProgressMonitor monitor) throws CoreException;
/**
* Creates a new project resource in the workspace with files in the default location in the
* local file system. Upon successful completion, the project will exist but be closed.
* <p>
* Newly created projects have no session or persistent properties.
* </p>
* <p>
* If the project content area does not contain a project description file, an initial project
* description file is written in the project content area with the following information:
* <ul>
* <li>no references to other projects</li>
* <li>no natures</li>
* <li>an empty build spec</li>
* <li>an empty comment</li>
* </ul>
* If there is an existing project description file, it is not overwritten.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this project has been added to the workspace.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project already exists in the workspace.</li>
* <li>The name of this resource is not valid (according to
* <code>IWorkspace.validateName</code>).</li>
* <li>The project location is not valid (according to
* <code>IWorkspace.validateProjectLocation</code>).</li>
* <li>The project description file could not be created in the project content
* area.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see IWorkspace#validateProjectLocation(IProject, IPath)
* @see IResourceRuleFactory#createRule(IResource)
*/
public void create(IProgressMonitor monitor) throws CoreException;
/**
* Creates a new project resource in the workspace using the given project description. Upon
* successful completion, the project will exist but be closed.
* <p>
* Newly created projects have no session or persistent properties.
* </p>
* <p>
* If the project content area given in the project description does not contain a project
* description file, a project description file is written in the project content area with the
* natures, build spec, comment, and referenced projects as specified in the given project
* description. If there is an existing project description file, it is not overwritten. In
* either case, this method does not cause natures to be configured.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that the project has been added to the workspace.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
* <p>
* The {@link IResource#HIDDEN} update flag indicates that this resource should immediately be
* set as a hidden resource. Specifying this flag is equivalent to atomically calling
* {@link IResource#setHidden(boolean)} with a value of <code>true</code> immediately after
* creating the resource.
* </p>
* <p>
* Update flags other than those listed above are ignored.
* </p>
*
* @param description the project description
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project already exists in the workspace.</li>
* <li>The name of this resource is not valid (according to
* <code>IWorkspace.validateName</code>).</li>
* <li>The project location is not valid (according to
* <code>IWorkspace.validateProjectLocation</code>).</li>
* <li>The project description file could not be created in the project content
* area.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see IWorkspace#validateProjectLocation(IProject, IPath)
* @see IResourceRuleFactory#createRule(IResource)
*
* @since 3.4
*/
public void create(IProjectDescription description, int updateFlags, IProgressMonitor monitor) throws CoreException;
/**
* Deletes this project from the workspace. No action is taken if this project does not exist.
* <p>
* This is a convenience method, fully equivalent to:
*
* <pre>
* delete(
* (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT)
* | (force ? FORCE : IResource.NONE),
* monitor);
* </pre>
*
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param deleteContent a flag controlling how whether content is aggressively deleted
* @param force a flag controlling whether resources that are not in sync with the local file
* system will be tolerated
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project could not be deleted.</li>
* <li>This project's contents could not be deleted.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#delete(int, IProgressMonitor)
* @see #open(IProgressMonitor)
* @see #close(IProgressMonitor)
* @see IResource#delete(int,IProgressMonitor)
* @see IResourceRuleFactory#deleteRule(IResource)
*/
public void delete(boolean deleteContent, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Returns this project's content type matcher. This content type matcher takes project specific
* preferences and nature-content type associations into account.
*
* @return the content type matcher for this project
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* </ul>
* @see IContentTypeMatcher
* @since 3.1
*/
public IContentTypeMatcher getContentTypeMatcher() throws CoreException;
/**
* Returns the description for this project. The returned value is a copy and cannot be used to
* modify this project. The returned value is suitable for use in creating, copying and moving
* other projects.
*
* @return the description for this project
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* </ul>
* @see #create(IProgressMonitor)
* @see #create(IProjectDescription, IProgressMonitor)
* @see IResource#copy(IProjectDescription, int, IProgressMonitor)
* @see #move(IProjectDescription, boolean, IProgressMonitor)
*/
public IProjectDescription getDescription() throws CoreException;
/**
* Returns a handle to the file with the given name in this project.
* <p>
* This is a resource handle operation; neither the resource nor the result need exist in the
* workspace. The validation check on the resource name/path is not done when the resource
* handle is constructed; rather, it is done automatically as the resource is created.
* </p>
*
* @param name the string name of the member file
* @return the (handle of the) member file
* @see #getFolder(String)
*/
public IFile getFile(String name);
/**
* Returns a handle to the folder with the given name in this project.
* <p>
* This is a resource handle operation; neither the container nor the result need exist in the
* workspace. The validation check on the resource name/path is not done when the resource
* handle is constructed; rather, it is done automatically as the resource is created.
* </p>
*
* @param name the string name of the member folder
* @return the (handle of the) member folder
* @see #getFile(String)
*/
public IFolder getFolder(String name);
/**
* Returns the specified project nature for this project or <code>null</code> if the project
* nature has not been added to this project. Clients may downcast to a more concrete type for
* more nature-specific methods. The documentation for a project nature specifies any such
* additional protocol.
* <p>
* This may cause the plug-in that provides the given nature to be activated.
* </p>
*
* @param natureId the fully qualified nature extension identifier, formed by combining the
* nature extension id with the id of the declaring plug-in. (e.g.
* <code>"com.example.acmeplugin.coolnature"</code>)
* @return the project nature object
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* <li>The project nature extension could not be found.</li>
* </ul>
*/
public IProjectNature getNature(String natureId) throws CoreException;
/**
* Returns the location in the local file system of the project-specific working data area for
* use by the given plug-in or <code>null</code> if the project does not exist.
* <p>
* The content, structure, and management of this area is the responsibility of the plug-in.
* This area is deleted when the project is deleted.
* </p>
* <p>
* This project needs to exist but does not need to be open.
* </p>
*
* @param plugin the plug-in
* @return a local file system path
* @deprecated Use <code>IProject.getWorkingLocation(plugin.getUniqueIdentifier())</code>.
*/
public IPath getPluginWorkingLocation(IPluginDescriptor plugin);
/**
* Returns the location in the local file system of the project-specific working data area for
* use by the bundle/plug-in with the given identifier, or <code>null</code> if the project does
* not exist.
* <p>
* The content, structure, and management of this area is the responsibility of the
* bundle/plug-in. This area is deleted when the project is deleted.
* </p>
* <p>
* This project needs to exist but does not need to be open.
* </p>
*
* @param id the bundle or plug-in's identifier
* @return a local file system path
* @since 3.0
*/
public IPath getWorkingLocation(String id);
/**
* Returns the projects referenced by this project. This includes both the static and dynamic
* references of this project. The returned projects need not exist in the workspace. The result
* will not contain duplicates. Returns an empty array if there are no referenced projects.
*
* @return a list of projects
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* </ul>
* @see IProjectDescription#getReferencedProjects()
* @see IProjectDescription#getDynamicReferences()
*/
public IProject[] getReferencedProjects() throws CoreException;
/**
* Returns the list of all open projects which reference this project. This project may or may
* not exist. Returns an empty array if there are no referencing projects.
*
* @return a list of open projects referencing this project
*/
public IProject[] getReferencingProjects();
/**
* Returns whether the project nature specified by the given nature extension id has been added
* to this project.
*
* @param natureId the nature extension identifier
* @return <code>true</code> if the project has the given nature
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* </ul>
*/
public boolean hasNature(String natureId) throws CoreException;
/**
* Returns true if the project nature specified by the given nature extension id is enabled for
* this project, and false otherwise.
* <p>
* <ul>
* Reasons for a nature not to be enabled include:
* <li>The nature is not available in the install.</li>
* <li>The nature has not been added to this project.</li>
* <li>The nature has a prerequisite that is not enabled for this project.</li>
* <li>The nature specifies "one-of-nature" membership in a set, and there is another nature on
* this project belonging to that set.</li>
* <li>The prerequisites for the nature form a cycle.</li>
* </ul>
* </p>
*
* @param natureId the nature extension identifier
* @return <code>true</code> if the given nature is enabled for this project
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist.</li>
* <li>This project is not open.</li>
* </ul>
* @since 2.0
* @see IWorkspace#validateNatureSet(String[])
*/
public boolean isNatureEnabled(String natureId) throws CoreException;
/**
* Returns whether this project is open.
* <p>
* A project must be opened before it can be manipulated. A closed project is passive and has a
* minimal memory footprint; a closed project has no members.
* </p>
*
* @return <code>true</code> if this project is open, <code>false</code> if this project is
* closed or does not exist
* @see #open(IProgressMonitor)
* @see #close(IProgressMonitor)
*/
public boolean isOpen();
/**
* Loads a snapshot of project meta-data from the given location URI. Must be called after the
* project has been created, but before it is opened. The options constant controls what kind of
* snapshot information to load. Valid option values include:
* <ul>
* <li>{@link IProject#SNAPSHOT_TREE} - load resource tree (refresh info)
* </ul>
*
* @param options kind of snapshot information to load
* @param snapshotLocation URI to load from
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>The snapshot was not found at the specified URI.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled.
* @see #saveSnapshot(int, URI, IProgressMonitor)
* @since 3.6
*/
public void loadSnapshot(int options, URI snapshotLocation,
IProgressMonitor monitor) throws CoreException;
/**
* Renames this project so that it is located at the name in the given description.
* <p>
* This is a convenience method, fully equivalent to:
*
* <pre>
* move(description, (force ? FORCE : IResource.NONE), monitor);
* </pre>
*
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event that will include an indication that the resource has been removed from its parent and
* that a corresponding resource has been added to its new parent. Additional information
* provided with resource delta shows that these additions and removals are related.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param description the description for the destination project
* @param force a flag controlling whether resources that are not in sync with the local file
* system will be tolerated
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this resource could not be moved. Reasons include:
* <ul>
* <li>This resource is not accessible.</li>
* <li>This resource or one of its descendents is not local.</li>
* <li>This resource or one of its descendents is out of sync with the local file
* system and <code>force</code> is <code>false</code>.</li>
* <li>The workspace and the local file system are out of sync at the destination
* resource or one of its descendents.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResourceDelta#getFlags()
* @see IResource#move(IProjectDescription,int,IProgressMonitor)
* @see IResourceRuleFactory#moveRule(IResource, IResource)
*/
public void move(IProjectDescription description, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Opens this project. No action is taken if the project is already open.
* <p>
* Opening a project constructs an in-memory representation of its resources from information
* stored on disk.
* </p>
* <p>
* When a project is opened for the first time, initial information about the project's existing
* resources can be obtained in the following ways:
* <ul>
* <li>If a {@link #loadSnapshot(int, URI, IProgressMonitor)} call has been made before the
* open, resources are restored from that file (a file written by
* {@link #saveSnapshot(int, URI, IProgressMonitor)}). When the snapshot includes resource tree
* information and can be loaded without error, no refresh is initiated, so the project's
* resource tree will match what the snapshot provides.
* <li>Otherwise, when the {@link IResource#BACKGROUND_REFRESH} flag is specified, resources on
* disk will be added to the project in the background after this method returns. Child
* resources of the project may not be available until this background refresh completes.
* <li>Otherwise, resource information is obtained with a refresh operation in the foreground,
* before this method returns.
* </ul>
* </p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event that includes an indication that the project has been opened and its resources have
* been added to the tree. If the <code>BACKGROUND_REFRESH</code> update flag is specified,
* multiple resource change events may occur as resources on disk are discovered and added to
* the tree. </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see #close(IProgressMonitor)
* @see IResource#BACKGROUND_REFRESH
* @see IResourceRuleFactory#modifyRule(IResource)
* @since 3.1
*/
public void open(int updateFlags, IProgressMonitor monitor) throws CoreException;
/**
* Opens this project. No action is taken if the project is already open.
* <p>
* This is a convenience method, fully equivalent to <code>open(IResource.NONE, monitor)</code>.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event that includes an indication that the project has been opened and its resources have
* been added to the tree.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see #close(IProgressMonitor)
* @see IResourceRuleFactory#modifyRule(IResource)
*/
public void open(IProgressMonitor monitor) throws CoreException;
/**
* Writes a snapshot of project meta-data into the given location URI. The options constant
* controls what kind of snapshot information to write. Valid option values include:
* <ul>
* <li>{@link IProject#SNAPSHOT_TREE} - save resource tree (refresh info)
* </ul>
*
* @param options kind of snapshot information to save
* @param snapshotLocation URI for saving the snapshot to
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>The URI is not writable or an error occurs writing the data.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled.
* @see #loadSnapshot(int, URI, IProgressMonitor)
* @since 3.6
*/
public void saveSnapshot(int options, URI snapshotLocation,
IProgressMonitor monitor) throws CoreException;
/**
* Changes this project resource to match the given project description. This project should
* exist and be open.
* <p>
* This is a convenience method, fully equivalent to:
*
* <pre>
* setDescription(description, KEEP_HISTORY, monitor);
* </pre>
*
* </p>
* <p>
* This method requires the {@link IWorkspaceRoot} scheduling rule.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that the project's content has changed.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param description the project description
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist in the workspace.</li>
* <li>This project is not open.</li>
* <li>The location in the local file system corresponding to the project
* description file is occupied by a directory.</li>
* <li>The workspace is out of sync with the project description file in the
* local file system .</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* <li>The file modification validator disallowed the change.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see #getDescription()
* @see IProjectNature#configure()
* @see IProjectNature#deconfigure()
* @see #setDescription(IProjectDescription,int,IProgressMonitor)
*/
public void setDescription(IProjectDescription description, IProgressMonitor monitor) throws CoreException;
/**
* Changes this project resource to match the given project description. This project should
* exist and be open.
* <p>
* The given project description is used to change the project's natures, build spec, comment,
* and referenced projects. The name and location of a project cannot be changed using this
* method; these settings in the project description are ignored. To change a project's name or
* location, use {@link IResource#move(IProjectDescription, int, IProgressMonitor)}. The
* project's session and persistent properties are not affected.
* </p>
* <p>
* If the new description includes nature ids of natures that the project did not have before,
* these natures will be configured in automatically, which involves instantiating the project
* nature and calling {@link IProjectNature#configure()} on it. An internal reference to the
* nature object is retained, and will be returned on subsequent calls to <code>getNature</code>
* for the specified nature id. Similarly, any natures the project had which are no longer
* required will be automatically de-configured by calling {@link IProjectNature#deconfigure} on
* the nature object and letting go of the internal reference to it.
* </p>
* <p>
* The <code>FORCE</code> update flag controls how this method deals with cases where the
* workspace is not completely in sync with the local file system. If <code>FORCE</code> is not
* specified, the method will only attempt to overwrite the project's description file in the
* local file system provided it is in sync with the workspace. This option ensures there is no
* unintended data loss; it is the recommended setting. However, if <code>FORCE</code> is
* specified, an attempt will be made to write the project description file in the local file
* system, overwriting any existing one if need be.
* </p>
* <p>
* The <code>KEEP_HISTORY</code> update flag controls whether or not a copy of current contents
* of the project description file should be captured in the workspace's local history. The
* local history mechanism serves as a safety net to help the user recover from mistakes that
* might otherwise result in data loss. Specifying <code>KEEP_HISTORY</code> is recommended.
* Note that local history is maintained with each individual project, and gets discarded when a
* project is deleted from the workspace.
* </p>
* <p>
* The <code>AVOID_NATURE_CONFIG</code> update flag controls whether or not added and removed
* natures should be configured or de-configured. If this flag is not specified, then added
* natures will be configured and removed natures will be de-configured. If this flag is
* specified, natures can still be added or removed, but they will not be configured or
* de-configured.
* </p>
* <p>
* The scheduling rule required for this operation depends on the
* <code>AVOID_NATURE_CONFIG</code> flag. If the flag is specified the
* {@link IResourceRuleFactory#modifyRule} is required; If the flag is not specified, the
* {@link IWorkspaceRoot} scheduling rule is required.
* </p>
* <p>
* Update flags other than <code>FORCE</code>, <code>KEEP_HISTORY</code>, and
* <code>AVOID_NATURE_CONFIG</code> are ignored.
* </p>
* <p>
* Prior to modifying the project description file, the file modification validator (if provided
* by the Team plug-in), will be given a chance to perform any last minute preparations.
* Validation is performed by calling <code>IFileModificationValidator.validateSave</code> on
* the project description file. If the validation fails, then this operation will fail.
* </p>
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that the project's content has changed.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param description the project description
* @param updateFlags bit-wise or of update flag constants (<code>FORCE</code>,
* <code>KEEP_HISTORY</code> and <code>AVOID_NATURE_CONFIG</code>)
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This project does not exist in the workspace.</li>
* <li>This project is not open.</li>
* <li>The location in the local file system corresponding to the project
* description file is occupied by a directory.</li>
* <li>The workspace is not in sync with the project description file in the
* local file system and <code>FORCE</code> is not specified.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* <li>The file modification validator disallowed the change.</li>
* </ul>
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
*
* @see #getDescription()
* @see IProjectNature#configure()
* @see IProjectNature#deconfigure()
* @see IResource#FORCE
* @see IResource#KEEP_HISTORY
* @see IResource#AVOID_NATURE_CONFIG
* @see IResourceRuleFactory#modifyRule(IResource)
* @since 2.0
*/
public void setDescription(IProjectDescription description, int updateFlags, IProgressMonitor monitor) throws CoreException;
}