org.eclipse.core.resources
Interface IResource

All Superinterfaces:

IAdaptable, ISchedulingRule

All Known Subinterfaces:

IContainer, IFile, IFolder, IProject, IWorkspaceRoot

public interface IResource

extends IAdaptable, ISchedulingRule

The workspace analog of file system files and directories. There are exactly four types of resource: files, folders, projects and the workspace root.

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.

Features of resources:

• IResource objects are handles 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.
• Resources have two different kinds of properties as detailed below. All properties are keyed by qualified names.
• 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.
• 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).
• Resources are identified by type and by their path, 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.
• Resources can be local or non-local. A non-local resource is one whose contents and properties have not been fetched from a repository.
• Phantom resources represent incoming additions or outgoing deletions which have yet to be reconciled with a synchronization partner.

Resources implement the IAdaptable interface; extensions are managed by the platform's adapter manager.

See Also:

IWorkspace, Platform.getAdapterManager()

Restriction

This interface is not intended to be implemented by clients.

Field Summary

static int	ALLOW_MISSING_LOCAL 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.
static int	ALWAYS_DELETE_PROJECT_CONTENT Update flag constant (bit mask value 4) indicating that the operation should delete the files and folders of a project.
static int	AVOID_NATURE_CONFIG Update flag constant (bit mask value 64) indicating that setting the project description should not attempt to configure and de-configure natures.
static int	BACKGROUND_REFRESH 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.
static int	CHECK_ANCESTORS Update flag constant (bit mask value 512) indicating that ancestor resources of the target resource should be checked.
static int	DEPTH_INFINITE Depth constant (value 2) indicating this resource and its direct and indirect members at any depth.
static int	DEPTH_ONE Depth constant (value 1) indicating this resource and its direct members.
static int	DEPTH_ZERO Depth constant (value 0) indicating this resource, but not any of its members.
static int	DERIVED Update flag constant (bit mask value 0x400) indicating that a resource should be marked as derived.
static int	FILE Type constant (bit mask value 1) which identifies file resources.
static int	FOLDER Type constant (bit mask value 2) which identifies folder resources.
static int	FORCE 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.
static int	HIDDEN Update flag constant (bit mask value 0x1000) indicating that a resource should be marked as a hidden resource.
static int	KEEP_HISTORY 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.
static int	NEVER_DELETE_PROJECT_CONTENT Update flag constant (bit mask value 8) indicating that the operation should preserve the files and folders of a project.
static int	NONE General purpose zero-valued bit mask constant.
static int	NULL_STAMP Modification stamp constant (value -1) indicating no modification stamp is available.
static int	PROJECT Type constant (bit mask value 4) which identifies project resources.
static int	REPLACE 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.
static int	ROOT Type constant (bit mask value 8) which identifies the root resource.
static int	SHALLOW 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.
static int	TEAM_PRIVATE Update flag constant (bit mask value 0x800) indicating that a resource should be marked as team private.

Method Summary

void	accept(IResourceProxyVisitor visitor, int memberFlags) Accepts the given visitor for an optimized traversal.
void	accept(IResourceVisitor visitor) Accepts the given visitor.
void	accept(IResourceVisitor visitor, int depth, boolean includePhantoms) Accepts the given visitor.
void	accept(IResourceVisitor visitor, int depth, int memberFlags) Accepts the given visitor.
void	clearHistory(IProgressMonitor monitor) Removes the local history of this resource and its descendents.
void	copy(IPath destination, boolean force, IProgressMonitor monitor) Makes a copy of this resource at the given path.
void	copy(IPath destination, int updateFlags, IProgressMonitor monitor) Makes a copy of this resource at the given path.
void	copy(IProjectDescription description, boolean force, IProgressMonitor monitor) Makes a copy of this project using the given project description.
void	copy(IProjectDescription description, int updateFlags, IProgressMonitor monitor) Makes a copy of this project using the given project description.
IMarker	createMarker(String type) Creates and returns the marker with the specified type on this resource.
IResourceProxy	createProxy() Creates a resource proxy representing the current state of this resource.
void	delete(boolean force, IProgressMonitor monitor) Deletes this resource from the workspace.
void	delete(int updateFlags, IProgressMonitor monitor) Deletes this resource from the workspace.
void	deleteMarkers(String type, boolean includeSubtypes, int depth) Deletes all markers on this resource of the given type, and, optionally, deletes such markers from its children.
boolean	equals(Object other) Compares two objects for equality; for resources, equality is defined in terms of their handles: same resource type, equal full paths, and identical workspaces.
boolean	exists() Returns whether this resource exists in the workspace.
IMarker	findMarker(long id) Returns the marker with the specified id on this resource, Returns null if there is no matching marker.
IMarker[]	findMarkers(String type, boolean includeSubtypes, int depth) Returns all markers of the specified type on this resource, and, optionally, on its children.
int	findMaxProblemSeverity(String type, boolean includeSubtypes, int depth) Returns the maximum value of the IMarker.SEVERITY attribute across markers of the specified type on this resource, and, optionally, on its children.
String	getFileExtension() Returns the file extension portion of this resource's name, or null if it does not have one.
IPath	getFullPath() Returns the full, absolute path of this resource relative to the workspace.
long	getLocalTimeStamp() Returns a cached value of the local time stamp on disk for this resource, or NULL_STAMP if the resource does not exist or is not local or is not accessible.
IPath	getLocation() Returns the absolute path in the local file system to this resource, or null if no path can be determined.
URI	getLocationURI() Returns the absolute URI of this resource, or null if no URI can be determined.
IMarker	getMarker(long id) Returns a marker handle with the given id on this resource.
long	getModificationStamp() Returns a non-negative modification stamp, or NULL_STAMP if the resource does not exist or is not local or is not accessible.
String	getName() Returns the name of this resource.
IContainer	getParent() Returns the resource which is the parent of this resource, or null if it has no parent (that is, this resource is the workspace root).
Map	getPersistentProperties() Returns a copy of the map of this resource's persistent properties.
String	getPersistentProperty(QualifiedName key) Returns the value of the persistent property of this resource identified by the given key, or null if this resource has no such property.
IProject	getProject() Returns the project which contains this resource.
IPath	getProjectRelativePath() Returns a relative path of this resource with respect to its project.
IPath	getRawLocation() Returns the file system location of this resource, or null if no path can be determined.
URI	getRawLocationURI() Returns the file system location of this resource, or null if no path can be determined.
ResourceAttributes	getResourceAttributes() Gets this resource's extended attributes from the file system, or null if the attributes could not be obtained.
Map	getSessionProperties() Returns a copy of the map of this resource's session properties.
Object	getSessionProperty(QualifiedName key) Returns the value of the session property of this resource identified by the given key, or null if this resource has no such property.
int	getType() Returns the type of this resource.
IWorkspace	getWorkspace() Returns the workspace which manages this resource.
boolean	isAccessible() Returns whether this resource is accessible.
boolean	isDerived() Returns whether this resource subtree is marked as derived.
boolean	isDerived(int options) Returns whether this resource subtree is marked as derived.
boolean	isHidden() Returns whether this resource is hidden in the resource tree.
boolean	isLinked() Returns whether this resource has been linked to a location other than the default location calculated by the platform.
boolean	isLinked(int options) Returns true if this resource has been linked to a location other than the default location calculated by the platform.
boolean	isLocal(int depth) 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.
boolean	isPhantom() Returns whether this resource is a phantom resource.
boolean	isReadOnly() Deprecated. use IResource#getResourceAttributes()
boolean	isSynchronized(int depth) Returns whether this resource and its descendents to the given depth are considered to be in sync with the local file system.
boolean	isTeamPrivateMember() Returns whether this resource is a team private member of its parent container.
void	move(IPath destination, boolean force, IProgressMonitor monitor) Moves this resource so that it is located at the given path.
void	move(IPath destination, int updateFlags, IProgressMonitor monitor) Moves this resource so that it is located at the given path.
void	move(IProjectDescription description, boolean force, boolean keepHistory, IProgressMonitor monitor) Renames or relocates this project so that it is the project specified by the given project description.
void	move(IProjectDescription description, int updateFlags, IProgressMonitor monitor) Renames or relocates this project so that it is the project specified by the given project description.
void	refreshLocal(int depth, IProgressMonitor monitor) Refreshes the resource hierarchy from this resource and its children (to the specified depth) relative to the local file system.
void	revertModificationStamp(long value) Reverts this resource's modification stamp.
void	setDerived(boolean isDerived) Sets whether this resource subtree is marked as derived.
void	setHidden(boolean isHidden) Sets whether this resource and its members are hidden in the resource tree.
void	setLocal(boolean flag, int depth, IProgressMonitor monitor) 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.
long	setLocalTimeStamp(long value) Sets the local time stamp on disk for this resource.
void	setPersistentProperty(QualifiedName key, String value) Sets the value of the persistent property of this resource identified by the given key.
void	setReadOnly(boolean readOnly) Deprecated. use IResource#setResourceAttributes(ResourceAttributes)
void	setResourceAttributes(ResourceAttributes attributes) Sets this resource with the given extended attributes.
void	setSessionProperty(QualifiedName key, Object value) Sets the value of the session property of this resource identified by the given key.
void	setTeamPrivateMember(boolean isTeamPrivate) Sets whether this resource subtree is a team private member of its parent container.
void	touch(IProgressMonitor monitor) Marks this resource as having changed even though its content may not have changed.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Methods inherited from interface org.eclipse.core.runtime.jobs.ISchedulingRule

contains, isConflicting

Field Detail

FILE

public static final int FILE

Type constant (bit mask value 1) which identifies file resources.

See Also:

getType(), IFile, Constant Field Values

FOLDER

public static final int FOLDER

Type constant (bit mask value 2) which identifies folder resources.

See Also:

getType(), IFolder, Constant Field Values

PROJECT

public static final int PROJECT

Type constant (bit mask value 4) which identifies project resources.

See Also:

getType(), IProject, Constant Field Values

ROOT

public static final int ROOT

Type constant (bit mask value 8) which identifies the root resource.

See Also:

getType(), IWorkspaceRoot, Constant Field Values

DEPTH_ZERO

public static final int DEPTH_ZERO

Depth constant (value 0) indicating this resource, but not any of its members.

See Also:

Constant Field Values

DEPTH_ONE

public static final int DEPTH_ONE

Depth constant (value 1) indicating this resource and its direct members.

See Also:

Constant Field Values

DEPTH_INFINITE

public static final int DEPTH_INFINITE

Depth constant (value 2) indicating this resource and its direct and indirect members at any depth.

See Also:

Constant Field Values

FORCE

public static final int FORCE

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

See Also:

Constant Field Values

KEEP_HISTORY

public static final int KEEP_HISTORY

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.

Since:

2.0

See Also:

IFile.getHistory(IProgressMonitor), Constant Field Values

ALWAYS_DELETE_PROJECT_CONTENT

public static final int ALWAYS_DELETE_PROJECT_CONTENT

Update flag constant (bit mask value 4) indicating that the operation should delete the files and folders of a project.

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 ALWAYS_DELETE_PROJECT_CONTENT indicates that the contents of a project are to be deleted regardless of whether the project is open or closed at the time; specifying NEVER_DELETE_PROJECT_CONTENT indicates that the contents of a project are to be retained regardless of whether the project is open or closed at the time.

Since:

2.0

See Also:

NEVER_DELETE_PROJECT_CONTENT, Constant Field Values

NEVER_DELETE_PROJECT_CONTENT

public static final int NEVER_DELETE_PROJECT_CONTENT

Update flag constant (bit mask value 8) indicating that the operation should preserve the files and folders of a project.

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 ALWAYS_DELETE_PROJECT_CONTENT indicates that the contents of a project are to be deleted regardless of whether the project is open or closed at the time; specifying NEVER_DELETE_PROJECT_CONTENT indicates that the contents of a project are to be retained regardless of whether the project is open or closed at the time.

Since:

2.0

See Also:

ALWAYS_DELETE_PROJECT_CONTENT, Constant Field Values

ALLOW_MISSING_LOCAL

public static final int ALLOW_MISSING_LOCAL

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.

Since:

2.1

See Also:

IFolder.createLink(IPath, int, IProgressMonitor), IFile.createLink(IPath, int, IProgressMonitor), Constant Field Values

SHALLOW

public static final int SHALLOW

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.

Since:

2.1

See Also:

copy(IPath, int, IProgressMonitor), move(IPath, int, IProgressMonitor), Constant Field Values

AVOID_NATURE_CONFIG

public static final int AVOID_NATURE_CONFIG

Update flag constant (bit mask value 64) indicating that setting the project description should not attempt to configure and de-configure natures.

Since:

3.0

See Also:

IProject.setDescription(IProjectDescription, int, IProgressMonitor), Constant Field Values

BACKGROUND_REFRESH

public static final int BACKGROUND_REFRESH

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.

Since:

3.1

See Also:

IProject.open(int, IProgressMonitor), IFolder.createLink(URI, int, IProgressMonitor), Constant Field Values

REPLACE

public static final int REPLACE

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.

Since:

3.2

See Also:

IFile.createLink(URI, int, IProgressMonitor), IFolder.createLink(URI, int, IProgressMonitor), move(IProjectDescription, int, IProgressMonitor), Constant Field Values

CHECK_ANCESTORS

public static final int CHECK_ANCESTORS

Update flag constant (bit mask value 512) indicating that ancestor resources of the target resource should be checked.

Since:

3.2

See Also:

isLinked(int), Constant Field Values

DERIVED

public static final int DERIVED

Update flag constant (bit mask value 0x400) indicating that a resource should be marked as derived.

Since:

3.2

See Also:

IFile.create(java.io.InputStream, int, IProgressMonitor), IFolder.create(int, boolean, IProgressMonitor), setDerived(boolean), Constant Field Values

TEAM_PRIVATE

public static final int TEAM_PRIVATE

Update flag constant (bit mask value 0x800) indicating that a resource should be marked as team private.

Since:

3.2

See Also:

IFile.create(java.io.InputStream, int, IProgressMonitor), IFolder.create(int, boolean, IProgressMonitor), copy(IPath, int, IProgressMonitor), setTeamPrivateMember(boolean), Constant Field Values

HIDDEN

public static final int HIDDEN

Update flag constant (bit mask value 0x1000) indicating that a resource should be marked as a hidden resource.

Since:

3.4

See Also:

Constant Field Values

NULL_STAMP

public static final int NULL_STAMP

Modification stamp constant (value -1) indicating no modification stamp is available.

See Also:

getModificationStamp(), Constant Field Values

NONE

public static final int NONE

General purpose zero-valued bit mask constant. Useful whenever you need to supply a bit mask with no bits set.

Example usage:

    delete(IResource.NONE, null)
 

Since:

2.0

See Also:

Constant Field Values

Method Detail

accept

public void accept(IResourceProxyVisitor visitor,
                   int memberFlags)
            throws CoreException

Accepts the given visitor for an optimized traversal. The visitor's visit 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.

The entire subtree under the given resource is traversed to infinite depth, unless the visitor ignores a subtree by returning false from its visit method.

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.

If the IContainer.INCLUDE_PHANTOMS flag is not specified in the member flags (recommended), only member resources that exist will be visited. If the IContainer.INCLUDE_PHANTOMS flag is specified, the visit will also include any phantom member resource that the workspace is keeping track of.

If the IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS flag is not specified (recommended), team private members will not be visited. If the IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS flag is specified in the member flags, team private member resources are visited as well.

If the IContainer.INCLUDE_HIDDEN flag is not specified (recommended), hidden resources will not be visited. If the IContainer.INCLUDE_HIDDEN flag is specified in the member flags, hidden resources are visited as well.

Parameters:

visitor - the visitor

memberFlags - bit-wise or of member flag constants (IContainer.INCLUDE_PHANTOMS, IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS and IContainer.INCLUDE_HIDDEN) indicating which members are of interest

Throws:

CoreException - if this request fails. Reasons include:

• the IContainer.INCLUDE_PHANTOMS flag is not specified and this resource does not exist.
• the IContainer.INCLUDE_PHANTOMS flag is not specified and this resource is a project that is not open.
• The visitor failed with this exception.

Since:

2.1

See Also:

IContainer.INCLUDE_PHANTOMS, IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS, IContainer.INCLUDE_HIDDEN, isPhantom(), isTeamPrivateMember(), IResourceProxyVisitor.visit(IResourceProxy)

accept

public void accept(IResourceVisitor visitor)
            throws CoreException

Accepts the given visitor. The visitor's visit method is called with this resource. If the visitor returns true, this method visits this resource's members.

This is a convenience method, fully equivalent to accept(visitor, IResource.DEPTH_INFINITE, IResource.NONE).

Parameters:

visitor - the visitor

Throws:

CoreException - if this method fails. Reasons include:

• This resource does not exist.
• The visitor failed with this exception.

See Also:

IResourceVisitor.visit(IResource), accept(IResourceVisitor,int,int)

accept

public void accept(IResourceVisitor visitor,
                   int depth,
                   boolean includePhantoms)
            throws CoreException

Accepts the given visitor. The visitor's visit method is called with this resource. If the visitor returns false, this resource's members are not visited.

The subtree under the given resource is traversed to the supplied depth.

This is a convenience method, fully equivalent to:

   accept(visitor, depth, includePhantoms ? IContainer.INCLUDE_PHANTOMS : IResource.NONE);
 

Parameters:

visitor - the visitor

depth - the depth to which members of this resource should be visited. One of DEPTH_ZERO, DEPTH_ONE, or DEPTH_INFINITE.

includePhantoms - true if phantom resources are of interest; false if phantom resources are not of interest.

Throws:

CoreException - if this request fails. Reasons include:

• includePhantoms is false and this resource does not exist.
• includePhantoms is true and this resource does not exist and is not a phantom.
• The visitor failed with this exception.

See Also:

isPhantom(), IResourceVisitor.visit(IResource), DEPTH_ZERO, DEPTH_ONE, DEPTH_INFINITE, accept(IResourceVisitor,int,int)

accept

public void accept(IResourceVisitor visitor,
                   int depth,
                   int memberFlags)
            throws CoreException

Accepts the given visitor. The visitor's visit method is called with this resource. If the visitor returns false, this resource's members are not visited.

The subtree under the given resource is traversed to the supplied depth.

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 the IContainer.INCLUDE_PHANTOMS flag is not specified in the member flags (recommended), only member resources that exists are visited. If the IContainer.INCLUDE_PHANTOMS flag is specified, the visit also includes any phantom member resource that the workspace is keeping track of.

If the IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS flag is not specified (recommended), team private members are not visited. If the IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS flag is specified in the member flags, team private member resources are visited as well.

If the IContainer.EXCLUDE_DERIVED flag is not specified (recommended), derived resources are visited. If the IContainer.EXCLUDE_DERIVED flag is specified in the member flags, derived resources are not visited.

If the IContainer.INCLUDE_HIDDEN flag is not specified (recommended), hidden resources will not be visited. If the IContainer.INCLUDE_HIDDEN flag is specified in the member flags, hidden resources are visited as well.

Parameters:

visitor - the visitor

depth - the depth to which members of this resource should be visited. One of DEPTH_ZERO, DEPTH_ONE, or DEPTH_INFINITE.

memberFlags - bit-wise or of member flag constants (IContainer.INCLUDE_PHANTOMS, IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS, IContainer.INCLUDE_HIDDEN and IContainer.EXCLUDE_DERIVED) indicating which members are of interest

Throws:

CoreException - if this request fails. Reasons include:

• the IContainer.INCLUDE_PHANTOMS flag is not specified and this resource does not exist.
• the IContainer.INCLUDE_PHANTOMS flag is not specified and this resource is a project that is not open.
• The visitor failed with this exception.

Since:

2.0

See Also:

IContainer.INCLUDE_PHANTOMS, IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS, IContainer.INCLUDE_HIDDEN, IContainer.EXCLUDE_DERIVED, isDerived(), isPhantom(), isTeamPrivateMember(), isHidden(), DEPTH_ZERO, DEPTH_ONE, DEPTH_INFINITE, IResourceVisitor.visit(IResource)

clearHistory

public void clearHistory(IProgressMonitor monitor)
                  throws CoreException

Removes the local history of this resource and its descendents.

This operation is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException

copy

public void copy(IPath destination,
                 boolean force,
                 IProgressMonitor monitor)
          throws CoreException

Makes a copy of this resource at the given path.

This is a convenience method, fully equivalent to:

   copy(destination, (force ? FORCE : IResource.NONE), monitor);
 

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.

This operation is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

destination - the destination path

force - a flag controlling whether resources that are not in sync with the local file system will be tolerated

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this resource could not be copied. Reasons include:

• This resource does not exist.
• This resource or one of its descendents is not local.
• The source or destination is the workspace root.
• The source is a project but the destination is not.
• The destination is a project but the source is not.
• The resource corresponding to the parent destination path does not exist.
• The resource corresponding to the parent destination path is a closed project.
• A resource at destination path does exist.
• This resource or one of its descendents is out of sync with the local file system and force is false.
• The workspace and the local file system are out of sync at the destination resource or one of its descendents.
• The source resource is a file and the destination path specifies a project.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

copy

public void copy(IPath destination,
                 int updateFlags,
                 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.

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.

Calling this method with a one segment absolute destination path is equivalent to calling:

   copy(workspace.newProjectDescription(folder.getName()),updateFlags,monitor);
 

When a resource is copied, its persistent properties are copied with it. Session properties and markers are not copied.

The FORCE update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If FORCE 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 FORCE 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 FORCE 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.

The SHALLOW update flag controls how this method deals with linked resources. If SHALLOW 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 SHALLOW 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 SHALLOW flag, copying of linked resources into anything other than a project is not permitted. The SHALLOW update flag is ignored when copying non- linked resources.

The DERIVED update flag indicates that the new resource should immediately be set as a derived resource. Specifying this flag is equivalent to atomically calling setDerived(boolean) with a value of true immediately after creating the resource.

The 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 setTeamPrivateMember(boolean) with a value of true immediately after creating the resource.

The HIDDEN update flag indicates that the new resource should immediately be set as a hidden resource. Specifying this flag is equivalent to atomically calling setHidden(boolean) with a value of true immediately after creating the resource.

Update flags other than those listed above are ignored.

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.

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.

This operation is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

destination - the destination path

updateFlags - bit-wise or of update flag constants (FORCE, SHALLOW, DERIVED, TEAM_PRIVATE, HIDDEN)

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this resource could not be copied. Reasons include:

• This resource does not exist.
• This resource or one of its descendents is not local.
• The source or destination is the workspace root.
• The source is a project but the destination is not.
• The destination is a project but the source is not.
• The resource corresponding to the parent destination path does not exist.
• The resource corresponding to the parent destination path is a closed project.
• The source is a linked resource, but the destination is not a project, and SHALLOW is specified.
• A resource at destination path does exist.
• This resource or one of its descendants is out of sync with the local file system and FORCE is not specified.
• The workspace and the local file system are out of sync at the destination resource or one of its descendants.
• The source resource is a file and the destination path specifies a project.
• The source is a linked resource, and the destination path does not specify a project.
• The location of the source resource on disk is the same or a prefix of the location of the destination resource on disk.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancellation can occur even if no progress monitor is provided.

Since:

2.0

See Also:

FORCE, SHALLOW, DERIVED, TEAM_PRIVATE, IResourceRuleFactory.copyRule(IResource, IResource)

copy

public void copy(IProjectDescription description,
                 boolean force,
                 IProgressMonitor monitor)
          throws CoreException

Makes a copy of this project using the given project description.

This is a convenience method, fully equivalent to:

   copy(description, (force ? FORCE : IResource.NONE), monitor);
 

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.

This operation is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the destination project description

force - a flag controlling whether resources that are not in sync with the local file system will be tolerated

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this resource could not be copied. Reasons include:

• This resource does not exist.
• This resource or one of its descendents is not local.
• This resource is not a project.
• The project described by the given description already exists.
• This resource or one of its descendents is out of sync with the local file system and force is false.
• The workspace and the local file system are out of sync at the destination resource or one of its descendents.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

copy

public void copy(IProjectDescription description,
                 int updateFlags,
                 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.

When a resource is copied, its persistent properties are copied with it. Session properties and markers are not copied.

The FORCE update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If FORCE 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 FORCE 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 FORCE 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.

The SHALLOW update flag controls how this method deals with linked resources. If SHALLOW 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 SHALLOW 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 SHALLOW update flag is ignored when copying non- linked resources.

Update flags other than FORCE or SHALLOW are ignored.

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.

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.

This operation is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the destination project description

updateFlags - bit-wise or of update flag constants (FORCE and SHALLOW)

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this resource could not be copied. Reasons include:

• This resource does not exist.
• This resource or one of its descendents is not local.
• This resource is not a project.
• The project described by the given description already exists.
• This resource or one of its descendents is out of sync with the local file system and FORCE is not specified.
• The workspace and the local file system are out of sync at the destination resource or one of its descendents.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

Since:

2.0

See Also:

FORCE, SHALLOW, IResourceRuleFactory.copyRule(IResource, IResource)

createMarker

public IMarker createMarker(String type)
                     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 org.eclipse.core.resources.markers extension point. The specified type string must not be null.

Parameters:

type - the type of the marker to create

Returns:

the handle of the new marker

Throws:

CoreException - if this method fails. Reasons include:

• This resource does not exist.
• This resource is a project that is not open.

See Also:

IResourceRuleFactory.markerRule(IResource)

createProxy

public IResourceProxy createProxy()

Creates a resource proxy representing the current state of this resource.

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.

Returns:

A proxy representing this resource

Since:

3.2

delete

public void delete(boolean force,
                   IProgressMonitor monitor)
            throws CoreException

Deletes this resource from the workspace.

This is a convenience method, fully equivalent to:

   delete(force ? FORCE : IResource.NONE, monitor);
 

This method changes resources; these changes will be reported in a subsequent resource change event.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

force - a flag controlling whether resources that are not in sync with the local file system will be tolerated

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this method fails. Reasons include:

• This resource could not be deleted for some reason.
• This resource or one of its descendents is out of sync with the local file system and force is false.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

See Also:

delete(int,IProgressMonitor)

delete

public void delete(int updateFlags,
                   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.

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.

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.

Deleting a resource also deletes its session and persistent properties and markers.

Deleting a non-project resource which has sync information converts the resource to a phantom and retains the sync information for future use.

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.

This method changes resources; these changes will be reported in a subsequent resource change event.

This method is long-running; progress and cancellation are provided by the given progress monitor.

The FORCE update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If 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 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.

The 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 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 KEEP_HISTORY is only really applicable when deleting files and folders, but not projects.

The ALWAYS_DELETE_PROJECT_CONTENT update flag controls how project deletions are handled. If 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; FORCE is assumed regardless of whether it is specified. If 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 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 FORCE flag), but never from closed projects.

Parameters:

updateFlags - bit-wise or of update flag constants ( FORCE, KEEP_HISTORY, ALWAYS_DELETE_PROJECT_CONTENT, and NEVER_DELETE_PROJECT_CONTENT)

monitor - a progress monitor, or null if progress reporting is not desired

Throws:

CoreException - if this method fails. Reasons include:

• This resource could not be deleted for some reason.
• This resource or one of its descendents is out of sync with the local file system and FORCE is not specified.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

OperationCanceledException - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.

Since:

2.0

See Also:

IFile.delete(boolean, boolean, IProgressMonitor), IFolder.delete(boolean, boolean, IProgressMonitor), FORCE, KEEP_HISTORY, ALWAYS_DELETE_PROJECT_CONTENT, NEVER_DELETE_PROJECT_CONTENT, IResourceRuleFactory.deleteRule(IResource)

deleteMarkers

public void deleteMarkers(String type,
                          boolean includeSubtypes,
                          int depth)
                   throws CoreException

Deletes all markers on this resource of the given type, and, optionally, deletes such markers from its children. If includeSubtypes is false, only markers whose type exactly matches the given type are deleted.

This method changes resources; these changes will be reported in a subsequent resource change event.

Parameters:

type - the type of marker to consider, or null to indicate all types

includeSubtypes - whether or not to consider sub-types of the given type

depth - how far to recurse (see IResource.DEPTH_* )

Throws:

CoreException - if this method fails. Reasons include:

• This resource does not exist.
• This resource is a project that is not open.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

DEPTH_ZERO, DEPTH_ONE, DEPTH_INFINITE, IResourceRuleFactory.markerRule(IResource)

equals

public boolean equals(Object other)

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.

Parameters:

other - the other object

Returns:

an indication of whether the objects are equals

See Also:

getType(), getFullPath(), getWorkspace()

exists

public boolean exists()

Returns whether this resource exists in the workspace.

IResource 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 exist, and this method returns true; in all other cases, this method returns false. In particular, it returns false 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.

Note that no resources ever exist under a project that is closed; opening a project may bring some resources into existence.

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.

Returns:

true if the resource exists, otherwise false

findMarker

public IMarker findMarker(long id)
                   throws CoreException

Returns the marker with the specified id on this resource, Returns null if there is no matching marker.

Parameters:

id - the id of the marker to find

Returns:

a marker or null

Throws:

CoreException - if this method fails. Reasons include:

• This resource does not exist.
• This resource is a project that is not open.

fin