/*******************************************************************************
 *  Copyright (c) 2000, 2009 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
 *     Red Hat Incorporated - get/setResourceAttribute code
 *     Oakland Software Incorporated - added getSessionProperties and getPersistentProperties
 *******************************************************************************/
package org.eclipse.core.resources;

import java.net.URI;
import java.util.Map;
import org.eclipse.core.runtime.*;
import org.eclipse.core.runtime.jobs.ISchedulingRule;

/**
 * The workspace analog of file system files
 * and directories.  There are exactly four <i>types</i> of resource:
 * files, folders, projects and the workspace root.
 * <p>
 * File resources are similar to files in that they
 * hold data directly.  Folder resources are analogous to directories in that they
 * hold other resources but cannot directly hold data.  Project resources
 * group files and folders into reusable clusters.  The workspace root is the
 * top level resource under which all others reside.
 * </p>
 * <p>
 * Features of resources:
 * <ul>
 * <li><code>IResource</code> objects are <i>handles</i> to state maintained
 *      by a workspace.  That is, resource objects do not actually contain data
 *      themselves but rather represent resource state and give it behavior.  Programmers
 *      are free to manipulate handles for resources that do not exist in a workspace 
 *      but must keep in mind that some methods and operations require that an actual 
 *      resource be available.</li>
 * <li>Resources have two different kinds of properties as detailed below.  All 
 *      properties are keyed by qualified names.</li>
 * <ul>
 * <li>Session properties: Session properties live for the lifetime of one execution of
 *      the workspace.  They are not stored on disk.  They can carry arbitrary
 *      object values.  Clients should be aware that these values are kept in memory
 *      at all times and, as such, the values should not be large.</li>
 * <li>Persistent properties: Persistent properties have string values which are stored
 *      on disk across platform sessions.  The value of a persistent property is a 
 *      string which should be short (i.e., under 2KB). </li>
 * </ul>
 * </li>
 * <li>Resources are identified by type and by their <i>path</i>, which is similar to a file system 
 *      path.  The name of a resource is the last segment of its path. A resource's parent 
 *      is located by removing the last segment (the resource's name) from the resource's full path.</li>
 * <li>Resources can be local or non-local. A non-local resource is one whose
 *      contents and properties have not been fetched from a repository.</li>
 * <li><i>Phantom</i> resources represent incoming additions or outgoing deletions
 *      which have yet to be reconciled with a synchronization partner. </li>
 * </ul>
 * </p>
 * <p>
 * Resources implement the <code>IAdaptable</code> interface;
 *  extensions are managed by the platform's adapter manager.
 * </p>
 *
 * @see IWorkspace
 * @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 IResource extends IAdaptable, ISchedulingRule {

    /*====================================================================
     * Constants defining resource types:  There are four possible resource types
     * and their type constants are in the integer range 1 to 8 as defined below.
     *====================================================================*/

    /** 
     * Type constant (bit mask value 1) which identifies file resources.
     *
     * @see IResource#getType()
     * @see IFile
     */
    public static final int FILE = 0x1;

    /**
     * Type constant (bit mask value 2) which identifies folder resources.
     *
     * @see IResource#getType()
     * @see IFolder
     */
    public static final int FOLDER = 0x2;

    /**
     * Type constant (bit mask value 4) which identifies project resources.
     *
     * @see IResource#getType()
     * @see IProject
     */
    public static final int PROJECT = 0x4;

    /**
     * Type constant (bit mask value 8) which identifies the root resource.
     *
     * @see IResource#getType()
     * @see IWorkspaceRoot
     */
    public static final int ROOT = 0x8;

    /*====================================================================
     * Constants defining the depth of resource tree traversal:
     *====================================================================*/

    /**
     * Depth constant (value 0) indicating this resource, but not any of its members.
     */
    public static final int DEPTH_ZERO = 0;

    /**
     * Depth constant (value 1) indicating this resource and its direct members.
     */
    public static final int DEPTH_ONE = 1;

    /**
     * Depth constant (value 2) indicating this resource and its direct and
     * indirect members at any depth.
     */
    public static final int DEPTH_INFINITE = 2;

    /*====================================================================
     * Constants for update flags for delete, move, copy, open, etc.:
     *====================================================================*/

    /**
     * Update flag constant (bit mask value 1) indicating that the operation
     * should proceed even if the resource is out of sync with the local file
     * system.
     * 
     * @since 2.0
     */
    public static final int FORCE = 0x1;

    /**
     * Update flag constant (bit mask value 2) indicating that the operation
     * should maintain local history by taking snapshots of the contents of
     * files just before being overwritten or deleted.
     * 
     * @see IFile#getHistory(IProgressMonitor)
     * @since 2.0
     */
    public static final int KEEP_HISTORY = 0x2;

    /**
     * Update flag constant (bit mask value 4) indicating that the operation
     * should delete the files and folders of a project.
     * <p>
     * Deleting a project that is open ordinarily deletes all its files and folders, 
     * whereas deleting a project that is closed retains its files and folders.
     * Specifying <code>ALWAYS_DELETE_PROJECT_CONTENT</code> indicates that the contents
     * of a project are to be deleted regardless of whether the project is open or closed
     * at the time; specifying <code>NEVER_DELETE_PROJECT_CONTENT</code> indicates that
     * the contents of a project are to be retained regardless of whether the project
     * is open or closed at the time.
     * </p>
     * 
     * @see #NEVER_DELETE_PROJECT_CONTENT
     * @since 2.0
     */
    public static final int ALWAYS_DELETE_PROJECT_CONTENT = 0x4;

    /**
     * Update flag constant (bit mask value 8) indicating that the operation
     * should preserve the files and folders of a project.
     * <p>
     * Deleting a project that is open ordinarily deletes all its files and folders, 
     * whereas deleting a project that is closed retains its files and folders.
     * Specifying <code>ALWAYS_DELETE_PROJECT_CONTENT</code> indicates that the contents
     * of a project are to be deleted regardless of whether the project is open or closed
     * at the time; specifying <code>NEVER_DELETE_PROJECT_CONTENT</code> indicates that
     * the contents of a project are to be retained regardless of whether the project
     * is open or closed at the time.
     * </p>
     * 
     * @see #ALWAYS_DELETE_PROJECT_CONTENT
     * @since 2.0
     */
    public static final int NEVER_DELETE_PROJECT_CONTENT = 0x8;

    /**
     * Update flag constant (bit mask value 16) indicating that the link creation
     * should proceed even if the local file system file or directory is missing.
     * 
     * @see IFolder#createLink(IPath, int, IProgressMonitor)
     * @see IFile#createLink(IPath, int, IProgressMonitor)
     * @since 2.1
     */
    public static final int ALLOW_MISSING_LOCAL = 0x10;

    /**
     * Update flag constant (bit mask value 32) indicating that a copy or move
     * operation should only copy the link, rather than copy the underlying
     * contents of the linked resource.
     *
     * @see #copy(IPath, int, IProgressMonitor)
     * @see #move(IPath, int, IProgressMonitor)
     * @since 2.1
     */
    public static final int SHALLOW = 0x20;

    /**
     * Update flag constant (bit mask value 64) indicating that setting the
     * project description should not attempt to configure and de-configure
     * natures.
     *
     * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
     * @since 3.0
     */
    public static final int AVOID_NATURE_CONFIG = 0x40;

    /**
     * Update flag constant (bit mask value 128) indicating that opening a
     * project for the first time or creating a linked folder should refresh in the 
     * background.
     *
     * @see IProject#open(int, IProgressMonitor)
     * @see IFolder#createLink(URI, int, IProgressMonitor)
     * @since 3.1
     */
    public static final int BACKGROUND_REFRESH = 0x80;

    /**
     * Update flag constant (bit mask value 256) indicating that a
     * resource should be replaced with a resource of the same name
     * at a different file system location.
     *
     * @see IFile#createLink(URI, int, IProgressMonitor)
     * @see IFolder#createLink(URI, int, IProgressMonitor)
     * @see IResource#move(IProjectDescription, int, IProgressMonitor)
     * @since 3.2
     */
    public static final int REPLACE = 0x100;

    /**
     * Update flag constant (bit mask value 512) indicating that ancestor
     * resources of the target resource should be checked.
     *
     * @see IResource#isLinked(int)
     * @since 3.2
     */
    public static final int CHECK_ANCESTORS = 0x200;

    /**
     * Update flag constant (bit mask value 0x400) indicating that a
     * resource should be marked as derived.
     *
     * @see IFile#create(java.io.InputStream, int, IProgressMonitor)
     * @see IFolder#create(int, boolean, IProgressMonitor)
     * @see IResource#setDerived(boolean)
     * @since 3.2
     */
    public static final int DERIVED = 0x400;

    /**
     * Update flag constant (bit mask value 0x800) indicating that a 
     * resource should be marked as team private.
     *
     * @see IFile#create(java.io.InputStream, int, IProgressMonitor)
     * @see IFolder#create(int, boolean, IProgressMonitor)
     * @see IResource#copy(IPath, int, IProgressMonitor)
     * @see IResource#setTeamPrivateMember(boolean)
     * @since 3.2
     */
    public static final int TEAM_PRIVATE = 0x800;
    
    /**
     * Update flag constant (bit mask value 0x1000) indicating that a 
     * resource should be marked as a hidden resource.
     * 
     * @since 3.4
     */
    public static final int HIDDEN = 0x1000;

    /*====================================================================
     * Other constants:
     *====================================================================*/

    /** 
     * Modification stamp constant (value -1) indicating no modification stamp is
     * available.
     *
     * @see #getModificationStamp()
     */
    public static final int NULL_STAMP = -1;

    /** 
     * General purpose zero-valued bit mask constant. Useful whenever you need to
     * supply a bit mask with no bits set.
     * <p>
     * Example usage:
     * <code>
     * <pre>
     *    delete(IResource.NONE, null)
     * </pre>
     * </code>
     * </p>
     *
     * @since 2.0
     */
    public static final int NONE = 0;

    /**
     * Accepts the given visitor for an optimized traversal. 
     * The visitor's <code>visit</code> method is called, and is provided with a
     * proxy to this resource.  The proxy is a transient object that can be queried
     * very quickly for information about the resource. If the actual resource
     * handle is needed, it can be obtained from the proxy. Requesting the resource
     * handle, or the full path of the resource, will degrade performance of the
     * visit.
     * <p>
     * The entire subtree under the given resource is traversed to infinite depth,
     * unless the visitor ignores a subtree by returning <code>false</code> from its
     * <code>visit</code> method.
     * </p>
     *  <p>No  guarantees are made about the behavior of this method if resources
     * are deleted or added during the traversal of this resource hierarchy.  If
     * resources are deleted during the traversal, they may still be passed to the
     * visitor; if resources are created, they may not be passed to the visitor.  If
     * resources other than the one being visited are modified during the traversal,
     * the resource proxy may contain stale information when that resource is
     * visited.
     * </p>
     <p>
     * If the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified in the member 
     * flags (recommended), only member resources that exist will be visited.
     * If the {@link IContainer#INCLUDE_PHANTOMS} flag is specified, the visit will
     * also include any phantom member resource that the workspace is keeping track of.
     * </p>
     * <p>
     * If the {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not specified
     * (recommended), team private members will not be visited. If the 
     * {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the member
     * flags, team private member resources are visited as well.
     * </p>
     * <p>
     * If the {@link IContainer#INCLUDE_HIDDEN} flag is not specified (recommended), 
     * hidden resources will not be visited. If the {@link IContainer#INCLUDE_HIDDEN} flag is specified 
     * in the member flags, hidden resources are visited as well.
     * </p>
     *
     * @param visitor the visitor
     * @param memberFlags bit-wise or of member flag constants
     *   ({@link IContainer#INCLUDE_PHANTOMS}, {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS}
     *   and {@link IContainer#INCLUDE_HIDDEN}) indicating which members are of interest
     * @exception CoreException if this request fails. Reasons include:
     * <ul>
     * <li> the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified and
     *     this resource does not exist.</li>
     * <li> the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified and
     *     this resource is a project that is not open.</li>
     * <li> The visitor failed with this exception.</li>
     * </ul>
     * @see IContainer#INCLUDE_PHANTOMS
     * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
     * @see IContainer#INCLUDE_HIDDEN
     * @see IResource#isPhantom()
     * @see IResource#isTeamPrivateMember()
     * @see IResourceProxyVisitor#visit(IResourceProxy)
     * @since 2.1
     */
    public void accept(final IResourceProxyVisitor visitor, int memberFlags) throws CoreException;

    /**
     * Accepts the given visitor.
     * The visitor's <code>visit</code> method is called with this
     * resource. If the visitor returns <code>true</code>, this method
     * visits this resource's members.
     * <p>
     * This is a convenience method, fully equivalent to 
     * <code>accept(visitor, IResource.DEPTH_INFINITE, IResource.NONE)</code>.
     * </p>
     *
     * @param visitor the visitor
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> The visitor failed with this exception.</li>
     * </ul>
     * @see IResourceVisitor#visit(IResource)
     * @see #accept(IResourceVisitor,int,int)
     */
    public void accept(IResourceVisitor visitor) throws CoreException;

    /**
     * Accepts the given visitor.
     * The visitor's <code>visit</code> method is called with this
     * resource. If the visitor returns <code>false</code>, 
     * this resource's members are not visited.
     * <p>
     * The subtree under the given resource is traversed to the supplied depth.
     * </p>
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   accept(visitor, depth, includePhantoms ? IContainer.INCLUDE_PHANTOMS : IResource.NONE);
     * </pre>
     * </p>
     *
     * @param visitor the visitor
     * @param depth the depth to which members of this resource should be
     *      visited.  One of {@link IResource#DEPTH_ZERO}, {@link IResource#DEPTH_ONE},
     *      or {@link IResource#DEPTH_INFINITE}.
     * @param includePhantoms <code>true</code> if phantom resources are
     *   of interest; <code>false</code> if phantom resources are not of
     *   interest.
     * @exception CoreException if this request fails. Reasons include:
     * <ul>
     * <li> <code>includePhantoms</code> is <code>false</code> and
     *     this resource does not exist.</li>
     * <li> <code>includePhantoms</code> is <code>true</code> and
     *     this resource does not exist and is not a phantom.</li>
     * <li> The visitor failed with this exception.</li>
     * </ul>
     * @see IResource#isPhantom()
     * @see IResourceVisitor#visit(IResource)
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @see IResource#accept(IResourceVisitor,int,int)
     */
    public void accept(IResourceVisitor visitor, int depth, boolean includePhantoms) throws CoreException;

    /**
     * Accepts the given visitor.
     * The visitor's <code>visit</code> method is called with this
     * resource. If the visitor returns <code>false</code>, 
     * this resource's members are not visited.
     * <p>
     * The subtree under the given resource is traversed to the supplied depth.
     * </p>
     * <p>
     * No guarantees are made about the behavior of this method if resources are
     * deleted or added during the traversal of this resource hierarchy.  If
     * resources are deleted during the traversal, they may still be passed to the
     * visitor; if resources are created, they may not be passed to the visitor.
     * </p>
     * <p>
     * If the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified in the member 
     * flags (recommended), only member resources that exists are visited.
     * If the {@link IContainer#INCLUDE_PHANTOMS} flag is specified, the visit also
     * includes any phantom member resource that the workspace is keeping track of.
     * </p>
     * <p>
     * If the {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not specified
     * (recommended), team private members are not visited. If the 
     * {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the member
     * flags, team private member resources are visited as well.
     * </p>
     * <p>
     * If the {@link IContainer#EXCLUDE_DERIVED} flag is not specified
     * (recommended), derived resources are visited. If the 
     * {@link IContainer#EXCLUDE_DERIVED} flag is specified in the member
     * flags, derived resources are not visited.
     * </p>
     * <p>
     * If the {@link IContainer#INCLUDE_HIDDEN} flag is not specified (recommended), 
     * hidden resources will not be visited. If the {@link IContainer#INCLUDE_HIDDEN} flag is specified 
     * in the member flags, hidden resources are visited as well.
     * </p>
     *
     * @param visitor the visitor
     * @param depth the depth to which members of this resource should be
     *      visited.  One of {@link IResource#DEPTH_ZERO}, {@link IResource#DEPTH_ONE},
     *      or {@link IResource#DEPTH_INFINITE}.
     * @param memberFlags bit-wise or of member flag constants
     *   ({@link IContainer#INCLUDE_PHANTOMS}, {@link IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS}, 
     *   {@link IContainer#INCLUDE_HIDDEN} and {@link IContainer#EXCLUDE_DERIVED}) indicating which members are of interest
     * @exception CoreException if this request fails. Reasons include:
     * <ul>
     * <li> the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified and
     *     this resource does not exist.</li>
     * <li> the {@link IContainer#INCLUDE_PHANTOMS} flag is not specified and
     *     this resource is a project that is not open.</li>
     * <li> The visitor failed with this exception.</li>
     * </ul>
     * @see IContainer#INCLUDE_PHANTOMS
     * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
     * @see IContainer#INCLUDE_HIDDEN
     * @see IContainer#EXCLUDE_DERIVED
     * @see IResource#isDerived()
     * @see IResource#isPhantom()
     * @see IResource#isTeamPrivateMember()
     * @see IResource#isHidden()
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @see IResourceVisitor#visit(IResource)
     * @since 2.0
     */
    public void accept(IResourceVisitor visitor, int depth, int memberFlags) throws CoreException;

    /**
     * Removes the local history of this resource and its descendents.
     * <p>
     * This operation 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 and cancellation are not desired
     */
    public void clearHistory(IProgressMonitor monitor) throws CoreException;

    /**
     * Makes a copy of this resource at the given path. 
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   copy(destination, (force ? FORCE : IResource.NONE), monitor);
     * </pre>
     * </p>
     * <p> 
     * This operation changes resources; these changes will be reported
     * in a subsequent resource change event that will include 
     * an indication that the resource copy has been added to its new parent.
     * </p>
     * <p>
     * This operation is long-running; progress and cancellation are provided
     * by the given progress monitor. 
     * </p>
     *
     * @param destination the destination path 
     * @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 copied. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> The source or destination is the workspace root.</li>
     * <li> The source is a project but the destination is not.</li>
     * <li> The destination is a project but the source is not.</li>
     * <li> The resource corresponding to the parent destination path does not exist.</li>
     * <li> The resource corresponding to the parent destination path is a closed project.</li>
     * <li> A resource at destination path does exist.</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> The source resource is a file and the destination path specifies a project.</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.
     */
    public void copy(IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;

    /**
     * Makes a copy of this resource at the given path. The resource's
     * descendents are copied as well.  The path of this resource must not be a
     * prefix of the destination path. The workspace root may not be the source or
     * destination location of a copy operation, and a project can only be copied to
     * another project. After successful completion, corresponding new resources
     * will exist at the given path; their contents and properties will be copies of
     * the originals. The original resources are not affected.
     * <p>
     * The supplied path may be absolute or relative.  Absolute paths fully specify
     * the new location for the resource, including its project. Relative paths are
     * considered to be relative to the container of the resource being copied. A
     * trailing separator is ignored.
     * </p>
     * <p>
     * Calling this method with a one segment absolute destination path is
     * equivalent to calling:
     * <pre>
     *   copy(workspace.newProjectDescription(folder.getName()),updateFlags,monitor);
     * </pre>
     * </p>
     * <p> When a resource is copied, its persistent properties are copied with it.
     * Session properties and markers are not copied.
     * </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 copy
     * resources that are in sync with the corresponding files and directories in
     * the local file system; it will fail if it encounters a resource that is out
     * of sync with the file system. However, if <code>FORCE</code> is specified,
     * the method copies all corresponding files and directories from the local file
     * system, including ones that have been recently updated or created. Note that
     * in both settings of the <code>FORCE</code> flag, the operation fails if the
     * newly created resources in the workspace would be out of sync with the local
     * file system; this ensures files in the file system cannot be accidentally
     * overwritten.
     * </p>
     * <p>
     * The <code>SHALLOW</code> update flag controls how this method deals with linked
     * resources.  If <code>SHALLOW</code> is not specified, then the underlying
     * contents of the linked resource will always be copied in the file system.  In
     * this case, the destination of the copy will never be a linked resource or
     * contain any linked resources.  If <code>SHALLOW</code> is specified when a
     * linked resource is copied into another project, a new linked resource is
     * created in the destination project that points to the same file system
     * location.  When a project containing linked resources is copied, the new
     * project will contain the same linked resources pointing to the same file
     * system locations.  For both of these shallow cases, no files on disk under
     * the linked resource are actually copied.  With the <code>SHALLOW</code> flag,
     * copying of linked resources into anything other than a project is not
     * permitted.  The <code>SHALLOW</code> update flag is ignored when copying non-
     * linked resources.
     * </p>
     * <p>
     * The {@link #DERIVED} update flag indicates that the new resource
     * should immediately be set as a derived resource.  Specifying this flag
     * is equivalent to atomically calling {@link #setDerived(boolean)}
     * with a value of <code>true</code> immediately after creating the resource.
     * </p>
     * <p>
     * The {@link #TEAM_PRIVATE} update flag indicates that the new resource
     * should immediately be set as a team private resource.  Specifying this flag
     * is equivalent to atomically calling {@link #setTeamPrivateMember(boolean)}
     * with a value of <code>true</code> immediately after creating the resource.
     * </p>
     * <p>
     * The {@link #HIDDEN} update flag indicates that the new resource
     * should immediately be set as a hidden resource.  Specifying this flag
     * is equivalent to atomically calling {@link #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>
     * <p> 
     * This operation changes resources; these changes will be reported in a
     * subsequent resource change event that will include an indication that the
     * resource copy has been added to its new parent.
     * </p>
     * <p>
     * An attempt will be made to copy the local history for this resource and its children,
     * to the destination. Since local history existence is a safety-net mechanism, failure
     * of this action will not result in automatic failure of the copy operation.
     * </p>
     * <p>
     * This operation is long-running; progress and cancellation are provided
     * by the given progress monitor. 
     * </p>
     *
     * @param destination the destination path 
     * @param updateFlags bit-wise or of update flag constants
     *   ({@link #FORCE}, {@link #SHALLOW}, {@link #DERIVED}, {@link #TEAM_PRIVATE}, {@link #HIDDEN})
     * @param monitor a progress monitor, or <code>null</code> if progress
     *    reporting is not desired
     * @exception CoreException if this resource could not be copied. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> The source or destination is the workspace root.</li>
     * <li> The source is a project but the destination is not.</li>
     * <li> The destination is a project but the source is not.</li>
     * <li> The resource corresponding to the parent destination path does not exist.</li>
     * <li> The resource corresponding to the parent destination path is a closed project.</li>
     * <li> The source is a linked resource, but the destination is not a project,
     *      and <code>SHALLOW</code> is specified.</li>
     * <li> A resource at destination path does exist.</li>
     * <li> This resource or one of its descendants is out of sync with the local file
     *      system and <code>FORCE</code> is not specified.</li>
     * <li> The workspace and the local file system are out of sync
     *      at the destination resource or one of its descendants.</li>
     * <li> The source resource is a file and the destination path specifies a project.</li>
     * <li> The source is a linked resource, and the destination path does not
     *  specify a project.</li>
     * <li> The location of the source resource on disk is the same or a prefix of
     * the location of the destination resource on disk.</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. 
     * Cancellation can occur even if no progress monitor is provided.
     * @see #FORCE
     * @see #SHALLOW
     * @see #DERIVED
     * @see #TEAM_PRIVATE
     * @see IResourceRuleFactory#copyRule(IResource, IResource)
     * @since 2.0
     */
    public void copy(IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;

    /**
     * Makes a copy of this project using the given project description.
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   copy(description, (force ? FORCE : IResource.NONE), monitor);
     * </pre>
     * </p>
     * <p> 
     * This operation changes resources; these changes will be reported
     * in a subsequent resource change event that will include 
     * an indication that the resource copy has been added to its new parent.
     * </p>
     * <p>
     * This operation is long-running; progress and cancellation are provided
     * by the given progress monitor. 
     * </p>
     *
     * @param description the destination project description
     * @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 copied. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> This resource is not a project.</li>
     * <li> The project described by the given description already exists.</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.
     */
    public void copy(IProjectDescription description, boolean force, IProgressMonitor monitor) throws CoreException;

    /**
     * Makes a copy of this project using the given project description. 
     * The project's descendents are copied as well. The description specifies the
     * name, location and attributes of the new project. After successful
     * completion, corresponding new resources will exist at the given path; their
     * contents and properties will be copies of the originals. The original
     * resources are not affected.
     * <p>
     * When a resource is copied, its persistent properties are copied with it.
     * Session properties and markers are not copied.
     * </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 copy resources that are in sync with the corresponding files and
     * directories in the local file system; it will fail if it encounters a
     * resource that is out of sync with the file system. However, if
     * <code>FORCE</code> is specified, the method copies all corresponding files
     * and directories from the local file system, including ones that have been
     * recently updated or created. Note that in both settings of the
     * <code>FORCE</code> flag, the operation fails if the newly created resources
     * in the workspace would be out of sync with the local file system; this
     * ensures files in the file system cannot be accidentally overwritten.
     * </p>
     * <p>  
     * The <code>SHALLOW</code> update flag controls how this method deals with
     * linked resources.  If <code>SHALLOW</code> is not specified, then the
     * underlying contents of any linked resources in the project will always be
     * copied in the file system.  In this case, the destination of the copy will
     * never contain any linked resources.  If <code>SHALLOW</code> is specified
     * when a project containing linked resources is copied, new linked resources
     * are created in the destination project that point to the same file system
     * locations.  In this case, no files on disk under linked resources are
     * actually copied. The <code>SHALLOW</code> update flag is ignored when copying
     * non- linked resources.
     * </p>
     * <p>
     * Update flags other than <code>FORCE</code> or <code>SHALLOW</code> are ignored.
     * </p>
     * <p>
     * An attempt will be made to copy the local history for this resource and its children,
     * to the destination. Since local history existence is a safety-net mechanism, failure
     * of this action will not result in automatic failure of the copy operation.
     * </p>
     * <p> This operation changes resources; these changes will be reported in a
     * subsequent resource change event that will include an indication that the
     * resource copy has been added to its new parent.
     * </p>
     * <p>
     * This operation is long-running; progress and cancellation are provided
     * by the given progress monitor. 
     * </p>
     *
     * @param description the destination project description
     * @param updateFlags bit-wise or of update flag constants
     *   (<code>FORCE</code> and <code>SHALLOW</code>)
     * @param monitor a progress monitor, or <code>null</code> if progress
     *    reporting is not desired
     * @exception CoreException if this resource could not be copied. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> This resource is not a project.</li>
     * <li> The project described by the given description already exists.</li>
     * <li> This resource or one of its descendents is out of sync with the local file
     *      system and <code>FORCE</code> is not specified.</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 #FORCE
     * @see #SHALLOW
     * @see IResourceRuleFactory#copyRule(IResource, IResource)
     * @since 2.0
     */
    public void copy(IProjectDescription description, int updateFlags, IProgressMonitor monitor) throws CoreException;

    /**
     * Creates and returns the marker with the specified type on this resource.
     * Marker type ids are the id of an extension installed in the
     * <code>org.eclipse.core.resources.markers</code> extension
     * point. The specified type string must not be <code>null</code>.
     *
     * @param type the type of the marker to create
     * @return the handle of the new marker
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see IResourceRuleFactory#markerRule(IResource)
     */
    public IMarker createMarker(String type) throws CoreException;

    /**
     * Creates a resource proxy representing the current state of this resource.
     * <p>
     * Note that once a proxy has been created, it does not stay in sync
     * with the corresponding resource.  Changes to the resource after
     * the proxy is created will not be reflected in the state of the proxy.
     * </p>
     * 
     * @return A proxy representing this resource
     * @since 3.2
     */
    public IResourceProxy createProxy();

    /**
     * Deletes this resource from the workspace.
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   delete(force ? FORCE : IResource.NONE, monitor);
     * </pre>
     * </p>
     * <p>
     * This method changes 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 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 resource could not be deleted for some reason.</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> 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)
     */
    public void delete(boolean force, IProgressMonitor monitor) throws CoreException;

    /**
     * Deletes this resource from the workspace.
     * Deletion applies recursively to all members of this resource in a "best-
     * effort" fashion.  That is, all resources which can be deleted are deleted.
     * Resources which could not be deleted are noted in a thrown exception. The
     * method does not fail if resources do not exist; it fails only if resources
     * could not be deleted.
     * <p>
     * Deleting a non-linked resource also deletes its contents from the local file
     * system. In the case of a file or folder resource, the corresponding file or
     * directory in the local file system is deleted. Deleting an open project
     * recursively deletes its members; deleting a closed project just gets rid of
     * the project itself (closed projects have no members); files in the project's
     * local content area are retained; referenced projects are unaffected.
     * </p>
     * <p>
     * Deleting a linked resource does not delete its contents from the file system,
     * it just removes that resource and its children from the workspace.  Deleting
     * children of linked resources does remove the contents from the file system.
     * </p>
     * <p>
     * Deleting a resource also deletes its session and persistent properties and
     * markers.
     * </p>
     * <p>
     * Deleting a non-project resource which has sync information converts the
     * resource to a phantom and retains the sync information for future use.
     * </p>
     * <p>
     * Deleting the workspace root resource recursively deletes all projects,
     * and removes all markers, properties, sync info and other data related to the
     * workspace root; the root resource itself is not deleted, however.
     * </p>
     * <p>
     * This method changes 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>
     * <p>
     * The {@link #FORCE} update flag controls how this method deals with
     * cases where the workspace is not completely in sync with the local
     * file system. If {@link #FORCE} is not specified, the method will only
     * attempt to delete files and directories in the local file system that
     * correspond to, and are in sync with, resources in the workspace; it will fail
     * if it encounters a file or directory in the file system that is out of sync
     * with  the workspace.  This option ensures there is no unintended data loss;
     * it is the recommended setting. However, if {@link #FORCE} is specified,
     * the method will ruthlessly attempt to delete corresponding files and
     * directories in the local file system, including ones that have been recently
     * updated or created.
     * </p>
     * <p>
     * The {@link #KEEP_HISTORY} update flag controls whether or not files that
     * are about to be deleted from the local file system have their current
     * contents saved 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 {@link #KEEP_HISTORY} is
     * recommended except in circumstances where past states of the files are of no
     * conceivable interest to the user. Note that local history is maintained
     * with each individual project, and gets discarded when a project is deleted
     * from the workspace. Hence {@link #KEEP_HISTORY} is only really applicable
     * when deleting files and folders, but not projects.
     * </p>
     * <p>
     * The {@link #ALWAYS_DELETE_PROJECT_CONTENT} update flag controls how
     * project deletions are handled. If {@link #ALWAYS_DELETE_PROJECT_CONTENT}
     * is specified, then the files and folders in a project's local content area
     * are deleted, regardless of whether the project is open or closed;
     * {@link #FORCE} is assumed regardless of whether it is specified. If
     * {@link #NEVER_DELETE_PROJECT_CONTENT} is specified, then the files and
     * folders in a project's local content area are retained, regardless of whether
     * the project is open or closed; the {@link #FORCE} flag is ignored. If
     * neither of these flags is specified, files and folders in a project's local
     * content area from open projects (subject to the {@link #FORCE} flag), but
     * never from closed projects.
     * </p>
     * 
     * @param updateFlags bit-wise or of update flag constants (
     *   {@link #FORCE}, {@link #KEEP_HISTORY},
     *   {@link #ALWAYS_DELETE_PROJECT_CONTENT},
     *   and {@link #NEVER_DELETE_PROJECT_CONTENT})
     * @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 could not be deleted for some reason.</li>
     * <li> This resource or one of its descendents is out of sync with the local file system
     *      and {@link #FORCE} 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>
     * </ul>
     * @exception OperationCanceledException if the operation is canceled. 
     * Cancelation can occur even if no progress monitor is provided.
     * @see IFile#delete(boolean, boolean, IProgressMonitor)
     * @see IFolder#delete(boolean, boolean, IProgressMonitor)
     * @see #FORCE
     * @see #KEEP_HISTORY
     * @see #ALWAYS_DELETE_PROJECT_CONTENT
     * @see #NEVER_DELETE_PROJECT_CONTENT
     * @see IResourceRuleFactory#deleteRule(IResource)
     * @since 2.0
     */
    public void delete(int updateFlags, IProgressMonitor monitor) throws CoreException;

    /**
     * Deletes all markers on this resource of the given type, and, 
     * optionally, deletes such markers from its children.  If <code>includeSubtypes</code>
     * is <code>false</code>, only markers whose type exactly matches 
     * the given type are deleted.  
     * <p>
     * This method changes resources; these changes will be reported
     * in a subsequent resource change event.
     * </p>
     *
     * @param type the type of marker to consider, or <code>null</code> to indicate all types
     * @param includeSubtypes whether or not to consider sub-types of the given type
     * @param depth how far to recurse (see <code>IResource.DEPTH_* </code>)
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is a project that is not open.</li>
     * <li> Resource changes are disallowed during certain types of resource change 
     *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
     * </ul>
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @see IResourceRuleFactory#markerRule(IResource)
     */
    public void deleteMarkers(String type, boolean includeSubtypes, int depth) throws CoreException;

    /**
     * Compares two objects for equality;
     * for resources, equality is defined in terms of their handles:
     * same resource type, equal full paths, and identical workspaces. 
     * Resources are not equal to objects other than resources.
     *
     * @param other the other object
     * @return an indication of whether the objects are equals
     * @see #getType()
     * @see #getFullPath()
     * @see #getWorkspace()
     */
    public boolean equals(Object other);

    /**
     * Returns whether this resource exists in the workspace.
     * <p>
     * <code>IResource</code> objects are lightweight handle objects
     * used to access resources in the workspace. However, having a
     * handle object does not necessarily mean the workspace really 
     * has such a resource. When the workspace does have a genuine
     * resource of a matching type, the resource is said to 
     * <em>exist</em>, and this method returns <code>true</code>; 
     * in all other cases, this method returns <code>false</code>.
     * In particular, it returns <code>false</code> if the workspace
     * has no resource at that path, or if it has a resource at that
     * path with a type different from the type of this resource handle.
     * </p>
     * <p>
     * Note that no resources ever exist under a project 
     * that is closed; opening a project may bring some
     * resources into existence.
     * </p>
     * <p>
     * The name and path of a resource handle may be invalid.
     * However, validation checks are done automatically as a 
     * resource is created; this means that any resource that exists
     * can be safely assumed to have a valid name and path.
     * </p>
     *
     * @return <code>true</code> if the resource exists, otherwise
     *    <code>false</code>
     */
    public boolean exists();

    /**
     * Returns the marker with the specified id on this resource,
     * Returns <code>null</code> if there is no matching marker.
     *
     * @param id the id of the marker to find
     * @return a marker or <code>null</code>
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     */
    public IMarker findMarker(long id) throws CoreException;

    /**
     * Returns all markers of the specified type on this resource,
     * and, optionally, on its children. If <code>includeSubtypes</code>
     * is <code>false</code>, only markers whose type exactly matches 
     * the given type are returned.  Returns an empty array if there 
     * are no matching markers.
     *
     * @param type the type of marker to consider, or <code>null</code> to indicate all types
     * @param includeSubtypes whether or not to consider sub-types of the given type
     * @param depth how far to recurse (see <code>IResource.DEPTH_* </code>)
     * @return an array of markers
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     */
    public IMarker[] findMarkers(String type, boolean includeSubtypes, int depth) throws CoreException;

    /**
     * Returns the maximum value of the {@link IMarker#SEVERITY} attribute across markers 
     * of the specified type on this resource, and, optionally, on its children. 
     * If <code>includeSubtypes</code>is <code>false</code>, only markers whose type 
     * exactly matches the given type are considered.  
     * Returns <code>-1</code> if there are no matching markers.  
     * Returns {@link IMarker#SEVERITY_ERROR} if any of the markers has a severity 
     * greater than or equal to {@link IMarker#SEVERITY_ERROR}.
     *
     * @param type the type of marker to consider (normally {@link IMarker#PROBLEM} 
     *   or one of its subtypes), or <code>null</code> to indicate all types 
     *   
     * @param includeSubtypes whether or not to consider sub-types of the given type
     * @param depth how far to recurse (see <code>IResource.DEPTH_* </code>)
     * @return {@link IMarker#SEVERITY_INFO}, {@link IMarker#SEVERITY_WARNING}, {@link IMarker#SEVERITY_ERROR}, or -1
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @since 3.3
     */
    public int findMaxProblemSeverity(String type, boolean includeSubtypes, int depth) throws CoreException;

    /**
     * Returns the file extension portion of this resource's name,
     * or <code>null</code> if it does not have one.
     * <p>
     * The file extension portion is defined as the string
     * following the last period (".") character in the name.
     * If there is no period in the name, the path has no
     * file extension portion. If the name ends in a period,
     * the file extension portion is the empty string.
     * </p>
     * <p> 
     * This is a resource handle operation; the resource need 
     * not exist.
     * </p>
     *
     * @return a string file extension
     * @see #getName()
     */
    public String getFileExtension();

    /**
     * Returns the full, absolute path of this resource relative to the
     * workspace.
     * <p> 
     * This is a resource handle operation; the resource need 
     * not exist.
     * If this resource does exist, its path can be safely assumed to be valid.
     * </p>
     * <p>
     * A resource's full path indicates the route from the root of the workspace
     * to the resource.  Within a workspace, there is exactly one such path
     * for any given resource. The first segment of these paths name a project; 
     * remaining segments, folders and/or files within that project.
     * The returned path never has a trailing separator.  The path of the
     * workspace root is <code>Path.ROOT</code>.
     * </p>
     * <p>
     * Since absolute paths contain the name of the project, they are
     * vulnerable when the project is renamed. For most situations,
     * project-relative paths are recommended over absolute paths.
     * </p>
     *
     * @return the absolute path of this resource
     * @see #getProjectRelativePath()
     * @see Path#ROOT
     */
    public IPath getFullPath();

    /**
     * Returns a cached value of the local time stamp on disk for this resource, or 
     * <code>NULL_STAMP</code>  if the resource does not exist or is not local or is 
     * not accessible.  The return value is represented as the number of milliseconds 
     * since the epoch (00:00:00 GMT, January 1, 1970).
     * The returned value may not be the same as the actual time stamp
     * on disk if the file has been modified externally since the last local refresh.
     * <p>
     * Note that due to varying file system timing granularities, this value is not guaranteed
     * to change every time the file is modified.  For a more reliable indication of whether
     * the file has changed, use <code>getModificationStamp</code>.
     * 
     * @return a local file system time stamp, or <code>NULL_STAMP</code>.
     * @since 3.0
     */
    public long getLocalTimeStamp();

    /**
     * Returns the absolute path in the local file system to this resource, 
     * or <code>null</code> if no path can be determined.
     * <p>
     * If this resource is the workspace root, this method returns
     * the absolute local file system path of the platform working area.
     * </p><p>
     * If this resource is a project that exists in the workspace, this method
     * returns the path to the project's local content area. This is true regardless
     * of whether the project is open or closed. This value will be null in the case
     * where the location is relative to an undefined workspace path variable.
     * </p><p>
     * If this resource is a linked resource under a project that is open, this
     * method returns the resolved path to the linked resource's local contents.
     * This value will be null in the case where the location is relative to an
     * undefined workspace path variable.
     * </p><p>
     * If this resource is a file or folder under a project that exists, or a
     * linked resource under a closed project, this method returns a (non-
     * <code>null</code>) path computed from the location of the project's local
     * content area and the project- relative path of the file or folder. This is
     * true regardless of whether the file or folders exists, or whether the project
     * is open or closed. In the case of linked resources, the location of a linked resource
     * within a closed project is too computed from the location of the
     * project's local content area and the project-relative path of the resource. If the
     * linked resource resides in an open project then its location is computed
     * according to the link.
     * </p><p>
     * If this resource is a project that does not exist in the workspace,
     * or a file or folder below such a project, this method returns
     * <code>null</code>.  This method also returns <code>null</code> if called 
     * on a resource that is not stored in the local file system.  For such resources 
     * {@link #getLocationURI()} should be used instead.
     * </p>
     * 
     * @return the absolute path of this resource in the local file system,
     *  or <code>null</code> if no path can be determined
     * @see #getRawLocation()
     * @see #getLocationURI()
     * @see  IProjectDescription#setLocation(IPath)
     * @see Platform#getLocation()
     */
    public IPath getLocation();

    /**
     * Returns the absolute URI of this resource, 
     * or <code>null</code> if no URI can be determined.
     * <p>
     * If this resource is the workspace root, this method returns
     * the absolute location of the platform working area.
     * </p><p>
     * If this resource is a project that exists in the workspace, this method
     * returns the URI to the project's local content area. This is true regardless
     * of whether the project is open or closed. This value will be null in the case
     * where the location is relative to an undefined workspace path variable.
     * </p><p>
     * If this resource is a linked resource under a project that is open, this
     * method returns the resolved URI to the linked resource's local contents.
     * This value will be null in the case where the location is relative to an
     * undefined workspace path variable.
     * </p><p>
     * If this resource is a file or folder under a project that exists, or a
     * linked resource under a closed project, this method returns a (non-
     * <code>null</code>) URI computed from the location of the project's local
     * content area and the project- relative path of the file or folder. This is
     * true regardless of whether the file or folders exists, or whether the project
     * is open or closed. In the case of linked resources, the location of a linked resource
     * within a closed project is computed from the location of the
     * project's local content area and the project-relative path of the resource. If the
     * linked resource resides in an open project then its location is computed
     * according to the link.
     * </p><p>
     * If this resource is a project that does not exist in the workspace,
     * or a file or folder below such a project, this method returns
     * <code>null</code>.
     * </p>
     * 
     * @return the absolute URI of this resource,
     *  or <code>null</code> if no URI can be determined
     * @see #getRawLocation()
     * @see  IProjectDescription#setLocation(IPath)
     * @see Platform#getLocation()
     * @see java.net.URI
     * @since 3.2
     */
    public URI getLocationURI();

    /**
     * Returns a marker handle with the given id on this resource.
     * This resource is not checked to see if it has such a marker.
     * The returned marker need not exist.
     * This resource need not exist.
     *
     * @param id the id of the marker
     * @return the specified marker handle
     * @see IMarker#getId()
     */
    public IMarker getMarker(long id);

    /**
     * Returns a non-negative modification stamp, or <code>NULL_STAMP</code> if 
     * the resource does not exist or is not local or is not accessible.
     * <p>
     * A resource's modification stamp gets updated each time a resource is modified.
     * If a resource's modification stamp is the same, the resource has not changed.
     * Conversely, if a resource's modification stamp is different, some aspect of it
     * (other than properties) has been modified at least once (possibly several times).
     * Resource modification stamps are preserved across project close/re-open,
     * and across workspace shutdown/restart.
     * The magnitude or sign of the numerical difference between two modification stamps 
     * is not significant.
     * </p>
     * <p>
     * The following things affect a resource's modification stamp:
     * <ul>
     * <li>creating a non-project resource (changes from <code>NULL_STAMP</code>)</li>
     * <li>changing the contents of a file</li>
     * <li><code>touch</code>ing a resource</li>
     * <li>setting the attributes of a project presented in a project description</li>
     * <li>deleting a resource (changes to <code>NULL_STAMP</code>)</li>
     * <li>moving a resource (source changes to <code>NULL_STAMP</code>,
     destination changes from <code>NULL_STAMP</code>)</li>
     * <li>copying a resource (destination changes from <code>NULL_STAMP</code>)</li>
     * <li>making a resource local</li>
     * <li>closing a project (changes to <code>NULL_STAMP</code>)</li>
     * <li>opening a project (changes from <code>NULL_STAMP</code>)</li>
     * <li>adding or removing a project nature (changes from <code>NULL_STAMP</code>)</li>
     * </ul>
     * The following things do not affect a resource's modification stamp:
     * <ul>
     * <li>"reading" a resource</li>
     * <li>adding or removing a member of a project or folder</li>
     * <li>setting a session property</li>
     * <li>setting a persistent property</li>
     * <li>saving the workspace</li>
     * <li>shutting down and re-opening a workspace</li>
     * </ul>
     * </p>
     *
     * @return the modification stamp, or <code>NULL_STAMP</code> if this resource either does
     *    not exist or exists as a closed project
     * @see IResource#NULL_STAMP
     * @see #revertModificationStamp(long)
     */
    public long getModificationStamp();

    /**
     * Returns the name of this resource. 
     * The name of a resource is synonymous with the last segment
     * of its full (or project-relative) path for all resources other than the 
     * workspace root.  The workspace root's name is the empty string.
     * <p> 
     * This is a resource handle operation; the resource need 
     * not exist.
     * </p>
     * <p>
     * If this resource exists, its name can be safely assumed to be valid.
     * </p>
     *
     * @return the name of the resource
     * @see #getFullPath()
     * @see #getProjectRelativePath()
     */
    public String getName();

    /**
     * Returns the resource which is the parent of this resource,
     * or <code>null</code> if it has no parent (that is, this
     * resource is the workspace root).
     * <p>
     * The full path of the parent resource is the same as this
     * resource's full path with the last segment removed.
     * </p>
     * <p>
     * This is a resource handle operation; neither the resource 
     * nor the resulting resource need exist.
     * </p>
     *
     * @return the parent resource of this resource,
     *    or <code>null</code> if it has no parent
     */
    public IContainer getParent();

    /**
     * Returns a copy of the map of this resource's persistent properties.
     * Returns an empty map if this resource has no persistent properties.
     *
     * @return the map containing the persistent properties where the key is
     *  the {@link QualifiedName} of the property and the value is the {@link String} 
     *  value of the property.
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see #setPersistentProperty(QualifiedName, String)
     * @since 3.4
     */
    public Map getPersistentProperties() throws CoreException;

    /**
     * Returns the value of the persistent property of this resource identified
     * by the given key, or <code>null</code> if this resource has no such property.
     *
     * @param key the qualified name of the property
     * @return the string value of the property, 
     *     or <code>null</code> if this resource has no such property
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see #setPersistentProperty(QualifiedName, String)
     */
    public String getPersistentProperty(QualifiedName key) throws CoreException;

    /**
     * Returns the project which contains this resource.
     * Returns itself for projects and <code>null</code>
     * for the workspace root.
     * <p>
     * A resource's project is the one named by the first segment
     * of its full path.
     * </p>
     * <p>
     * This is a resource handle operation; neither the resource 
     * nor the resulting project need exist.
     * </p>
     *
     * @return the project handle
     */
    public IProject getProject();

    /**
     * Returns a relative path of this resource with respect to its project.
     * Returns the empty path for projects and the workspace root.
     * <p> 
     * This is a resource handle operation; the resource need not exist.
     * If this resource does exist, its path can be safely assumed to be valid.
     * </p>
     * <p>
     * A resource's project-relative path indicates the route from the project
     * to the resource.  Within a project, there is exactly one such path
     * for any given resource. The returned path never has a trailing slash.
     * </p>
     * <p>
     * Project-relative paths are recommended over absolute paths, since 
     * the former are not affected if the project is renamed.
     * </p>
     *
     * @return the relative path of this resource with respect to its project
     * @see #getFullPath()
     * @see #getProject()
     * @see Path#EMPTY
     */
    public IPath getProjectRelativePath();

    /**
     * Returns the file system location of this resource, or <code>null</code> if no
     * path can be determined.  The returned path will either be an absolute file
     * system path, or a relative path whose first segment is the name of a
     * workspace path variable.
     * <p>
     * If this resource is an existing project, the returned path will be equal to
     * the location path in the project description.  If this resource is a linked
     * resource in an open project, the returned path will be equal to the location
     * path supplied when the linked resource was created.  In all other cases, this
     * method returns the same value as {@link #getLocation()}.
     * </p>
     * 
     * @return the raw path of this resource in the local file system,  or
     * <code>null</code> if no path can be determined
     * @see #getLocation()
     * @see IFile#createLink(IPath, int, IProgressMonitor)
     * @see IFolder#createLink(IPath, int, IProgressMonitor)
     * @see IPathVariableManager
     * @see IProjectDescription#getLocation()
     * @since 2.1
     */
    public IPath getRawLocation();

    /**
     * Returns the file system location of this resource, or <code>null</code> if no
     * path can be determined.  The returned path will either be an absolute URI,
     * or a relative URI whose first path segment is the name of a workspace path variable.
     * <p>
     * If this resource is an existing project, the returned path will be equal to
     * the location path in the project description.  If this resource is a linked
     * resource in an open project, the returned path will be equal to the location
     * path supplied when the linked resource was created.  In all other cases, this
     * method returns the same value as {@link #getLocationURI()}.
     * </p>
     * 
     * @return the raw path of this resource in the file system,  or
     * <code>null</code> if no path can be determined
     * @see #getLocationURI()
     * @see IFile#createLink(URI, int, IProgressMonitor)
     * @see IFolder#createLink(URI, int, IProgressMonitor)
     * @see IPathVariableManager
     * @see IProjectDescription#getLocationURI()
     * @since 3.2
     */
    public URI getRawLocationURI();

    /**
     * Gets this resource's extended attributes from the file system,
     * or <code>null</code> if the attributes could not be obtained.
     * <p>
     * Reasons for a <code>null</code> return value include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * </p><p>
     * Attributes that are not supported by the underlying file system 
     * will have a value of <code>false</code>.
     * </p><p>
     * Sample usage: <br>
     * <br> 
     * <code>
     *  IResource resource; <br> 
     *  ... <br>
     *  ResourceAttributes attributes = resource.getResourceAttributes(); <br>
     *  if (attributes != null) {
     *     attributes.setExecutable(true); <br>
     *     resource.setResourceAttributes(attributes); <br>
     *  }
     * </code>
     * </p>
     * 
     * @return the extended attributes from the file system, or
     * <code>null</code> if they could not be obtained
     * @see #setResourceAttributes(ResourceAttributes)
     * @see ResourceAttributes
     * @since 3.1
     */
    public ResourceAttributes getResourceAttributes();

    /**
     * Returns a copy of the map of this resource's session properties.
     * Returns an empty map if this resource has no session properties.
     *
     * @return the map containing the session properties where the key is
     *  the {@link QualifiedName} of the property and the value is the property 
     *  value (an {@link Object}.
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see #setSessionProperty(QualifiedName, Object)
     * @since 3.4
     */
    public Map getSessionProperties() throws CoreException;

    /**
     * Returns the value of the session property of this resource identified
     * by the given key, or <code>null</code> if this resource has no such property.
     *
     * @param key the qualified name of the property
     * @return the value of the session property, 
     *     or <code>null</code> if this resource has no such property
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see #setSessionProperty(QualifiedName, Object)
     */
    public Object getSessionProperty(QualifiedName key) throws CoreException;

    /**
     * Returns the type of this resource.
     * The returned value will be one of <code>FILE</code>, 
     * <code>FOLDER</code>, <code>PROJECT</code>, <code>ROOT</code>.
     * <p>
     * <ul>
     * <li> All resources of type <code>FILE</code> implement <code>IFile</code>.</li>
     * <li> All resources of type <code>FOLDER</code> implement <code>IFolder</code>.</li>
     * <li> All resources of type <code>PROJECT</code> implement <code>IProject</code>.</li>
     * <li> All resources of type <code>ROOT</code> implement <code>IWorkspaceRoot</code>.</li>
     * </ul>
     * </p>
     * <p> 
     * This is a resource handle operation; the resource need 
     * not exist in the workspace.
     * </p>
     *
     * @return the type of this resource
     * @see #FILE
     * @see #FOLDER
     * @see #PROJECT
     * @see #ROOT
     */
    public int getType();

    /**
     * Returns the workspace which manages this resource.
     * <p>
     * This is a resource handle operation; the resource need 
     * not exist in the workspace.
     * </p>
     *
     * @return the workspace
     */
    public IWorkspace getWorkspace();

    /**
     * Returns whether this resource is accessible.  For files and folders,
     * this is equivalent to existing; for projects, 
     * this is equivalent to existing and being open.  The workspace root
     * is always accessible.
     *
     * @return <code>true</code> if this resource is accessible, and
     *   <code>false</code> otherwise
     * @see #exists()
     * @see IProject#isOpen()
     */
    public boolean isAccessible();

    /**
     * Returns whether this resource subtree is marked as derived. Returns
     * <code>false</code> if this resource does not exist.
     * 
     * <p>
     * This is a convenience method, 
     * fully equivalent to <code>isDerived(IResource.NONE)</code>.
     * </p>
     *
     * @return <code>true</code> if this resource is marked as derived, and
     *   <code>false</code> otherwise
     * @see #setDerived(boolean)
     * @since 2.0
     */
    public boolean isDerived();
    
    /**
     * Returns whether this resource subtree is marked as derived. Returns 
     * <code>false</code> if this resource does not exist.
     * 
     * <p>
     * The {@link #CHECK_ANCESTORS} option flag indicates whether this method
     * should consider ancestor resources in its calculation.  If the 
     * {@link #CHECK_ANCESTORS} flag is present, this method will return 
     * <code>true</code>, if this resource, or any parent resource, is marked
     * as derived.  If the {@link #CHECK_ANCESTORS} option flag is not specified,
     * this method returns false for children of derived resources.
     * </p>
     * 
     * @param options bit-wise or of option flag constants
     *  (only {@link #CHECK_ANCESTORS} is applicable)
     * @return <code>true</code> if this resource subtree is derived, and 
     *   <code>false</code> otherwise
     * @see IResource#setDerived(boolean)
     * @since 3.4
     */
    public boolean isDerived(int options);

    /**
     * Returns whether this resource is hidden in the resource tree. Returns 
     * <code>false</code> if this resource does not exist.
     *  <p>
     * This operation is not related to the file system hidden attribute accessible using
     * {@link ResourceAttributes#isHidden()}.
     * </p>
     *
     * @return <code>true</code> if this resource is hidden , and
     *   <code>false</code> otherwise
     * @see #setHidden(boolean)
     * @since 3.4
     */
    public boolean isHidden();
    
    /**
     * Returns whether this resource is hidden in the resource tree. Returns
     * <code>false</code> if this resource does not exist.
     * <p>
     * This operation is not related to the file system hidden attribute
     * accessible using {@link ResourceAttributes#isHidden()}.
     * </p>
     * <p>
     * The {@link #CHECK_ANCESTORS} option flag indicates whether this method
     * should consider ancestor resources in its calculation. If the
     * {@link #CHECK_ANCESTORS} flag is present, this method will return
     * <code>true</code> if this resource, or any parent resource, is a hidden
     * resource. If the {@link #CHECK_ANCESTORS} option flag is not specified,
     * this method returns false for children of hidden resources.
     * </p>
     * 
     * @param options
     *        bit-wise or of option flag constants (only
     *        {@link #CHECK_ANCESTORS} is applicable)
     * @return <code>true</code> if this resource is hidden , and
     *         <code>false</code> otherwise
     * @see #setHidden(boolean)
     * @since 3.5
     */
    public boolean isHidden(int options);

    /**
     * Returns whether this resource has been linked to 
     * a location other than the default location calculated by the platform. 
     * <p>
     *   This is a convenience method, fully equivalent to 
     * <code>isLinked(IResource.NONE)</code>.
     * </p>
     * 
     * @return <code>true</code> if this resource is linked, and 
     *   <code>false</code> otherwise
     * @see IFile#createLink(IPath, int, IProgressMonitor)
     * @see IFolder#createLink(IPath, int, IProgressMonitor)
     * @since 2.1
     */
    public boolean isLinked();

    /**
     * Returns <code>true</code> if this resource has been linked to 
     * a location other than the default location calculated by the platform. This
     * location can be outside the project's content area or another location
     * within the project. Returns <code>false</code> in all other cases, including 
     * the case where this resource does not exist.  The workspace root and 
     * projects are never linked.
     * <p>
     * This method returns true only for a resource that has been linked using
     * the <code>createLink</code> method.  
     * </p>
     * <p>
     * The {@link #CHECK_ANCESTORS} option flag indicates whether this method
     * should consider ancestor resources in its calculation.  If the 
     * {@link #CHECK_ANCESTORS} flag is present, this method will return 
     * <code>true</code> if this resource, or any parent resource, is a linked 
     * resource.  If the {@link #CHECK_ANCESTORS} option flag is not specified,
     * this method returns false for children of linked resources.
     * </p>
     * 
     * @param options bit-wise or of option flag constants
     *  (only {@link #CHECK_ANCESTORS} is applicable)
     * @return <code>true</code> if this resource is linked, and 
     *   <code>false</code> otherwise
     * @see IFile#createLink(IPath, int, IProgressMonitor)
     * @see IFolder#createLink(IPath, int, IProgressMonitor)
     * @since 3.2
     */
    public boolean isLinked(int options);

    /**
     * Returns whether this resource and its members (to the 
     * specified depth) are expected to have their contents (and properties)
     * available locally.  Returns <code>false</code> in all other cases,
     * including the case where this resource does not exist.  The workspace
     * root and projects are always local.
     * <p>
     * When a resource is not local, its content and properties are
     * unavailable for both reading and writing.
     * </p>
     * 
     * @param depth valid values are <code>DEPTH_ZERO</code>, 
     *  <code>DEPTH_ONE</code>, or <code>DEPTH_INFINITE</code>
     * @return <code>true</code> if this resource is local, and
     *   <code>false</code> otherwise
     *
     * @see #setLocal(boolean, int, IProgressMonitor)
     * @deprecated This API is no longer in use.  Note that this API is unrelated 
     * to whether the resource is in the local file system versus some other file system.
     */
    public boolean isLocal(int depth);

    /**
     * Returns whether this resource is a phantom resource.
     * <p>
     * The workspace uses phantom resources to remember outgoing deletions and
     * incoming additions relative to an external synchronization partner.  Phantoms
     * appear and disappear automatically as a byproduct of synchronization.   
     * Since the workspace root cannot be synchronized in this way, it is never a phantom.
     * Projects are also never phantoms.
     * </p>
     * <p>
     * The key point is that phantom resources do not exist (in the technical
     * sense of <code>exists</code>, which returns <code>false</code>
     * for phantoms) are therefore invisible except through a handful of
     * phantom-enabled API methods (notably <code>IContainer.members(boolean)</code>).
     * </p>
     *
     * @return <code>true</code> if this resource is a phantom resource, and
     *   <code>false</code> otherwise
     * @see #exists()
     * @see IContainer#members(boolean)
     * @see IContainer#findMember(String, boolean)
     * @see IContainer#findMember(IPath, boolean)
     * @see ISynchronizer
     */
    public boolean isPhantom();

    /**
     * Returns whether this resource is marked as read-only in the file system.
     *
     * @return <code>true</code> if this resource is read-only, 
     *      <code>false</code> otherwise
     * @deprecated use <tt>IResource#getResourceAttributes()</tt>
     */
    public boolean isReadOnly();

    /**
     * Returns whether this resource and its descendents to the given depth 
     * are considered to be in sync with the local file system.  
     * <p>
     * A resource is considered to be in sync if all of the following 
     * conditions are true:
     * <ul>
     * <li>The resource exists in both the workspace and the file system.</li>
     * <li>The timestamp in the file system has not changed since the 
     * last synchronization.</li>
     * <li>The resource in the workspace is of the same type as the corresponding
     * file in the file system (they are either both files or both folders).</li>
     * </ul>
     *  A resource is also considered to be in sync if it is missing from both
     * the workspace and the file system.  In all other cases the resource is
     * considered to be out of sync.
     * </p>
     * <p>
     * This operation interrogates files and folders in the local file system;
     * depending on the speed of the local file system and the requested depth,
     * this operation may be time-consuming.
     * </p>
     * 
     * @param depth the depth (one of <code>IResource.DEPTH_ZERO</code>,
     *   <code>DEPTH_ONE</code>, or <code>DEPTH_INFINITE</code>)
     * @return <code>true</code> if this resource and its descendents to the 
     *    specified depth are synchronized, and <code>false</code> in all other
     *    cases
     * @see IResource#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @see #refreshLocal(int, IProgressMonitor)
     * @since 2.0
     */
    public boolean isSynchronized(int depth);

    /**
     * Returns whether this resource is a team private member of its parent container.
     * Returns <code>false</code> if this resource does not exist.
     *
     * @return <code>true</code> if this resource is a team private member, and
     *   <code>false</code> otherwise
     * @see #setTeamPrivateMember(boolean)
     * @since 2.0
     */
    public boolean isTeamPrivateMember();

    /**
     * Returns whether this resource is a team private member of its parent
     * container. Returns <code>false</code> if this resource does not exist.
     * <p>
     * The {@link #CHECK_ANCESTORS} option flag indicates whether this method
     * should consider ancestor resources in its calculation. If the
     * {@link #CHECK_ANCESTORS} flag is present, this method will return
     * <code>true</code> if this resource, or any parent resource, is a team
     * private member. If the {@link #CHECK_ANCESTORS} option flag is not
     * specified, this method returns false for children of team private
     * members.
     * </p>
     * 
     * @param options
     *        bit-wise or of option flag constants (only
     *        {@link #CHECK_ANCESTORS} is applicable)
     * @return <code>true</code> if this resource is a team private member, and
     *         <code>false</code> otherwise
     * @see #setTeamPrivateMember(boolean)
     * @since 3.5
     */
    public boolean isTeamPrivateMember(int options);
    
    /**
     * Moves this resource so that it is located at the given path.  
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   move(destination, 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 destination the destination path 
     * @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 does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> The source or destination is the workspace root.</li>
     * <li> The source is a project but the destination is not.</li>
     * <li> The destination is a project but the source is not.</li>
     * <li> The resource corresponding to the parent destination path does not exist.</li>
     * <li> The resource corresponding to the parent destination path is a closed 
     *      project.</li>
     * <li> A resource at destination path does exist.</li>
     * <li> A resource of a different type exists at the destination path.</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>
     * <li> The source resource is a file and the destination path specifies a project.</li>
     * </ul>
     * @exception OperationCanceledException if the operation is canceled. 
     * Cancelation can occur even if no progress monitor is provided.
     * @see IResourceDelta#getFlags()
     */
    public void move(IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;

    /**
     * Moves this resource so that it is located at the given path.  
     * The path of the resource must not be a prefix of the destination path. The
     * workspace root may not be the source or destination location of a move
     * operation, and a project can only be moved to another project. After
     * successful completion, the resource and any direct or indirect members will
     * no longer exist; but corresponding new resources will now exist at the given
     * path.
     * <p>
     * The supplied path may be absolute or relative.  Absolute paths fully specify
     * the new location for the resource, including its project.  Relative paths are
     * considered to be relative to the container of the resource being moved. A
     * trailing slash is ignored.
     * </p>
     * <p>
     * Calling this method with a one segment absolute destination path is
     * equivalent to calling:
     * <pre>
     IProjectDescription description = getDescription();
     description.setName(path.lastSegment());
     move(description, updateFlags, monitor);
     * </pre>
     * </p>
     * <p> When a resource moves, its session and persistent properties move with
     * it. Likewise for all other attributes of the resource including markers.
     * </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 move
     * resources that are in sync with the corresponding files and directories in
     * the local file system; it will fail if it encounters a resource that is out
     * of sync with the file system. However, if <code>FORCE</code> is specified,
     * the method moves all corresponding files and directories from the local file
     * system, including ones that have been recently updated or created. Note that
     * in both settings of the <code>FORCE</code> flag, the operation fails if the
     * newly created resources in the workspace would be out of sync with the local
     * file system; this ensures files in the file system cannot be accidentally
     * overwritten.
     * </p>
     * <p>
     * The <code>KEEP_HISTORY</code> update flag controls whether or not 
     * file that are about to be deleted from the local file system have their
     * current contents saved 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 except in circumstances where past states of the files are of
     * no conceivable interest to the user. Note that local history is maintained
     * with each individual project, and gets discarded when a project is deleted
     * from the workspace. Hence <code>KEEP_HISTORY</code> is only really applicable
     * when moving files and folders, but not whole projects.
     * </p>
     * <p>
     * If this resource is not a project, an attempt will be made to copy the local history 
     * for this resource and its children, to the destination. Since local history existence 
     * is a safety-net mechanism, failure of this action will not result in automatic failure 
     * of the move operation.
     * </p>
     * <p>
     * The <code>SHALLOW</code> update flag controls how this method deals with linked
     * resources.  If <code>SHALLOW</code> is not specified, then the underlying
     * contents of the linked resource will always be moved in the file system.  In
     * this case, the destination of the move will never be a linked resource or
     * contain any linked resources. If <code>SHALLOW</code> is specified when a
     * linked resource is moved into another project, a new linked resource is
     * created in the destination project that points to the same file system
     * location.  When a project containing linked resources is moved, the new
     * project will contain the same linked resources pointing to the same file
     * system locations.  For either of these cases, no files on disk under the
     * linked resource are actually moved. With the <code>SHALLOW</code> flag,
     * moving of linked resources into anything other than a project is not
     * permitted.  The <code>SHALLOW</code> update flag is ignored when moving non-
     * linked resources.
     * </p>
     * <p> 
     * Update flags other than <code>FORCE</code>, <code>KEEP_HISTORY</code>and
     * <code>SHALLOW</code> are ignored.
     * </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 destination the destination path 
     * @param updateFlags bit-wise or of update flag constants
     *   (<code>FORCE</code>, <code>KEEP_HISTORY</code> and <code>SHALLOW</code>)
     * @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 does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> The source or destination is the workspace root.</li>
     * <li> The source is a project but the destination is not.</li>
     * <li> The destination is a project but the source is not.</li>
     * <li> The resource corresponding to the parent destination path does not exist.</li>
     * <li> The resource corresponding to the parent destination path is a closed 
     *      project.</li>
     * <li> The source is a linked resource, but the destination is not a project
     *      and  <code>SHALLOW</code> is specified.</li>
     * <li> A resource at destination path does exist.</li>
     * <li> A resource of a different type exists at the destination path.</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> The source resource is a file and the destination path specifies a project.</li>
     * <li> The location of the source resource on disk is the same or a prefix of
     * the location of the destination resource on disk.</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 #FORCE
     * @see #KEEP_HISTORY
     * @see #SHALLOW
     * @see IResourceRuleFactory#moveRule(IResource, IResource)
     * @since  2.0
     */
    public void move(IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;

    /**
     * Renames or relocates this project so that it is the project specified by the given project 
     * description.
     * <p>
     * This is a convenience method, fully equivalent to:
     * <pre>
     *   move(description, (keepHistory ? KEEP_HISTORY : IResource.NONE) | (force ? FORCE : IResource.NONE), monitor);
     * </pre>
     * </p>
     * <p>
     * This operation 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 destination project description
     * @param force a flag controlling whether resources that are not
     *    in sync with the local file system will be tolerated
     * @param keepHistory a flag indicating whether or not to keep
     *    local history for files
     * @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 does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> This resource is not a project.</li>
     * <li> The project at the destination already exists.</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()
     */
    public void move(IProjectDescription description, boolean force, boolean keepHistory, IProgressMonitor monitor) throws CoreException;

    /**
     * Renames or relocates this project so that it is the project specified by the
     * given project description. The description specifies the name and location
     * of the new project. After successful completion, the old project
     * and any direct or indirect members will no longer exist; but corresponding
     * new resources will now exist in the new project.
     * <p>
     * When a resource moves, its session and persistent properties move with it.
     * Likewise for all the other attributes of the resource including markers.
     * </p>
     * <p>
     * When this project's location is the default location, then the directories
     * and files on disk are moved to be in the location specified by the given
     * description. If the given description specifies the default location for the
     * project, the directories and files are moved to the default location. If the name
     * in the given description is the same as this project's name and the location
     * is different, then the project contents will be moved to the new location.
     * In all other cases the directories and files on disk are left untouched.
     * Parts of the supplied description other than the name and location are ignored.
     * </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 move
     * resources that are in sync with the corresponding files and directories in
     * the local file system; it will fail if it encounters a resource that is out
     * of sync with the file system. However, if <code>FORCE</code> is specified,
     * the method moves all corresponding files and directories from the local file
     * system, including ones that have been recently updated or created. Note that
     * in both settings of the <code>FORCE</code> flag, the operation fails if the
     * newly created resources in the workspace would be out of sync with the local
     * file system; this ensures files in the file system cannot be accidentally
     * overwritten.
     * </p>
     * <p>
     * The <code>KEEP_HISTORY</code> update flag controls whether or not file that
     * are about to be deleted from the local file system have their current
     * contents saved 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 except in circumstances where past states of the files are of no
     * conceivable interest to the user. Note that local history is maintained
     * with each individual project, and gets discarded when a project is deleted
     * from the workspace. Hence <code>KEEP_HISTORY</code> is only really applicable
     * when moving files and folders, but not whole projects.
     * </p>
     * <p>
     * Local history information for this project and its children will not be moved to the
     * destination.
     * </p>
     * <p>
     * The <code>SHALLOW</code> update flag controls how this method deals with linked
     * resources.  If <code>SHALLOW</code> is not specified, then the underlying
     * contents of any linked resource will always be moved in the file system.  In
     * this case, the destination of the move will not contain any linked resources.
     * If  <code>SHALLOW</code> is specified when a project containing linked
     * resources is moved, new linked resources are created in the destination
     * project pointing to the same file system locations.  In this case, no files
     * on disk under any linked resource are actually moved.  The
     * <code>SHALLOW</code> update flag is ignored when moving non- linked
     * resources.
     * </p>
     * <p>
     * The {@link #REPLACE} update flag controls how this method deals
     * with a change of location.  If the location changes and the {@link #REPLACE}
     * flag is not specified, then the projects contents on disk are moved to the new
     * location.  If the location changes and the {@link #REPLACE}
     * flag is specified, then the project is reoriented to correspond to the new
     * location, but no contents are moved on disk.  The contents already on
     * disk at the new location become the project contents.  If the new project
     * location does not exist, it will be created.
     * </p>
     * <p>  
     * Update flags other than those listed above are ignored.
     * </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 destination project description
     * @param updateFlags bit-wise or of update flag constants
     *   ({@link #FORCE}, {@link #KEEP_HISTORY}, {@link #SHALLOW}
     *   and {@link #REPLACE}).
     * @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 does not exist.</li>
     * <li> This resource or one of its descendents is not local.</li>
     * <li> This resource is not a project.</li>
     * <li> The project at the destination already exists.</li>
     * <li> This resource or one of its descendents is out of sync with the
     *      local  file system and <code>FORCE</code> is not specified.</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>
     *  <li> The destination file system location is occupied. When moving a project
     *  in the file system, the destination directory must either not exist or be empty.</li>
     * </ul>
     * @exception OperationCanceledException if the operation is canceled. 
     * Cancelation can occur even if no progress monitor is provided.
     * @see IResourceDelta#getFlags()
     * @see #FORCE
     * @see #KEEP_HISTORY
     * @see #SHALLOW
     * @see #REPLACE
     * @see IResourceRuleFactory#moveRule(IResource, IResource)
     * @since  2.0
     */
    public void move(IProjectDescription description, int updateFlags, IProgressMonitor monitor) throws CoreException;

    /**
     * Refreshes the resource hierarchy from this resource and its 
     * children (to the specified depth) relative to the local file system.
     * Creations, deletions, and changes detected in the local file system 
     * will be reflected in the workspace's resource tree.
     * This resource need not exist or be local.
     * <p>
     * This method may discover changes to resources; any such 
     * changes will be reported in a subsequent resource change event.
     * </p>
     * <p>
     * If a new file or directory is discovered in the local file
     * system at or below the location of this resource, 
     * any parent folders required to contain the new
     * resource in the workspace will also be created automatically as required.
     * </p>
     * <p>
     * This method is long-running; progress and cancellation are provided
     * by the given progress monitor.
     * </p>
     * 
     * @param depth valid values are <code>DEPTH_ZERO</code>, 
     *  <code>DEPTH_ONE</code>, or <code>DEPTH_INFINITE</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> 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#DEPTH_ZERO
     * @see IResource#DEPTH_ONE
     * @see IResource#DEPTH_INFINITE
     * @see IResourceRuleFactory#refreshRule(IResource)
     */
    public void refreshLocal(int depth, IProgressMonitor monitor) throws CoreException;

    /**
     * Reverts this resource's modification stamp.  This is intended to be used by 
     * a client that is rolling back or undoing a previous change to this resource.  
     * <p>
     * It is the caller's responsibility to ensure that the value of the reverted 
     * modification stamp matches this resource's modification stamp prior to the 
     * change that has been rolled back.  More generally, the caller must ensure
     * that the specification of modification stamps outlined in 
     * <code>getModificationStamp</code> is honored; the modification stamp
     * of two distinct resource states should be different if and only if one or more
     * of the attributes listed in the specification as affecting the modification
     * stamp have changed.
     * <p>
     * Reverting the modification stamp will <b>not</b> be reported in a 
     * subsequent resource change event.
     * <p>
     * Note that a resource's modification stamp is unrelated to the local
     * time stamp for this resource on disk, if any.  A resource's local time
     * stamp is modified using the <code>setLocalTimeStamp</code> method.
     * 
     * @param value A non-negative modification stamp value
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is not accessible.</li>
     * <li> Resource changes are disallowed during certain types of resource change 
     *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
     * </ul>
     * @see #getModificationStamp()
     * @since 3.1
     */
    public void revertModificationStamp(long value) throws CoreException;

    /**
     * Sets whether this resource subtree is marked as derived.
     * <p>
     * A <b>derived</b> resource is a regular file or folder that is
     * created in the course of translating, compiling, copying, or otherwise 
     * processing other files. Derived resources are not original data, and can be
     * recreated from other resources. It is commonplace to exclude derived 
     * resources from version and configuration management because they would
     * otherwise clutter the team repository with version of these ever-changing
     * files as each user regenerates them.
     * </p>
     * <p>
     * If a resource or any of its ancestors is marked as derived, a team 
     * provider should assume that the resource is not under version and
     * configuration management <i>by default</i>. That is, the resource
     * should only be stored in a team repository if the user explicitly indicates
     * that this resource is worth saving.
     * </p>
     * <p>
     * Newly-created resources are not marked as derived; rather, the mark must be
     * set explicitly using <code>setDerived(true)</code>. Derived marks are maintained
     * in the in-memory resource tree, and are discarded when the resources are deleted.
     * Derived marks are saved to disk when a project is closed, or when the workspace
     * is saved.
     * </p>
     * <p>
     * Projects and the workspace root are never considered derived; attempts to
     * mark them as derived are ignored.
     * </p>
     * <p>
     * This operation does <b>not</b> result in a resource change event, and does not
     * trigger autobuilds.
     * </p>
     * 
     * @param isDerived <code>true</code> if this resource is to be marked
     *   as derived, and <code>false</code> otherwise
     * @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>
     * @see #isDerived()
     * @since 2.0
     */
    public void setDerived(boolean isDerived) throws CoreException;

    /**
     * Sets whether this resource and its members are hidden in the resource tree.
     * <p>
     * Hidden resources are invisible to most clients. Newly-created resources 
     * are not hidden resources by default.
     * </p>
     * <p>
     * The workspace root is never considered hidden resource;
     * attempts to mark it as hidden are ignored.
     * </p>
     * <p>
     * This operation does <b>not</b> result in a resource change event, and does not
     * trigger autobuilds.
     * </p>
     * <p>
     * This operation is not related to {@link ResourceAttributes#setHidden(boolean)}.
     * Whether a resource is hidden in the resource tree is unrelated to whether the
     * underlying file is hidden in the file system.
     * </p>
     * 
     * @param isHidden <code>true</code> if this resource is to be marked
     *   as hidden, and <code>false</code> otherwise
     * @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>
     * @see #isHidden()
     * @since 3.4
     */
    public void setHidden(boolean isHidden) throws CoreException;

    /**
     * Set whether or not this resource and its members (to the 
     * specified depth) are expected to have their contents (and properties)
     * available locally.  The workspace root and projects are always local and 
     * attempting to set either to non-local (i.e., passing <code>false</code>) 
     * has no affect on the resource.
     * <p>
     * When a resource is not local, its content and properties are
     * unavailable for both reading and writing.
     * </p>
     * <p>
     * This method is long-running; progress and cancellation are provided
     * by the given progress monitor.
     * </p>
     * 
     * @param flag whether this resource should be considered local
     * @param depth valid values are <code>DEPTH_ZERO</code>, 
     *  <code>DEPTH_ONE</code>, or <code>DEPTH_INFINITE</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> 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 #isLocal(int)
     * @deprecated This API is no longer in use.  Note that this API is unrelated 
     * to whether the resource is in the local file system versus some other file system.
     */
    public void setLocal(boolean flag, int depth, IProgressMonitor monitor) throws CoreException;

    /**
     * Sets the local time stamp on disk for this resource.  The time must be represented 
     * as the number of milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
     * Returns the actual time stamp that was recorded.
     * Due to varying file system timing granularities, the provided value may be rounded
     * or otherwise truncated, so the actual recorded time stamp that is returned may
     * not be the same as the supplied value.
     * 
     * @param value a time stamp in milliseconds.
     * @return a local file system time stamp.
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is not accessible.</li>
     * <li> Resource changes are disallowed during certain types of resource change 
     *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
     * </ul>
     * @since 3.0
     */
    public long setLocalTimeStamp(long value) throws CoreException;

    /**
     * Sets the value of the persistent property of this resource identified
     * by the given key. If the supplied value is <code>null</code>,
     * the persistent property is removed from this resource. The change
     * is made immediately on disk.
     * <p>
     * Persistent properties are intended to be used by plug-ins to store
     * resource-specific information that should be persisted across platform sessions.
     * The value of a persistent property is a string that must be short -
     * 2KB or less in length. Unlike session properties, persistent properties are
     * stored on disk and maintained across workspace shutdown and restart.
     * </p>
     * <p>
     * The qualifier part of the property name must be the unique identifier
     * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
     * </p>
     *
     * @param key the qualified name of the property
     * @param value the string value of the property, 
     *     or <code>null</code> if the property is to be removed
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * <li> Resource changes are disallowed during certain types of resource change 
     *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
     * </ul>
     * @see #getPersistentProperty(QualifiedName)
     * @see #isLocal(int)
     */
    public void setPersistentProperty(QualifiedName key, String value) throws CoreException;

    /**
     * Sets or unsets this resource as read-only in the file system.
     *
     * @param readOnly <code>true</code> to set it to read-only, 
     *      <code>false</code> to unset
     * @deprecated use <tt>IResource#setResourceAttributes(ResourceAttributes)</tt>
     */
    public void setReadOnly(boolean readOnly);

    /**
     * Sets this resource with the given extended attributes. This sets the
     * attributes in the file system. Only attributes that are supported by
     * the underlying file system will be set. 
     * <p>
     * Sample usage: <br>
     * <br> 
     * <code>
     *  IResource resource; <br> 
     *  ... <br>
     *  if (attributes != null) {
     *     attributes.setExecutable(true); <br>
     *     resource.setResourceAttributes(attributes); <br>
     *  }
     * </code>
     * </p>
     * <p>
     * Note that a resource cannot be converted into a symbolic link by 
     * setting resource attributes with {@link ResourceAttributes#isSymbolicLink()}
     * set to true.
     * </p>
     * 
     * @param attributes the attributes to set
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * </ul>
     * @see #getResourceAttributes()
     * @since 3.1 
     */
    void setResourceAttributes(ResourceAttributes attributes) throws CoreException;

    /**
     * Sets the value of the session property of this resource identified
     * by the given key. If the supplied value is <code>null</code>,
     * the session property is removed from this resource. 
     * <p>
     * Sessions properties are intended to be used as a caching mechanism
     * by ISV plug-ins. They allow key-object associations to be stored with
     * existing resources in the workspace. These key-value associations are
     * maintained in memory (at all times), and the information is lost when a
     * resource is deleted from the workspace, when the parent project
     * is closed, or when the workspace is closed.
     * </p>
     * <p>
     * The qualifier part of the property name must be the unique identifier
     * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
     * </p>
     *
     * @param key the qualified name of the property
     * @param value the value of the session property, 
     *     or <code>null</code> if the property is to be removed
     * @exception CoreException if this method fails. Reasons include:
     * <ul>
     * <li> This resource does not exist.</li>
     * <li> This resource is not local.</li>
     * <li> This resource is a project that is not open.</li>
     * <li> Resource changes are disallowed during certain types of resource change 
     *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
     * </ul>
     * @see #getSessionProperty(QualifiedName)
     */
    public void setSessionProperty(QualifiedName key, Object value) throws CoreException;

    /**
     * Sets whether this resource subtree is a team private member of its parent container.
     * <p>
     * A <b>team private member</b> resource is a special file or folder created by a team
     * provider to hold team-provider-specific information. Resources marked as team private
     * members are invisible to most clients. 
     * </p>
     * <p>
     * Newly-created resources are not team private members by default; rather, the
     * team provider must mark a resource explicitly using
     * <code>setTeamPrivateMember(true)</code>. Team private member marks are
     * maintained in the in-memory resource tree, and are discarded when the
     * resources are deleted. Team private member marks are saved to disk when a
     * project is closed, or when the workspace is saved.
     * </p>
     * <p>
     * Projects and the workspace root are never considered team private members;
     * attempts to mark them as team private are ignored.
     * </p>
     * <p>
     * This operation does <b>not</b> result in a resource change event, and does not
     * trigger autobuilds.
     * </p>
     * 
     * @param isTeamPrivate <code>true</code> if this resource is to be marked
     *   as team private, and <code>false</code> otherwise
     * @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>
     * @see #isTeamPrivateMember()
     * @since 2.0
     */
    public void setTeamPrivateMember(boolean isTeamPrivate) throws CoreException;

    /**
     * Marks this resource as having changed even though its content
     * may not have changed. This method can be used to trigger 
     * the rebuilding of resources/structures derived from this resource.
     * Touching the workspace root has no effect. 
     * <p>
     * This method changes resources; these changes will be reported
     * in a subsequent resource change event. If the resource is a project,
     * the change event will indicate a description change.
     * </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> This resource is not local.</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 IResourceRuleFactory#modifyRule(IResource)
     * @see IResourceDelta#CONTENT
     * @see IResourceDelta#DESCRIPTION
     */
    public void touch(IProgressMonitor monitor) throws CoreException;
    
    
}