/*******************************************************************************
 *  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;
	
	
}