/*******************************************************************************
* Copyright (c) 2000, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Red Hat Incorporated - get/setResourceAttribute code
* Oakland Software Incorporated - added getSessionProperties and getPersistentProperties
* Serge Beauchamp (Freescale Semiconductor) - [252996] add hasFilters()
* Serge Beauchamp (Freescale Semiconductor) - [229633] Group and Project Path Variable Support
*******************************************************************************/
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;
/**
* Update flag constant (bit mask value 0x2000) indicating that a resource should be marked as a
* virtual resource.
*
* @see IFolder#create(int, boolean, IProgressMonitor)
* @since 3.6
*/
public static final int VIRTUAL= 0x2000;
/*====================================================================
* 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 path variable manager for this resource.
*
* @return the path variable manager
* @see IPathVariableManager
* @since 3.6
*/
public IPathVariableManager getPathVariableManager();
/**
* 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 whether this resource is a virtual resource. Returns <code>true</code> for folders
* that have been marked virtual using the {@link #VIRTUAL} update flag. Returns
* <code>false</code> in all other cases, including the case where this resource does not exist.
* The workspace root, projects and files currently cannot be made virtual.
*
* @return <code>true</code> if this resource is virtual, and <code>false</code> otherwise
* @see IFile#create(java.io.InputStream, int, IProgressMonitor)
* @see #VIRTUAL
* @since 3.6
*/
public boolean isVirtual();
/**
* 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 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
* @deprecated Replaced by {@link #setDerived(boolean, IProgressMonitor)} which is a workspace
* operation and reports changes in resource deltas.
*/
public void setDerived(boolean isDerived) 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, IProgressMonitor)</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>
* These changes will be reported in a subsequent resource change event, including an indication
* that this file's derived flag has changed.
* </p>
* <p>
* This method is long-running; progress and cancellation are provided by the given progress
* monitor.
* </p>
*
* @param isDerived <code>true</code> if this resource is to be marked as derived, and
* <code>false</code> otherwise
* @param monitor a progress monitor, or <code>null</code> if progress reporting is not desired
* @exception OperationCanceledException if the operation is canceled. Cancellation can occur
* even if no progress monitor is provided.
* @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()
* @see IResourceRuleFactory#derivedRule(IResource)
* @since 3.6
*/
public void setDerived(boolean isDerived, IProgressMonitor monitor) 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 {@link IResourceChangeEvent} 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;
}