Package org.eclipse.core.resources

Interface IContainer

All Superinterfaces:

IAdaptable, IResource, ISchedulingRule

All Known Subinterfaces:

IFolder, IProject, IWorkspaceRoot

public interface IContainer
extends IResource, IAdaptable

Interface for resources which may contain other resources (termed its members). While the workspace itself is not considered a container in this sense, the workspace root resource is a container.

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

See Also:

• Platform.getAdapterManager()
• IProject
• IFolder
• IWorkspaceRoot

Restriction:

This interface is not intended to be implemented by clients.

Restriction:

This interface is not intended to be extended by clients.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DO_NOT_CHECK_EXISTENCE	Member constant (bit mask value 16) indicating that a resource should not be checked for existence.
static final int	EXCLUDE_DERIVED	Member constant (bit mask value 4) indicating that derived resources are to be excluded.
static final int	INCLUDE_HIDDEN	Member constant (bit mask value 8) indicating that hidden resources are to be included.
static final int	INCLUDE_PHANTOMS	Member constant (bit mask value 1) indicating that phantom member resources are to be included.
static final int	INCLUDE_TEAM_PRIVATE_MEMBERS	Member constant (bit mask value 2) indicating that team private members are to be included.

Fields inherited from interface org.eclipse.core.resources.IResource

ALLOW_MISSING_LOCAL, ALWAYS_DELETE_PROJECT_CONTENT, AVOID_NATURE_CONFIG, BACKGROUND_REFRESH, CHECK_ANCESTORS, DEPTH_INFINITE, DEPTH_ONE, DEPTH_ZERO, DERIVED, FILE, FOLDER, FORCE, HIDDEN, KEEP_HISTORY, NEVER_DELETE_PROJECT_CONTENT, NONE, NULL_STAMP, PROJECT, REPLACE, ROOT, SHALLOW, TEAM_PRIVATE, VIRTUAL

Method Summary

Modifier and Type	Method	Description
IResourceFilterDescription	createFilter(int type, FileInfoMatcherDescription matcherDescription, int updateFlags, IProgressMonitor monitor)	Adds a new filter to this container.
boolean	exists(IPath path)	Returns whether a resource of some type with the given path exists relative to this resource.
IFile[]	findDeletedMembersWithHistory(int depth, IProgressMonitor monitor)	Returns a list of recently deleted files inside this container that have one or more saved states in the local history.
IResource	findMember(String path)	Finds and returns the member resource identified by the given path in this container, or null if no such resource exists.
IResource	findMember(String path, boolean includePhantoms)	Finds and returns the member resource identified by the given path in this container, or null if no such resource exists.
IResource	findMember(IPath path)	Finds and returns the member resource identified by the given path in this container, or null if no such resource exists.
IResource	findMember(IPath path, boolean includePhantoms)	Finds and returns the member resource identified by the given path in this container, or null if no such resource exists.
String	getDefaultCharset()	Returns the default charset for resources in this container.
String	getDefaultCharset(boolean checkImplicit)	Returns the default charset for resources in this container.
IFile	getFile(IPath path)	Returns a handle to the file identified by the given path in this container.
IResourceFilterDescription[]	getFilters()	Retrieve all filters on this container.
IFolder	getFolder(IPath path)	Returns a handle to the folder identified by the given path in this container.
IResource[]	members()	Returns a list of existing member resources (projects, folders and files) in this resource, in no particular order.
IResource[]	members(boolean includePhantoms)	Returns a list of all member resources (projects, folders and files) in this resource, in no particular order.
IResource[]	members(int memberFlags)	Returns a list of all member resources (projects, folders and files) in this resource, in no particular order.
void	setDefaultCharset(String charset)	Deprecated. Replaced by setDefaultCharset(String, IProgressMonitor) which is a workspace operation and reports changes in resource deltas.
void	setDefaultCharset(String charset, IProgressMonitor monitor)	Sets the default charset for this container.

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

getAdapter

Methods inherited from interface org.eclipse.core.resources.IResource

accept, accept, accept, accept, accept, clearHistory, copy, copy, copy, copy, createMarker, createMarker, createProxy, delete, delete, deleteMarkers, equals, exists, findMarker, findMarkers, findMaxProblemSeverity, getFileExtension, getFullPath, getLocalTimeStamp, getLocation, getLocationURI, getMarker, getModificationStamp, getName, getParent, getPathVariableManager, getPersistentProperties, getPersistentProperty, getProject, getProjectRelativePath, getRawLocation, getRawLocationURI, getResourceAttributes, getSessionProperties, getSessionProperty, getType, getWorkspace, isAccessible, isDerived, isDerived, isHidden, isHidden, isLinked, isLinked, isLocal, isPhantom, isReadOnly, isSynchronized, isTeamPrivateMember, isTeamPrivateMember, isVirtual, move, move, move, move, refreshLocal, revertModificationStamp, setDerived, setDerived, setHidden, setLocal, setLocalTimeStamp, setPersistentProperty, setReadOnly, setResourceAttributes, setSessionProperty, setTeamPrivateMember, touch

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

contains, isConflicting

Field Details

INCLUDE_PHANTOMS

static final int INCLUDE_PHANTOMS

Member constant (bit mask value 1) indicating that phantom member resources are to be included.

Since:

2.0

See Also:

• IResource.isPhantom()
• Constant Field Values

INCLUDE_TEAM_PRIVATE_MEMBERS

static final int INCLUDE_TEAM_PRIVATE_MEMBERS

Member constant (bit mask value 2) indicating that team private members are to be included.

Since:

2.0

See Also:

• IResource.isTeamPrivateMember()
• Constant Field Values

EXCLUDE_DERIVED

static final int EXCLUDE_DERIVED

Member constant (bit mask value 4) indicating that derived resources are to be excluded.

Since:

3.1

See Also:

• IResource.isDerived()
• Constant Field Values

INCLUDE_HIDDEN

static final int INCLUDE_HIDDEN

Member constant (bit mask value 8) indicating that hidden resources are to be included.

Since:

3.4

See Also:

• IResource.isHidden()
• Constant Field Values

DO_NOT_CHECK_EXISTENCE

static final int DO_NOT_CHECK_EXISTENCE

Member constant (bit mask value 16) indicating that a resource should not be checked for existence.

Since:

3.8

See Also:

• IResource.accept(IResourceProxyVisitor, int)
• IResource.accept(IResourceVisitor, int, int)
• Constant Field Values

Method Details

exists

boolean exists(IPath path)

Returns whether a resource of some type with the given path exists relative to this resource. The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource. Trailing separators are ignored. If the path is empty this container is checked for existence.

Parameters:

path - the path of the resource

Returns:

true if a resource of some type with the given path exists relative to this resource, and false otherwise

See Also:

• IResource.exists()

findMember

IResource findMember(String path)

Finds and returns the member resource identified by the given path in this container, or null if no such resource exists. The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource. Trailing separators and the path's device are ignored. If the path is empty this container is returned. Parent references in the supplied path are discarded if they go above the workspace root.

Note that no attempt is made to exclude team-private member resources as with members.

N.B. Unlike the methods which traffic strictly in resource handles, this method infers the resulting resource's type from the resource existing at the calculated path in the workspace.

Note that path contains a relative path to the resource and all path special characters will be interpreted. Passing an empty string will result in returning this IContainer itself.

Parameters:

path - the relative path to the member resource, must be a valid path or path segment

Returns:

the member resource, or null if no such resource exists

See Also:

• members()
• IPath.isValidPath(String)
• IPath.isValidSegment(String)

findMember

IResource findMember(String path,
 boolean includePhantoms)

Finds and returns the member resource identified by the given path in this container, or null if no such resource exists. The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource. Trailing separators and the path's device are ignored. If the path is empty this container is returned. Parent references in the supplied path are discarded if they go above the workspace root.

If the includePhantoms argument is false, only a member resource with the given path that exists will be returned. If the includePhantoms argument is true, the method also returns a resource if the workspace is keeping track of a phantom with that path.

Note that no attempt is made to exclude team-private member resources as with members.

N.B. Unlike the methods which traffic strictly in resource handles, this method infers the resulting resource's type from the resource (or phantom) existing at the calculated path in the workspace.

Note that path contains a relative path to the resource and all path special characters will be interpreted. Passing an empty string will result in returning this IContainer itself.

Parameters:

path - the relative path to the member resource, must be a valid path or path segment

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

Returns:

the member resource, or null if no such resource exists

See Also:

• members(boolean)
• IResource.isPhantom()
• IPath.isValidPath(String)
• IPath.isValidSegment(String)

findMember

IResource findMember(IPath path)

Finds and returns the member resource identified by the given path in this container, or null if no such resource exists. The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource. Trailing separators and the path's device are ignored. If the path is empty this container is returned. Parent references in the supplied path are discarded if they go above the workspace root.

Note that no attempt is made to exclude team-private member resources as with members.

N.B. Unlike the methods which traffic strictly in resource handles, this method infers the resulting resource's type from the resource existing at the calculated path in the workspace.

Parameters:

path - the path of the desired resource

Returns:

the member resource, or null if no such resource exists

findMember

IResource findMember(IPath path,
 boolean includePhantoms)

Finds and returns the member resource identified by the given path in this container, or null if no such resource exists. The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource. Trailing separators and the path's device are ignored. If the path is empty this container is returned. Parent references in the supplied path are discarded if they go above the workspace root.

If the includePhantoms argument is false, only a member resource with the given path that exists will be returned. If the includePhantoms argument is true, the method also returns a resource if the workspace is keeping track of a phantom with that path.

Note that no attempt is made to exclude team-private member resources as with members.

N.B. Unlike the methods which traffic strictly in resource handles, this method infers the resulting resource's type from the resource (or phantom) existing at the calculated path in the workspace.

Parameters:

path - the path of the desired resource

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

Returns:

the member resource, or null if no such resource exists

See Also:

• members(boolean)
• IResource.isPhantom()

getDefaultCharset

String getDefaultCharset()
                  throws CoreException

Returns the default charset for resources in this container.

This is a convenience method, fully equivalent to:

   getDefaultCharset(true);
 

Note that this method does not check whether the result is a supported charset name. Callers should be prepared to handle UnsupportedEncodingException where this charset is used.

Returns:

the name of the default charset encoding for this container

Throws:

CoreException - if this method fails

Since:

3.0

See Also:

• getDefaultCharset(boolean)
• IFile.getCharset()

getDefaultCharset

String getDefaultCharset(boolean checkImplicit)
                  throws CoreException

Returns the default charset for resources in this container.

If checkImplicit is false, this method will return the charset defined by calling #setDefaultCharset, provided this container exists, or null otherwise.

If checkImplicit is true, this method uses the following algorithm to determine the charset to be returned:

1. the one explicitly set by calling #setDefaultCharset (with a non-null argument) on this container, if any, and this container exists, or
2. the parent's default charset, if this container has a parent (is not the workspace root), or
3. the charset returned by ResourcesPlugin#getEncoding.

Note that this method does not check whether the result is a supported charset name. Callers should be prepared to handle UnsupportedEncodingException where this charset is used.

Returns:

the name of the default charset encoding for this container, or null

Throws:

CoreException - if this method fails

Since:

3.0

See Also:

• IFile.getCharset()

getFile

IFile getFile(IPath path)

Returns a handle to the file identified by the given path in this container.

This is a resource handle operation; neither the resource nor the result need exist in the workspace. The validation check on the resource name/path is not done when the resource handle is constructed; rather, it is done automatically as the resource is created.

The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource and is appended to this container's full path to form the full path of the resultant resource. A trailing separator is ignored. The path of the resulting resource must have at least two segments.

Parameters:

path - the path of the member file

Returns:

the (handle of the) member file

See Also:

• getFolder(IPath)

getFolder

IFolder getFolder(IPath path)

Returns a handle to the folder identified by the given path in this container.

This is a resource handle operation; neither the resource nor the result need exist in the workspace. The validation check on the resource name/path is not done when the resource handle is constructed; rather, it is done automatically as the resource is created.

The supplied path may be absolute or relative; in either case, it is interpreted as relative to this resource and is appended to this container's full path to form the full path of the resultant resource. A trailing separator is ignored. The path of the resulting resource must have at least two segments.

Parameters:

path - the path of the member folder

Returns:

the (handle of the) member folder

See Also:

• getFile(IPath)

members

IResource[] members()
             throws CoreException

Returns a list of existing member resources (projects, folders and files) in this resource, in no particular order.

This is a convenience method, fully equivalent to members(IResource.NONE). Team-private member resources are not included in the result.

Note that the members of a project or folder are the files and folders immediately contained within it. The members of the workspace root are the projects in the workspace.

Returns:

an array of members of this resource

Throws:

CoreException - if this request fails. Reasons include:

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

See Also:

• findMember(IPath)
• IResource.isAccessible()

members

IResource[] members(boolean includePhantoms)
             throws CoreException

Returns a list of all member resources (projects, folders and files) in this resource, in no particular order.

This is a convenience method, fully equivalent to:

   members(includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
 

Team-private member resources are not included in the result.

Parameters:

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

Returns:

an array of members of this resource

Throws:

CoreException - if this request fails. Reasons include:

• This resource does not exist.
• includePhantoms is false and this resource does not exist.
• includePhantoms is false and this resource is a project that is not open.

See Also:

• members(int)
• IResource.exists()
• IResource.isPhantom()

members

IResource[] members(int memberFlags)
             throws CoreException

Returns a list of all member resources (projects, folders and files) in this resource, in no particular order.

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

If the INCLUDE_TEAM_PRIVATE_MEMBERS flag is specified in the member flags, team private members will be included along with the others. If the INCLUDE_TEAM_PRIVATE_MEMBERS flag is not specified (recommended), the result will omit any team private member resources.

If the INCLUDE_HIDDEN flag is specified in the member flags, hidden members will be included along with the others. If the INCLUDE_HIDDEN flag is not specified (recommended), the result will omit any hidden member resources.

If the EXCLUDE_DERIVED flag is not specified, derived resources are included. If the EXCLUDE_DERIVED flag is specified in the member flags, derived resources are not included.

Parameters:

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

Returns:

an array of members of this resource

Throws:

CoreException - if this request fails. Reasons include:

• This resource does not exist.
• the INCLUDE_PHANTOMS flag is not specified and this resource does not exist.
• the INCLUDE_PHANTOMS flag is not specified and this resource is a project that is not open.

Since:

2.0

See Also:

• IResource.exists()

findDeletedMembersWithHistory

IFile[] findDeletedMembersWithHistory(int depth,
 IProgressMonitor monitor)
                               throws CoreException

Returns a list of recently deleted files inside this container that have one or more saved states in the local history. The depth parameter determines how deep inside the container to look. This resource may or may not exist in the workspace.

When applied to an existing project resource, this method returns recently deleted files with saved states in that project. Note that local history is maintained with each individual project, and gets discarded when a project is deleted from the workspace. If applied to a deleted project, this method returns the empty list.

When applied to the workspace root resource (depth infinity), this method returns all recently deleted files with saved states in all existing projects.

When applied to a folder (or project) resource (depth one), this method returns all recently deleted member files with saved states.

When applied to a folder resource (depth zero), this method returns an empty list unless there was a recently deleted file with saved states at the same path as the folder.

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

Parameters:

depth - depth limit: one of DEPTH_ZERO, DEPTH_ONE or DEPTH_INFINITE

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

Returns:

an array of recently deleted files

Throws:

CoreException - if this method fails

Since:

2.0

See Also:

• IFile.getHistory(IProgressMonitor)

setDefaultCharset

@Deprecated
void setDefaultCharset(String charset)
                throws CoreException

Deprecated.

Replaced by setDefaultCharset(String, IProgressMonitor) which is a workspace operation and reports changes in resource deltas.

Sets the default charset for this container. Passing a value of null will remove the default charset setting for this resource.

Parameters:

charset - a charset string, or null

Throws:

CoreException - if this method fails Reasons include:

• This resource does not exist.
• An error happened while persisting this setting.

Since:

3.0

See Also:

• getDefaultCharset()

setDefaultCharset

void setDefaultCharset(String charset,
 IProgressMonitor monitor)
                throws CoreException

Sets the default charset for this container. Passing a value of null will remove the default charset setting for this resource.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the encoding of affected resources has been changed.

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

Parameters:

charset - a charset string, or null

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

Throws:

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

CoreException - if this method fails Reasons include:

• This resource is not accessible.
• An error happened while persisting this setting.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

Since:

3.0

See Also:

• getDefaultCharset()
• IResourceRuleFactory.charsetRule(IResource)

createFilter

IResourceFilterDescription createFilter(int type,
 FileInfoMatcherDescription matcherDescription,
 int updateFlags,
 IProgressMonitor monitor)
                                 throws CoreException

Adds a new filter to this container. Filters restrict the set of files and directories in the underlying file system that will be included as members of this container.

The IResource.BACKGROUND_REFRESH update flag controls when changes to the resource hierarchy under this container resulting from the new filter take effect. If this flag is specified, the resource hierarchy is updated in a separate thread after this method returns. If the flag is not specified, any resource changes resulting from the new filter will occur before this method returns.

This operation changes resources; these changes will be reported in a subsequent resource change event that will include an indication of any resources that have been removed as a result of the new filter.

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

Parameters:

type - (IResourceFilterDescription.INCLUDE_ONLY or IResourceFilterDescription.EXCLUDE_ALL and/or IResourceFilterDescription.INHERITABLE)

matcherDescription - the description of the matcher that will determine which IFileInfo instances will be excluded from the resource tree

updateFlags - bit-wise or of update flag constants (IResource.BACKGROUND_REFRESH)

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

Returns:

the description of the added filter

Throws:

CoreException - if this filter could not be added. Reasons include:

• 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:

3.6

See Also:

• getFilters()
• IResourceFilterDescription.delete(int, IProgressMonitor)

getFilters

IResourceFilterDescription[] getFilters()
                                 throws CoreException

Retrieve all filters on this container. If no filters exist for this resource, an empty array is returned.

Returns:

an array of filters

Throws:

CoreException - if this resource's filters could not be retrieved. Reasons include:

• This resource is not a folder.

Since:

3.6

See Also:

• createFilter(int, FileInfoMatcherDescription, int, IProgressMonitor)
• IResourceFilterDescription.delete(int, IProgressMonitor)