org.eclipse.core.resources.IWorkspaceRoot Maven / Gradle / Ivy
Show all versions of aspectjtools Show documentation
/*******************************************************************************
* Copyright (c) 2000, 2016 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import java.net.URI;
import org.eclipse.core.runtime.*;
/**
* A root resource represents the top of the resource hierarchy in a workspace.
* There is exactly one root in a workspace. The root resource has the following
* behavior:
*
* - It cannot be moved or copied
* - It always exists.
* - Deleting the root deletes all of the children under the root but leaves the root itself
* - It is always local.
* - It is never a phantom.
*
*
* Workspace roots implement the IAdaptable interface;
* extensions are managed by the platform's adapter manager.
*
*
* @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 IWorkspaceRoot extends IContainer, IAdaptable {
/**
* Deletes everything in the workspace except the workspace root resource
* itself.
*
* This is a convenience method, fully equivalent to:
*
*
* delete(
* (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT )
* | (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.
*
*
* @param deleteContent a flag controlling how whether content is
* aggressively deleted
* @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 null if progress
* reporting is not desired
* @exception CoreException if this method fails. Reasons include:
*
* - A project could not be deleted.
* - A project's contents could not be deleted.
* - Resource changes are disallowed during certain types of resource change
* event notification. See
IResourceChangeEvent for more details.
*
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see IResource#delete(int,IProgressMonitor)
*/
void delete(boolean deleteContent, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Returns the handles to all the resources (workspace root, project,
* folder) in the workspace which are mapped to the given path in the local
* file system. Returns an empty array if there are none.
*
* If the path maps to the platform working location, the returned object
* will be a single element array consisting of an object of type
* ROOT.
*
*
* If the path maps to a project, the resulting array will contain a
* resource of type PROJECT, along with any linked folders that
* share the same location. Otherwise the resulting array will contain
* folders (type FOLDER).
*
*
* The path should be absolute; a relative path will be treated as absolute.
* The path segments need not be valid names; a trailing separator is
* ignored. The resulting resources may not currently exist.
*
*
* The result will omit team private members and hidden resources. The
* result will omit resources within team private members or hidden
* containers.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* @param location
* a path in the local file system
* @return the corresponding containers in the workspace, or an empty array
* if none
* @since 2.1
* @deprecated use {@link #findContainersForLocationURI(URI)} instead
*/
@Deprecated
IContainer[] findContainersForLocation(IPath location);
/**
* Returns the handles to all the resources (workspace root, project,
* folder) in the workspace which are mapped to the given URI. Returns an
* empty array if there are none.
*
* If the path maps to the platform working location, the returned object
* will be a single element array consisting of an object of type
* ROOT.
*
*
* If the path maps to a project, the resulting array will contain a
* resource of type PROJECT, along with any linked folders that
* share the same location. Otherwise the resulting array will contain
* folders (type FOLDER).
*
*
* The URI must be absolute; its segments need not be valid names; a
* trailing separator is ignored. The resulting resources may not currently
* exist.
*
*
* The result will omit team private members and hidden resources. The
* result will omit resources within team private member sor hidden
* containers.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* This is a convenience method, fully equivalent to
* findContainersForLocationURI(location, IResource.NONE).
*
*
* @param location
* a URI path into some file system
* @return the corresponding containers in the workspace, or an empty array
* if none
* @since 3.2
*/
IContainer[] findContainersForLocationURI(URI location);
/**
* Returns the handles to all the resources (workspace root, project,
* folder) in the workspace which are mapped to the given URI. Returns an
* empty array if there are none.
*
* If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the
* member flags, team private members will be included along with the
* others. If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not
* specified (recommended), the result will omit any team private member
* resources.
*
*
* If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags,
* hidden members will be included along with the others. If the
* {@link #INCLUDE_HIDDEN} flag is not specified (recommended), the result
* will omit any hidden member resources.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* @param location
* a URI path into some file system
* @param memberFlags
* bit-wise or of member flag constants (
* {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} and {@link #INCLUDE_HIDDEN})
* indicating which members are of interest
* @return the corresponding files in the workspace, or an empty array if
* none
* @since 3.5
*/
IContainer[] findContainersForLocationURI(URI location, int memberFlags);
/**
* Returns the handles of all files that are mapped to the given path in the
* local file system. Returns an empty array if there are none. The path
* should be absolute; a relative path will be treated as absolute. The path
* segments need not be valid names. The resulting files may not currently
* exist.
*
* The result will omit any team private member and hidden resources. The
* result will omit resources within team private member or hidden
* containers.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* @param location
* a path in the local file system
* @return the corresponding files in the workspace, or an empty array if
* none
* @since 2.1
* @deprecated use {@link #findFilesForLocationURI(URI)} instead
*/
@Deprecated
IFile[] findFilesForLocation(IPath location);
/**
* Returns the handles of all files that are mapped to the given URI.
* Returns an empty array if there are none. The URI must be absolute; its
* path segments need not be valid names. The resulting files may not
* currently exist.
*
* The result will omit any team private member and hidden resources. The
* result will omit resources within team private member or hidden
* containers.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* This is a convenience method, fully equivalent to
* findFilesForLocationURI(location, IResource.NONE).
*
*
* @param location
* a URI path into some file system
* @return the corresponding files in the workspace, or an empty array if
* none
* @since 3.2
*/
IFile[] findFilesForLocationURI(URI location);
/**
* Returns the handles of all files that are mapped to the given URI.
* Returns an empty array if there are none. The URI must be absolute; its
* path segments need not be valid names. The resulting files may not
* currently exist.
*
* If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is specified in the
* member flags, team private members will be included along with the
* others. If the {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} flag is not
* specified (recommended), the result will omit any team private member
* resources.
*
*
* If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags,
* hidden members will be included along with the others. If the
* {@link #INCLUDE_HIDDEN} flag is not specified (recommended), the result
* will omit any hidden member resources.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* @param location
* a URI path into some file system
* @param memberFlags
* bit-wise or of member flag constants (
* {@link #INCLUDE_TEAM_PRIVATE_MEMBERS} and {@link #INCLUDE_HIDDEN})
* indicating which members are of interest
* @return the corresponding files in the workspace, or an empty array if
* none
* @since 3.5
*/
IFile[] findFilesForLocationURI(URI location, int memberFlags);
/**
* Returns a handle to the workspace root, project or folder
* which is mapped to the given path
* in the local file system, or null if none.
* If the path maps to the platform working location, the returned object
* will be of type ROOT. If the path maps to a
* project, the resulting object will be
* of type PROJECT; otherwise the resulting object
* will be a folder (type FOLDER).
* The path should be absolute; a relative path will be treated as
* absolute. The path segments need not be valid names; a trailing separator is ignored.
* The resulting resource may not currently exist.
*
* This method returns null when the given file system location is not equal to
* or under the location of any existing project in the workspace, or equal to the
* location of the platform working location.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* This method prefers a container whose path has a minimal number of segments.
* I.e. a container in a nested project is preferred over a container in an enclosing project.
*
*
* Warning: This method ignores linked resources and their children. Since
* linked resources may overlap other resources, a unique mapping from a
* file system location to a single resource is not guaranteed. To find all
* resources for a given location, including linked resources, use the method
* findContainersForLocation.
*
*
* @param location a path in the local file system
* @return the corresponding project or folder in the workspace,
* or null if none
*/
IContainer getContainerForLocation(IPath location);
/**
* Returns a handle to the file which is mapped to the given path
* in the local file system, or null if none.
* The path should be absolute; a relative path will be treated as
* absolute. The path segments need not be valid names.
* The resulting file may not currently exist.
*
* This method returns null when the given file system location is not under
* the location of any existing project in the workspace.
*
*
* The result will also omit resources that are explicitly excluded
* from the workspace according to existing resource filters.
*
*
* This method prefers a file whose path has a minimal number of segments.
* I.e. a file in a nested project is preferred over a file in an enclosing project.
*
*
* Warning: This method ignores linked resources and their children. Since
* linked resources may overlap other resources, a unique mapping from a
* file system location to a single resource is not guaranteed. To find all
* resources for a given location, including linked resources, use the method
* findFilesForLocation.
*
*
* @param location a path in the local file system
* @return the corresponding file in the workspace,
* or null if none
*/
IFile getFileForLocation(IPath location);
/**
* Returns a handle to the project resource with the given name
* which is a child of this root. The given name must be a valid
* path segment as defined by {@link IPath#isValidSegment(String)}.
*
* Note: This method deals exclusively with resource handles,
* independent of whether the resources exist in the workspace.
* With the exception of validating that the name is a valid path segment,
* validation checking of the project name is not done
* when the project handle is constructed; rather, it is done
* automatically as the project is created.
*
*
* @param name the name of the project
* @return a project resource handle
* @see #getProjects()
*/
IProject getProject(String name);
/**
* Returns the collection of projects which exist under this root.
* The projects can be open or closed.
*
* This is a convenience method, fully equivalent to getProjects(IResource.NONE).
* Hidden projects are not included.
*
* @return an array of projects
* @see #getProject(String)
* @see IResource#isHidden()
*/
IProject[] getProjects();
/**
* Returns the collection of projects which exist under this root.
* The projects can be open or closed.
*
* If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags, hidden
* projects will be included along with the others. If the {@link #INCLUDE_HIDDEN} flag
* is not specified (recommended), the result will omit any hidden projects.
*
*
* @param memberFlags bit-wise or of member flag constants indicating which
* projects are of interest (only {@link #INCLUDE_HIDDEN} is currently applicable)
* @return an array of projects
* @see #getProject(String)
* @see IResource#isHidden()
* @since 3.4
*/
IProject[] getProjects(int memberFlags);
}