org.eclipse.core.resources.IWorkspace Maven / Gradle / Ivy
Show all versions of aspectjtools Show documentation
/*******************************************************************************
* Copyright (c) 2000, 2015 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
* Red Hat Incorporated - loadProjectDescription(InputStream)
* Broadcom Corporation - build configurations and references
*******************************************************************************/
package org.eclipse.core.resources;
import java.io.InputStream;
import java.net.URI;
import java.util.Map;
import org.eclipse.core.resources.team.FileModificationValidationContext;
import org.eclipse.core.runtime.*;
import org.eclipse.core.runtime.jobs.ISchedulingRule;
/**
* Workspaces are the basis for Eclipse Platform resource management. There is
* only one workspace per running platform. All resources exist in the context
* of this workspace.
*
* A workspace corresponds closely to discreet areas in the local file system.
* Each project in a workspace maps onto a specific area of the file system. The
* folders and files within a project map directly onto the corresponding
* directories and files in the file system. One sub-directory, the workspace
* metadata area, contains internal information about the workspace and its
* resources. This metadata area should be accessed only by the Platform or via
* Platform API calls.
*
*
* Workspaces add value over using the file system directly in that they allow
* for comprehensive change tracking (through IResourceDelta s),
* various forms of resource metadata (e.g., markers and properties) as well as
* support for managing application/tool state (e.g., saving and restoring).
*
*
* The workspace as a whole is thread safe and allows one writer concurrent with
* multiple readers. It also supports mechanisms for saving and snapshotting the
* current resource state.
*
*
* The workspace is provided by the Resources plug-in and is automatically
* created when that plug-in is activated. The default workspace data area
* (i.e., where its resources are stored) overlap exactly with the platform's
* data area. That is, by default, the workspace's projects are found directly
* in the platform's data area. Individual project locations can be specified
* explicitly.
*
*
*
* The recommended way of accessing the Workspace is fetching it as a service
* what could be performed in several ways:
*
*
* - For example in a Bundle/Plugin Activator:
*
*
* ServiceTracker<IWorkspace, IWorkspace> workspaceTracker = new ServiceTracker<>(bundleContext, IWorkspace.class,
* null);
* workspaceTracker.open();
* IWorkspace workspace = workspaceTracker.getService();
*
*
*
* - Using declarative service with annotations:
*
*
* @Reference
* private IWorkspace workspace;
*
*
*
* - Helper classes like ServiceCaller:
*
*
* ServiceCaller.callOnce(getClass(), IWorkspace.class, workspace -> {
* // do something with the workspace
* });
*
*
*
*
*
*
* The workspace resource namespace is always case-sensitive and
* case-preserving. Thus the workspace allows multiple sibling resources to
* exist with names that differ only in case. The workspace also imposes no
* restrictions on valid characters in resource names, the length of resource
* names, or the size of resources on disk. In situations where one or more
* resources are stored in a file system that is not case-sensitive, or that
* imposes restrictions on resource names, any failure to store or retrieve
* those resources will be propagated back to the caller of workspace API.
*
*
* Workspaces implement the IAdaptable interface; extensions are
* managed by the platform's adapter manager.
*
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IWorkspace extends IAdaptable {
/**
* flag constant (bit mask value 1) indicating that resource change
* notifications should be avoided during the invocation of a compound
* resource changing operation.
*
* @see IWorkspace#run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)
* @since 3.0
*/
int AVOID_UPDATE = 1;
/**
* Constant that can be passed to {@link #validateEdit(org.eclipse.core.resources.IFile[], Object)}
* to indicate that the caller does not have access to a UI context but would still
* like to have UI-based validation if possible.
* @since 3.3
* @see #validateEdit(IFile[], Object)
*/
Object VALIDATE_PROMPT = FileModificationValidationContext.VALIDATE_PROMPT;
/**
* The name of the IWorkspace OSGi service (value "org.eclipse.core.resources.IWorkspace").
* @since 3.5
*/
String SERVICE_NAME = IWorkspace.class.getName();
/**
* Adds the given listener for resource change events to this workspace. Has
* no effect if an identical listener is already registered.
*
* This method is equivalent to:
*
*
*
* addResourceChangeListener(listener, IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE | IResourceChangeEvent.POST_CHANGE);
*
*
*
* @param listener the listener
* @see IResourceChangeListener
* @see IResourceChangeEvent
* @see #addResourceChangeListener(IResourceChangeListener, int)
* @see #removeResourceChangeListener(IResourceChangeListener)
*/
void addResourceChangeListener(IResourceChangeListener listener);
/**
* Adds the given listener for the specified resource change events to this
* workspace. Has no effect if an identical listener is already registered
* for these events. After completion of this method, the given listener
* will be registered for exactly the specified events. If they were
* previously registered for other events, they will be de-registered.
*
* Once registered, a listener starts receiving notification of changes to
* resources in the workspace. The resource deltas in the resource change
* event are rooted at the workspace root. Most resource change
* notifications occur well after the fact; the exception is
* pre-notification of impending project closures and deletions. The
* listener continues to receive notifications until it is replaced or
* removed.
*
*
* Listeners can listen for several types of event as defined in
* IResourceChangeEvent. Clients are free to register for
* any number of event types however if they register for more than one, it
* is their responsibility to ensure they correctly handle the case where
* the same resource change shows up in multiple notifications. Clients are
* guaranteed to receive only the events for which they are registered.
*
*
* @param listener the listener
* @param eventMask the bit-wise OR of all event types of interest to the
* listener
* @see IResourceChangeListener
* @see IResourceChangeEvent
* @see #removeResourceChangeListener(IResourceChangeListener)
*/
void addResourceChangeListener(IResourceChangeListener listener, int eventMask);
/**
* Registers the given plug-in's workspace save participant, and returns an
* object describing the workspace state at the time of the last save in
* which the plug-in participated.
*
* Once registered, the workspace save participant will actively participate
* in the saving of this workspace.
*
*
* @param plugin the plug-in
* @param participant the participant
* @return the last saved state in which the plug-in participated, or
* null if the plug-in has not participated before
* @exception CoreException if the method fails to add the participant.
* Reasons include:
*
* - The previous state could not be recovered.
*
* @see ISaveParticipant
* @see #removeSaveParticipant(Plugin)
* @deprecated Use {@link #addSaveParticipant(String, ISaveParticipant)} instead
*/
@Deprecated
ISavedState addSaveParticipant(Plugin plugin, ISaveParticipant participant) throws CoreException;
/**
* Registers the given plug-in's workspace save participant, and returns an
* object describing the workspace state at the time of the last save in
* which the bundle participated.
*
* Once registered, the workspace save participant will actively participate
* in the saving of this workspace.
*
*
* @param pluginId the unique identifier of the plug-in
* @param participant the participant
* @return the last saved state in which the plug-in participated, or
* null if the plug-in has not participated before
* @exception CoreException if the method fails to add the participant.
* Reasons include:
*
* - The previous state could not be recovered.
*
* @see ISaveParticipant
* @see #removeSaveParticipant(String)
* @since 3.6
*/
ISavedState addSaveParticipant(String pluginId, ISaveParticipant participant) throws CoreException;
/**
* Builds all projects in this workspace. Projects are built in the order
* specified in this workspace's description. Projects not mentioned in the
* order or for which the order cannot be determined are built in an
* undefined order after all other projects have been built. If no order is
* specified, the workspace computes an order determined by project
* references.
*
* This method may change 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 kind the kind of build being requested. Valid values are
*
* - {@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.
* - {@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.
* - {@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does
* not actually build anything, but rather discards all problems and build states.
*
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @exception CoreException if the build fails.
* The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED}
* code, but it could also be any other status code; it might
* also be a {@link MultiStatus}.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
*
* @see IWorkspace#build(IBuildConfiguration[], int, boolean, IProgressMonitor)
* @see IProject#build(int, IProgressMonitor)
* @see #computeProjectOrder(IProject[])
* @see IncrementalProjectBuilder#FULL_BUILD
* @see IncrementalProjectBuilder#INCREMENTAL_BUILD
* @see IncrementalProjectBuilder#CLEAN_BUILD
* @see IResourceRuleFactory#buildRule()
*/
void build(int kind, IProgressMonitor monitor) throws CoreException;
/**
* Build the build configurations specified in the passed in build configuration array.
*
* Build order is determined by the workspace description and the project build configuration
* reference graph.
*
*
* If buildReferences is true, build configurations reachable through the build configuration graph are
* built as part of this build invocation.
*
*
* This method may change 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 buildConfigs array of configurations to build
* @param kind the kind of build being requested. Valid values are
*
* - {@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.
* - {@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.
* - {@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does
* not actually build anything, but rather discards all problems and build states.
*
* @param buildReferences boolean indicating if references should be transitively built.
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @exception CoreException if the build fails.
* The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED}
* code, but it could also be any other status code; it might
* also be a {@link MultiStatus}.
* @exception OperationCanceledException if the operation is canceled.
* Cancellation can occur even if no progress monitor is provided.
*
* @see IProject#build(int, IProgressMonitor)
* @see IncrementalProjectBuilder#FULL_BUILD
* @see IncrementalProjectBuilder#INCREMENTAL_BUILD
* @see IncrementalProjectBuilder#CLEAN_BUILD
* @see IResourceRuleFactory#buildRule()
* @since 3.7
*/
void build(IBuildConfiguration[] buildConfigs, int kind, boolean buildReferences, IProgressMonitor monitor) throws CoreException;
/**
* Checkpoints the operation currently in progress. This method is used in
* the middle of a group of operations to force a background autobuild (if
* the build argument is true) and send an interim notification of resource
* change events.
*
* When invoked in the dynamic scope of a call to the
* IWorkspace.run method, this method reports a single
* resource change event describing the net effect of all changes done to
* resources since the last round of notifications. When the outermost
* run method eventually completes, it will do another
* autobuild (if enabled) and report the resource changes made after this
* call.
*
*
* This method has no effect if invoked outside the dynamic scope of a call
* to the IWorkspace.run method.
*
*
* This method should be used under controlled circumstance (e.g., to break
* up extremely long-running operations).
*
*
* @param build whether or not to run a build
* @see IWorkspace#run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)
*/
void checkpoint(boolean build);
/**
* Returns the prerequisite ordering of the given projects. The computation
* is done by interpreting the projects' active build configuration references
* as dependency relationships.
* For example if A references B and C, and C references B, this method,
* given the list A, B, C will return the order B, C, A. That is, projects
* with no dependencies are listed first.
*
* The return value is a two element array of project arrays. The first
* project array is the list of projects which could be sorted (as outlined
* above). The second element of the return value is an array of the
* projects which are ambiguously ordered (e.g., they are part of a cycle).
*
*
* Cycles and ambiguities are handled by elimination. Projects involved in
* cycles are simply cut out of the ordered list and returned in an
* undefined order. Closed and non-existent projects are ignored and do not
* appear in the returned value at all.
*
*
* @param projects the projects to order
* @return the projects in sorted order and a list of projects which could
* not be ordered
* @deprecated Replaced by IWorkspace.computeProjectOrder,
* which produces a more usable result when there are cycles in project
* reference graph.
*/
@Deprecated
IProject[][] computePrerequisiteOrder(IProject[] projects);
/**
* Data structure for holding the multi-part outcome of
* IWorkspace.computeProjectOrder.
*
* This class is not intended to be instantiated by clients.
*
*
* @see IWorkspace#computeProjectOrder(IProject[])
* @since 2.1
*/
public static final class ProjectOrder {
/**
* Creates an instance with the given values.
*
* This class is not intended to be instantiated by clients.
*
*
* @param projects initial value of projects field
* @param hasCycles initial value of hasCycles field
* @param knots initial value of knots field
*/
public ProjectOrder(IProject[] projects, boolean hasCycles, IProject[][] knots) {
this.projects = projects;
this.hasCycles = hasCycles;
this.knots = knots;
}
/**
* A list of projects ordered so as to honor the project reference, and
* build configuration reference, relationships between these projects
* wherever possible.
* The elements are a subset of the ones passed as the projects
* parameter to IWorkspace.computeProjectOrder, where
* inaccessible (closed or non-existent) projects have been omitted.
*/
public IProject[] projects;
/**
* Indicates whether any of the accessible projects in
* projects are involved in non-trivial cycles.
* true if the reference graph contains at least
* one cycle involving two or more of the projects in
* projects, and false if none of the
* projects in projects are involved in cycles.
*/
public boolean hasCycles;
/**
* A list of knots in the project reference graph. This list is empty if
* the project reference graph does not contain cycles. If the project
* reference graph contains cycles, each element is a knot of two or
* more accessible projects from projects that are
* involved in a cycle of mutually dependent references.
*/
public IProject[][] knots;
}
/**
* Computes a total ordering of the given projects based on both static and
* dynamic project references. If an existing and open project P references
* another existing and open project Q also included in the list, then Q
* should come before P in the resulting ordering. Closed and non-existent
* projects are ignored, and will not appear in the result. References to
* non-existent or closed projects are also ignored, as are any
* self-references. The total ordering is always consistent with the global
* total ordering of all open projects in the workspace.
*
* When there are choices, the choice is made in a reasonably stable way.
* For example, given an arbitrary choice between two projects, the one with
* the lower collating project name is usually selected.
*
*
* When the project reference graph contains cyclic references, it is
* impossible to honor all of the relationships. In this case, the result
* ignores as few relationships as possible. For example, if P2 references
* P1, P4 references P3, and P2 and P3 reference each other, then exactly
* one of the relationships between P2 and P3 will have to be ignored. The
* outcome will be either [P1, P2, P3, P4] or [P1, P3, P2, P4]. The result
* also contains complete details of any cycles present.
*
*
* This method is time-consuming and should not be called unnecessarily.
* There are a very limited set of changes to a workspace that could affect
* the outcome: creating, renaming, or deleting a project; opening or
* closing a project; adding or removing a project reference.
*
*
* @param projects the projects to order
* @return result describing the project order
* @since 2.1
*/
ProjectOrder computeProjectOrder(IProject[] projects);
/**
* Copies the given sibling resources so that they are located as members of
* the resource at the given path; the names of the copies are the same as
* the corresponding originals.
*
* This is a convenience method, fully equivalent to:
*
*
*
* copy(resources, destination, (force ? IResource.FORCE : IResource.NONE), monitor);
*
*
*
* This method changes resources; these changes will be reported in a
* subsequent resource change event that will include an indication that the
* resources have been added to the new parent.
*
*
* This method is long-running; progress and cancellation are provided by
* the given progress monitor.
*
*
* @param resources the resources to copy
* @param destination the destination container 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 null if progress
* reporting is not desired
* @return a status object with code OK if there were no
* problems; otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages
* @exception CoreException if the method fails to copy some resources. The
* status contained in the exception may be a multi-status indicating where
* the individual failures occurred.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see #copy(IResource[],IPath,int,IProgressMonitor)
*/
IStatus copy(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Copies the given sibling resources so that they are located as members of
* the resource at the given path; the names of the copies are the same as
* the corresponding originals.
*
* This method can be expressed as a series of calls to
* IResource.copy(IPath,int,IProgressMonitor), with "best
* effort" semantics:
*
*
* - Resources are copied in the order specified, using the given update
* flags.
* - Duplicate resources are only copied once.
* - The method fails if the resources are not all siblings.
* - The failure of an individual copy does not necessarily prevent the
* method from attempting to copy other resources.
* - The method fails if there are projects among the resources.
* - The method fails if the path of the resources is a prefix of the
* destination path.
* - This method also fails if one or more of the individual resource
* copy steps fails.
*
*
* After successful completion, corresponding new resources will now exist
* as members of the resource at the given path.
*
*
* 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
* resources being copied. A trailing separator is ignored.
*
*
* This method changes resources; these changes will be reported in a
* subsequent resource change event that will include an indication that the
* resources have been added to the new parent.
*
*
* This method is long-running; progress and cancellation are provided by
* the given progress monitor.
*
*
* @param resources the resources to copy
* @param destination the destination container path
* @param updateFlags bit-wise or of update flag constants
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @return a status object with code OK if there were no
* problems; otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages
* @exception CoreException if the method fails to copy some resources. The
* status contained in the exception may be a multi-status indicating where
* the individual failures occurred. Reasons include:
*
* - One of the resources does not exist.
* - The resources are not siblings.
* - One of the resources, or one of its descendents, is not local.
* - The resource corresponding to the destination path does not exist.
*
* - The resource corresponding to the parent destination path is a
* closed project.
* - A corresponding target resource does exist.
* - A resource of a different type exists at the target path.
* - One of the resources is a project.
* - The path of one of the resources is a prefix of the destination
* path.
* - One of the resources, 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.
*
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see IResource#copy(IPath,int,IProgressMonitor)
* @see IResourceRuleFactory#copyRule(IResource, IResource)
* @since 2.0
*/
IStatus copy(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;
/**
* Deletes the given resources.
*
* This is a convenience method, fully equivalent to:
*
*
*
* delete(resources, IResource.KEEP_HISTORY | (force ? IResource.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 resources the resources to delete
* @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
* @return status with code OK if there were no problems;
* otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages
* @exception CoreException if the method fails to delete some resource. The
* status contained in the exception is a multi-status indicating where the
* individual failures occurred.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see #delete(IResource[],int,IProgressMonitor)
*/
IStatus delete(IResource[] resources, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Deletes the given resources.
*
* This method can be expressed as a series of calls to
* IResource.delete(int,IProgressMonitor).
*
*
* The semantics of multiple deletion are:
*
*
* - Resources are deleted in the order presented, using the given update
* flags.
* - Resources that do not exist are ignored.
* - An individual deletion fails if the resource still exists
* afterwards.
* - The failure of an individual deletion does not prevent the method
* from attempting to delete other resources.
* - This method fails if one or more of the individual resource
* deletions fails; that is, if at least one of the resources in the list
* still exists at the end of this method.
*
*
* 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 resources the resources to delete
* @param updateFlags bit-wise or of update flag constants
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @return status with code OK if there were no problems;
* otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages
* @exception CoreException if the method fails to delete some resource. The
* status contained in the exception is a multi-status indicating where the
* individual failures occurred.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see IResource#delete(int,IProgressMonitor)
* @see IResourceRuleFactory#deleteRule(IResource)
* @since 2.0
*/
IStatus delete(IResource[] resources, int updateFlags, IProgressMonitor monitor) throws CoreException;
/**
* Removes the given markers from the resources with which they are
* associated. Markers that do not exist are ignored.
*
* This method changes resources; these changes will be reported in a
* subsequent resource change event.
*
*
* @param markers the markers to remove
* @exception CoreException if this method fails. Reasons include:
*
* - Resource changes are disallowed during certain types of resource
* change event notification. See
IResourceChangeEvent for
* more details.
*
* @see IResourceRuleFactory#markerRule(IResource)
*/
void deleteMarkers(IMarker[] markers) throws CoreException;
/**
* Forgets any resource tree being saved for the plug-in with the given
* name. If the plug-in id is null, all trees are forgotten.
*
* Clients should not call this method unless they have a reason to do so. A
* plug-in which uses ISaveContext.needDelta in the process
* of a save indicates that it would like to be fed the resource delta the
* next time it is reactivated. If a plug-in never gets reactivated (or if
* it fails to successfully register to participate in workspace saves), the
* workspace nevertheless retains the necessary information to generate the
* resource delta if asked. This method allows such a long term leak to be
* plugged.
*
*
* @param pluginId the unique identifier of the plug-in, or null
* @see ISaveContext#needDelta()
*/
void forgetSavedTree(String pluginId);
/**
* Returns all filter matcher descriptors known to this workspace. Returns an empty
* array if there are no installed filter matchers.
*
* @return the filter matcher descriptors known to this workspace
* @since 3.6
*/
IFilterMatcherDescriptor[] getFilterMatcherDescriptors();
/**
* Returns the filter descriptor with the given unique identifier, or
* null if there is no such filter.
*
* @param filterMatcherId the filter matcher extension identifier (e.g.
* "com.example.coolFilter").
* @return the filter matcher descriptor, or null
* @since 3.6
*/
IFilterMatcherDescriptor getFilterMatcherDescriptor(String filterMatcherId);
/**
* Returns all nature descriptors known to this workspace. Returns an empty
* array if there are no installed natures.
*
* @return the nature descriptors known to this workspace
* @since 2.0
*/
IProjectNatureDescriptor[] getNatureDescriptors();
/**
* Returns the nature descriptor with the given unique identifier, or
* null if there is no such nature.
*
* @param natureId the nature extension identifier (e.g.
* "com.example.coolNature").
* @return the nature descriptor, or null
* @since 2.0
*/
IProjectNatureDescriptor getNatureDescriptor(String natureId);
/**
* Finds all dangling project references in this workspace. Projects which
* are not open are ignored. Returns a map with one entry for each open
* project in the workspace that has at least one dangling project
* reference; the value of the entry is an array of projects which are
* referenced by that project but do not exist in the workspace. Returns an
* empty Map if there are no projects in the workspace.
*
* @return a map (key type: IProject, value type:
* IProject[]) from project to dangling project references
*/
Map getDanglingReferences();
/**
* Returns the workspace description. This object is responsible for
* defining workspace preferences. The returned value is a modifiable copy
* but changes are not automatically applied to the workspace. In order to
* changes take effect, IWorkspace.setDescription needs to be
* called. The workspace description values are store in the preference
* store.
*
* @return the workspace description
* @see #setDescription(IWorkspaceDescription)
*/
IWorkspaceDescription getDescription();
/**
* Returns the root resource of this workspace.
*
* @return the workspace root
*/
IWorkspaceRoot getRoot();
/**
* Returns a factory for obtaining scheduling rules prior to modifying
* resources in the workspace.
*
* @see IResourceRuleFactory
* @return a resource rule factory
* @since 3.0
*/
IResourceRuleFactory getRuleFactory();
/**
* Returns the synchronizer for this workspace.
*
* @return the synchronizer
* @see ISynchronizer
*/
ISynchronizer getSynchronizer();
/**
* Returns whether this workspace performs autobuilds.
*
* @return true if autobuilding is on, false
* otherwise
*/
boolean isAutoBuilding();
/**
* Returns whether the workspace tree is currently locked. Resource changes
* are disallowed during certain types of resource change event
* notification. See IResourceChangeEvent for more details.
*
* @return boolean true if the workspace tree is locked,
* false otherwise
* @see IResourceChangeEvent
* @since 2.1
*/
boolean isTreeLocked();
/**
* Reads the project description file (".project") from the given location
* in the local file system. This object is useful for discovering the
* correct name for a project before importing it into the workspace.
*
* The returned value is writeable.
*
*
* @param projectDescriptionFile the path in the local file system of an
* existing project description file
* @return a new project description
* @exception CoreException if the operation failed. Reasons include:
*
* - The project description file does not exist.
* - The file cannot be opened or read.
* - The file cannot be parsed as a legal project description.
*
* @see #newProjectDescription(String)
* @see IProject#getDescription()
* @since 2.0
*/
IProjectDescription loadProjectDescription(IPath projectDescriptionFile) throws CoreException;
/**
* Reads the project description file (".project") from the given InputStream.
* This object will not attempt to set the location since the project may not
* have a valid location on the local file system.
* This object is useful for discovering the correct name for a project before
* importing it into the workspace.
*
* The returned value is writeable.
*
*
* @param projectDescriptionFile an InputStream pointing to an existing project
* description file
* @return a new project description
* @exception CoreException if the operation failed. Reasons include:
*
* - The stream could not be read.
* - The stream does not contain a legal project description.
*
* @see #newProjectDescription(String)
* @see IProject#getDescription()
* @see IWorkspace#loadProjectDescription(IPath)
* @since 3.1
*/
IProjectDescription loadProjectDescription(InputStream projectDescriptionFile) throws CoreException;
/**
* Moves the given sibling resources so that they are located as members of
* the resource at the given path; the names of the new members are the
* same.
*
* This is a convenience method, fully equivalent to:
*
*
*
* move(resources, destination, IResource.KEEP_HISTORY | (force ? IResource.FORCE : IResource.NONE), monitor);
*
*
*
* This method changes resources; these changes will be reported in a
* subsequent resource change event that will include an indication that the
* resources have been removed from their parent and that corresponding
* resources have been added to the new parent. Additional information
* provided with resource delta shows that these additions and removals are
* pairwise related.
*
*
* This method is long-running; progress and cancellation are provided by
* the given progress monitor.
*
*
* @param resources the resources to move
* @param destination the destination container 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 null if progress
* reporting is not desired
* @return status with code OK if there were no problems;
* otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages.
* @exception CoreException if the method fails to move some resources. The
* status contained in the exception may be a multi-status indicating where
* the individual failures occurred.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see #move(IResource[],IPath,int,IProgressMonitor)
*/
IStatus move(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException;
/**
* Moves the given sibling resources so that they are located as members of
* the resource at the given path; the names of the new members are the
* same.
*
* This method can be expressed as a series of calls to
* IResource.move, with "best effort" semantics:
*
*
* - Resources are moved in the order specified.
* - Duplicate resources are only moved once.
* - The
force flag has the same meaning as it does on the
* corresponding single-resource method.
* - The method fails if the resources are not all siblings.
* - The method fails the path of any of the resources is a prefix of the
* destination path.
* - The failure of an individual move does not necessarily prevent the
* method from attempting to move other resources.
* - This method also fails if one or more of the individual resource
* moves fails; that is, if at least one of the resources in the list still
* exists at the end of this method.
* - History is kept for moved files. When projects are moved, no history
* is kept
*
*
* After successful completion, the resources and descendents will no longer
* exist; but corresponding new resources will now exist as members of the
* resource at the given path.
*
*
* 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
* resources being moved. A trailing separator is ignored.
*
*
* This method changes resources; these changes will be reported in a
* subsequent resource change event that will include an indication that the
* resources have been removed from their parent and that corresponding
* resources have been added to the new parent. Additional information
* provided with resource delta shows that these additions and removals are
* pairwise related.
*
*
* This method is long-running; progress and cancellation are provided by
* the given progress monitor.
*
*
* @param resources the resources to move
* @param destination the destination container path
* @param updateFlags bit-wise or of update flag constants
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @return status with code OK if there were no problems;
* otherwise a description (possibly a multi-status) consisting of
* low-severity warnings or informational messages.
* @exception CoreException if the method fails to move some resources. The
* status contained in the exception may be a multi-status indicating where
* the individual failures occurred. Reasons include:
*
* - One of the resources does not exist.
* - The resources are not siblings.
* - One of the resources, or one of its descendents, is not local.
* - The resource corresponding to the destination path does not exist.
*
* - The resource corresponding to the parent destination path is a
* closed project.
* - A corresponding target resource does exist.
* - A resource of a different type exists at the target path.
* - The path of one of the resources is a prefix of the destination
* path.
* - One of the resources, 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.
*
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see IResource#move(IPath,int,IProgressMonitor)
* @see IResourceRuleFactory#moveRule(IResource, IResource)
* @since 2.0
*/
IStatus move(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException;
/**
* Returns a new build configuration for the project, with the given name.
* The name is a human readable unique name for the build configuration in the
* project. The project need not exist.
*
* This API can be used to create {@link IBuildConfiguration}s that will be used as references
* to {@link IBuildConfiguration}s in other projects. These references are set using
* {@link IProjectDescription#setBuildConfigReferences(String, IBuildConfiguration[])}
* and may have a null configuration name which will resolve to the referenced
* project's active configuration when the reference is used.
*
*
* Build configuration do not become part of a project
* description until set using {@link IProjectDescription#setBuildConfigs(String[])}.
*
*
* @param projectName the name of the project on which the configuration will exist
* @param configName the name of the new build configuration
* @return a build configuration
* @see IProjectDescription#setBuildConfigs(String[])
* @see IProjectDescription#setBuildConfigReferences(String, IBuildConfiguration[])
* @see IBuildConfiguration
* @since 3.7
*/
IBuildConfiguration newBuildConfig(String projectName, String configName);
/**
* Creates and returns a new project description for a project with the
* given name. This object is useful when creating, moving or copying
* projects.
*
* The project description is initialized to:
*
*
* - the given project name
* - no references to other projects
* - an empty build spec
* - an empty comment
*
*
* The returned value is writeable.
*
*
* @param projectName the name of the project
* @return a new project description
* @see IProject#getDescription()
* @see IProject#create(IProjectDescription, IProgressMonitor)
* @see IResource#copy(IProjectDescription, int, IProgressMonitor)
* @see IProject#move(IProjectDescription, boolean, IProgressMonitor)
*/
IProjectDescription newProjectDescription(String projectName);
/**
* Removes the given resource change listener from this workspace. Has no
* effect if an identical listener is not registered.
*
* @param listener the listener
* @see IResourceChangeListener
* @see #addResourceChangeListener(IResourceChangeListener)
*/
void removeResourceChangeListener(IResourceChangeListener listener);
/**
* Removes the workspace save participant for the given plug-in from this
* workspace. If no such participant is registered, no action is taken.
*
* Once removed, the workspace save participant no longer actively
* participates in any future saves of this workspace.
*
*
* @param plugin the plug-in
* @see ISaveParticipant
* @see #addSaveParticipant(Plugin, ISaveParticipant)
* @deprecated Use {@link #removeSaveParticipant(String)} instead
*/
@Deprecated
void removeSaveParticipant(Plugin plugin);
/**
* Removes the workspace save participant for the given plug-in from this
* workspace. If no such participant is registered, no action is taken.
*
* Once removed, the workspace save participant no longer actively
* participates in any future saves of this workspace.
*
*
* @param pluginId the unique identifier of the plug-in
* @see ISaveParticipant
* @see #addSaveParticipant(String, ISaveParticipant)
* @since 3.6
*/
void removeSaveParticipant(String pluginId);
/**
* Runs the given action as an atomic workspace operation.
*
* After running a method that modifies resources in the workspace,
* registered listeners receive after-the-fact notification of what just
* transpired, in the form of a resource change event. This method allows
* clients to call a number of methods that modify resources and only have
* resource change event notifications reported at the end of the entire
* batch.
*
*
* If this method is called outside the dynamic scope of another such call,
* this method runs the action and then reports a single resource change
* event describing the net effect of all changes done to resources by the
* action.
*
*
* If this method is called in the dynamic scope of another such call, this
* method simply runs the action.
*
*
* The supplied scheduling rule is used to determine whether this operation
* can be run simultaneously with workspace changes in other threads. If the
* scheduling rule conflicts with another workspace change that is currently
* running, the calling thread will be blocked until that change completes.
* If the action attempts to make changes to the workspace that were not
* specified in the scheduling rule, it will fail. If no scheduling rule is
* supplied, there are no scheduling restrictions for this operation.
* If a non-null scheduling rule is supplied, this operation
* must always support cancelation in the case where this operation becomes
* blocked by a long running background operation.
*
*
* The AVOID_UPDATE flag controls whether periodic resource change
* notifications should occur during the scope of this call. If this flag is
* specified, and no other threads modify the workspace concurrently, then
* all resource change notifications will be deferred until the end of this
* call. If this flag is not specified, the platform may decide to broadcast
* periodic resource change notifications during the scope of this call.
*
*
* Flags other than AVOID_UPDATE are ignored.
*
*
* @param action the action to perform
* @param rule the scheduling rule to use when running this operation, or
* null if there are no scheduling restrictions for this
* operation.
* @param flags bit-wise or of flag constants (only AVOID_UPDATE is relevant
* here)
* @param monitor a progress monitor, or null if progress
* reporting is not desired.
* @exception CoreException if the operation failed.
* @exception OperationCanceledException if the operation is canceled. If a
* non-null scheduling rule is supplied, cancelation can occur
* even if no progress monitor is provided.
*
* @see #AVOID_UPDATE
* @see IResourceRuleFactory
* @since 3.11
*/
void run(ICoreRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException;
/**
* Runs the given action as an atomic workspace operation.
*
* This is a convenience method, fully equivalent to:
*
*
*
* workspace.run(action, workspace.getRoot(), IWorkspace.AVOID_UPDATE, monitor);
*
*
*
* @param action the action to perform
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @exception CoreException if the operation failed.
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
*
* @see #run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)
* @since 3.11
*/
void run(ICoreRunnable action, IProgressMonitor monitor) throws CoreException;
/**
* Identical to {@link #run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)}.
* New code should use that method.
*
* @param action the action to perform
* @param rule the scheduling rule to use when running this operation, or
* null if there are no scheduling restrictions for this
* operation.
* @param flags bit-wise or of flag constants (only AVOID_UPDATE is relevant
* here)
* @param monitor a progress monitor, or null if progress
* reporting is not desired.
* @exception CoreException if the operation failed.
* @since 3.0
*/
void run(IWorkspaceRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException;
/**
* Identical to {@link #run(ICoreRunnable, IProgressMonitor)}.
* New code should use that method.
*
* @param action the action to perform
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @exception CoreException if the operation failed.
*/
void run(IWorkspaceRunnable action, IProgressMonitor monitor) throws CoreException;
/**
* Saves this workspace's valuable state on disk. Consults with all
* registered plug-ins so that they can coordinate the saving of their
* persistent state as well.
*
* The full parameter indicates whether a full save or a
* snapshot is being requested. Snapshots save the workspace information
* that is considered hard to be recomputed in the unlikely event of a
* crash. It includes parts of the workspace tree, workspace and projects
* descriptions, markers and sync information. Full saves are heavy weight
* operations which save the complete workspace state.
*
*
* To ensure that all outstanding changes to the workspace have been
* reported to interested parties prior to saving, a full save cannot be
* used within the dynamic scope of an IWorkspace.run
* invocation. Snapshots can be called any time and are interpreted by the
* workspace as a hint that a snapshot is required. The workspace will
* perform the snapshot when possible. Even as a hint, snapshots should only
* be called when necessary as they impact system performance. Although
* saving does not change the workspace per se, its execution is serialized
* like methods that write the workspace.
*
*
* The workspace is comprised of several different kinds of data with
* varying degrees of importance. The most important data, the resources
* themselves and their persistent properties, are written to disk
* immediately; other data are kept in volatile memory and only written to
* disk periodically; and other data are maintained in memory and never
* written out. The following table summarizes what gets saved when:
*
* - creating or deleting resource - immediately
* - setting contents of file - immediately
* - changes to project description - immediately
* - session properties - never
* - changes to persistent properties - immediately
* - markers -
save
* - synchronizer info -
save
* - shape of the workspace resource tree -
save
* - list of active plug-ins - never
*
*
* Resource-based plug-in also have data with varying degrees of importance.
* Each plug-in gets to decide the policy for protecting its data, either
* immediately, never, or at save time. For the latter, the
* plug-in coordinates its actions with the workspace (see
* ISaveParticipant for details).
*
*
* If the platform is shutdown (or crashes) after saving the workspace, any
* information written to disk by the last successful workspace
* save will be restored the next time the workspace is
* reopened for the next session. Naturally, information that is written to
* disk immediately will be as of the last time it was changed.
*
*
* The workspace provides a general mechanism for keeping concerned parties
* apprised of any and all changes to resources in the workspace (
* IResourceChangeListener). It is even possible for a
* plug-in to find out about changes to resources that happen between
* workspace sessions (see IWorkspace.addSaveParticipant).
*
*
* At certain points during this method, the entire workspace resource tree
* must be locked to prevent resources from being changed (read access to
* resources is permitted).
*
*
* Implementation note: The execution sequence is as follows.
*
* - A long-term lock on the workspace is taken out to prevent further
* changes to workspace until the save is done.
* - The list of saveable resource tree snapshots is initially empty.
*
* - A different
ISaveContext object is created for each
* registered workspace save participant plug-in, reflecting the kind of
* save (ISaveContext.getKind), the previous save number in
* which this plug-in actively participated, and the new save number (=
* previous save number plus 1).
* - Each registered workspace save participant is sent
*
prepareToSave(context), passing in its own context
* object.
*
* - Plug-in suspends all activities until further notice.
*
* If prepareToSave fails (throws an exception), the problem
* is logged and the participant is marked as unstable.
* - In dependent-before-prerequisite order, each registered workspace
* save participant is sent
saving(context), passing in its
* own context object.
*
* - Plug-in decides whether it wants to actively participate in this
* save. The plug-in only needs to actively participate if some of its
* important state has changed since the last time it actively participated.
* If it does decide to actively participate, it writes its important state
* to a brand new file in its plug-in state area under a generated file name
* based on
context.getStateNumber() and calls
* context.needStateNumber() to indicate that it has actively
* participated. If upon reactivation the plug-in will want a resource delta
* covering all changes between now and then, the plug-in should invoke
* context.needDelta() to request this now; otherwise, a
* resource delta for the intervening period will not be available on
* reactivation.
*
* If saving fails (throws an exception), the problem is
* logged and the participant is marked as unstable.
* - The plug-in save table contains an entry for each plug-in that has
* registered to participate in workspace saves at some time in the past
* (the list of plug-ins increases monotonically). Each entry records the
* save number of the last successful save in which that plug-in actively
* participated, and, optionally, a saved resource tree (conceptually, this
* is a complete tree; in practice, it is compressed into a special delta
* tree representation). A copy of the plug-in save table is made. Entries
* are created or modified for each registered plug-in to record the
* appropriate save number (either the previous save number, or the previous
* save number plus 1, depending on whether the participant was active and
* asked for a new number).
* - The workspace tree, the modified copy of the plug-in save table, all
* markers, etc. and all saveable resource tree snapshots are written to
* disk as one atomic operation .
* - The long-term lock on the workspace is released.
* - If the atomic save succeeded:
*
* - The modified copy of the plug-in save table becomes the new plug-in
* save table.
* - In prerequisite-before-dependent order, each registered workspace
* save participant is sent
doneSaving(context), passing in
* its own context object.
*
* - Plug-in may perform clean up by deleting obsolete state files in its
* plug-in state area.
* - Plug-in resumes its normal activities.
*
* If doneSaving fails (throws an exception), the problem is
* logged and the participant is marked as unstable. (The state number in
* the save table is not rolled back just because of this instability.)
*
* - The workspace save operation returns.
*
* - If it failed:
*
* - The workspace previous state is restored.
* - In prerequisite-before-dependent order, each registered workspace
* save participant is sent
rollback(context), passing in
* its own context object.
*
*
* - Plug-in may perform clean up by deleting newly-created but obsolete
* state file in its plug-in state area.
* - Plug-in resumes its normal activities.
*
-
* If
rollback fails (throws an exception), the problem is
* logged and the participant is marked as unstable. (The state number in
* the save table is rolled back anyway.)
* - The workspace save operation fails.
*
*
*
* After a full save, the platform can be shutdown. This will cause the
* Resources plug-in and all the other plug-ins to shutdown, without
* disturbing the saved workspace on disk.
*
*
* When the platform is later restarted, activating the Resources plug-in
* opens the saved workspace. This reads into memory the workspace's
* resource tree, plug-in save table, and saved resource tree snapshots
* (everything that was written to disk in the atomic operation above).
* Later, when a plug-in gets reactivated and registers to participate in
* workspace saves, it is handed back the info from its entry in the plug-in
* save table, if it has one. It gets back the number of the last save in
* which it actively participated and, possibly, a resource delta.
*
*
* The only source of long term garbage would come from a plug-in that never
* gets reactivated, or one that gets reactivated but fails to register for
* workspace saves. (There is no such problem with a plug-in that gets
* uninstalled; its easy enough to scrub its state areas and delete its
* entry in the plug-in save table.)
*
*
* @param full true if this is a full save, and
* false if this is only a snapshot for protecting against
* crashes
* @param monitor a progress monitor, or null if progress
* reporting is not desired
* @return a status that may contain warnings, such as the failure of an
* individual participant
* @exception CoreException if this method fails to save the state of this
* workspace. Reasons include:
*
* - The operation cannot be batched with others.
*
* @exception OperationCanceledException if the operation is canceled.
* Cancelation can occur even if no progress monitor is provided.
* @see #addSaveParticipant(Plugin, ISaveParticipant)
*/
IStatus save(boolean full, IProgressMonitor monitor) throws CoreException;
/**
* Sets the workspace description. Its values are stored in the preference
* store.
*
* @param description the new workspace description.
* @see #getDescription()
* @exception CoreException if the method fails. Reasons include:
*
* - There was a problem setting the workspace description.
*
*/
void setDescription(IWorkspaceDescription description) throws CoreException;
/**
* Returns a copy of the given set of natures sorted in prerequisite order.
* For each nature, it is guaranteed that all of its prerequisites will
* precede it in the resulting array.
*
*
* Natures that are missing from the install or are involved in a
* prerequisite cycle are sorted arbitrarily. Duplicate nature IDs are
* removed, so the returned array may be smaller than the original.
*
*
* @param natureIds a valid set of nature extension identifiers
* @return the set of nature Ids sorted in prerequisite order
* @see #validateNatureSet(String[])
* @since 2.0
*/
String[] sortNatureSet(String[] natureIds);
/**
* Advises that the caller intends to modify the contents of the given files
* in the near future and asks whether modifying all these files would be
* reasonable. The files must all exist. This method is used to give the VCM
* component an opportunity to check out (or otherwise prepare) the files if
* required. (It is provided in this component rather than in the UI so that
* "core" (i.e., head-less) clients can use it. Similarly, it is located
* outside the VCM component for the convenience of clients that must also
* operate in configurations without VCM.)
*
* A client (such as an editor) should perform a validateEdit
* on a file whenever it finds itself in the following position: (a) the
* file is marked read-only, and (b) the client believes it likely (not
* necessarily certain) that it will modify the file's contents at some
* point. A case in point is an editor that has a buffer opened on a file.
* When the user starts to dirty the buffer, the editor should check to see
* whether the file is read-only. If it is, it should call
* validateEdit, and can reasonably expect this call, when
* successful, to cause the file to become read-write. An editor should also
* be sensitive to a file becoming read-only again even after a successful
* validateEdit (e.g., due to the user checking in the file
* in a different view); the editor should again call
* validateEdit if the file is read-only before attempting to
* save the contents of the file.
*
*
* By passing a UI context, the caller indicates that the VCM component may
* contact the user to help decide how best to proceed. If no UI context is
* provided, the VCM component will make its decision without additional
* interaction with the user. If OK is returned, the caller can safely
* assume that all of the given files haven been prepared for modification
* and that there is good reason to believe that
* IFile.setContents (or appendContents)
* would be successful on any of them. If the result is not OK, modifying
* the given files might not succeed for the reason(s) indicated.
*
*
* If a shell is passed in as the context, the VCM component may bring up a
* dialogs to query the user or report difficulties; the shell should be
* used to parent any such dialogs; the caller may safely assume that the
* reasons for failure will have been made clear to the user. If
* {@link IWorkspace#VALIDATE_PROMPT} is passed
* as the context, this indicates that the caller does not have access to
* a UI context but would still like the user to be prompted if required.
* If null is passed, the user should not be contacted; any
* failures should be reported via the result; the caller may chose to
* present these to the user however they see fit. The ideal implementation
* of this method is transactional; no files would be affected unless the
* go-ahead could be given. (In practice, there may be no feasible way to
* ensure such changes get done atomically.)
*
*
* The method calls FileModificationValidator.validateEdit
* for the file modification validator (if provided by the VCM plug-in).
* When there is no file modification validator, this method returns a
* status with an IResourceStatus.READ_ONLY_LOCAL code if one
* of the files is read-only, and a status with an IStatus.OK
* code otherwise.
*
*
* This method may be called from any thread. If the UI context is used, it
* is the responsibility of the implementor of
* FileModificationValidator.validateEdit to interact with
* the UI context in an appropriate thread.
*
*
* @param files the files that are to be modified; these files must all
* exist in the workspace
* @param context either {@link IWorkspace#VALIDATE_PROMPT},
* or the org.eclipse.swt.widgets.Shell that is
* to be used to parent any dialogs with the user, or null if
* there is no UI context (declared as an Object to avoid any
* direct references on the SWT component)
* @return a status object that is OK if things are fine,
* otherwise a status describing reasons why modifying the given files is not
* reasonable. A status with a severity of CANCEL is returned
* if the validation was canceled, indicating the edit should not proceed.
* @see IResourceRuleFactory#validateEditRule(IResource[])
* @since 2.0
*/
IStatus validateEdit(IFile[] files, Object context);
/**
* Validates that the given resource will not (or would not, if the resource
* doesn't exist in the workspace yet) be filtered out from the workspace by
* its parent resource filters.
*
* Note that if the resource or its parent doesn't exist yet in the workspace,
* it is possible that it will still be effectively filtered out once the resource
* and/or its parent is created, even though this method doesn't report it.
*
* But if this method reports the resource as filtered, even though it, or its
* parent, doesn't exist in the workspace yet, it means that the resource will
* be filtered out by its parent resource filters once it exists in the workspace.
*
*
* This method will return a status with severity IStatus.ERROR
* if the resource will be filtered out - removed - out of the workspace by
* its parent resource filters.
*
*
* Note: linked resources and virtual folders are never filtered out by their
* parent resource filters.
*
* @param resource the resource to validate the location for
* @return a status object with code IStatus.OK if the given
* resource is not filtered by its parent resource filters, otherwise a status
* object with severity IStatus.ERROR indicating that it will
* @see IStatus#OK
* @since 3.6
*/
IStatus validateFiltered(IResource resource);
/**
* Validates the given path as the location of the given resource on disk.
* The path must be either an absolute file system path, or a relative path
* whose first segment is the name of a defined workspace path variable. In
* addition to the restrictions for paths in general (see IPath.
* isValidPath),
* a link location must also obey the following rules:
*
* - must not overlap with the platform's metadata directory
* - must not be the same as or a parent of the root directory of the
* project the linked resource is contained in
*
*
* This method also checks that the given resource can legally become a
* linked resource. This includes the following restrictions:
*
* - must have a project as its immediate parent
* - project natures and the team hook may disallow linked resources on
* projects they are associated with
* - the global workspace preference to disable linking,
*
ResourcesPlugin.PREF_DISABLE_LINKING must not be set to
* "true"
*
*
* This method will return a status with severity IStatus.ERROR
* if the location does not obey the above rules. Also, this method will
* return a status with severity IStatus.WARNING if the
* location overlaps the location of any existing resource in the workspace.
*
*
* Note: this method does not consider whether files or directories exist in
* the file system at the specified path.
*
* @param resource the resource to validate the location for
* @param location the location of the linked resource contents on disk
* @return a status object with code IStatus.OK if the given
* location is valid as the linked resource location, otherwise a status
* object with severity IStatus.WARNING or
* IStatus.ERROR indicating what is wrong with the location
* @see IStatus#OK
* @see ResourcesPlugin#PREF_DISABLE_LINKING
* @since 2.1
*/
IStatus validateLinkLocation(IResource resource, IPath location);
/**
* Validates the given {@link URI} as the location of the given resource on disk.
* The location must be either an absolute URI, or a relative URI
* whose first segment is the name of a defined workspace path variable.
* A link location must obey the following rules:
*
* - must not overlap with the platform's metadata directory
* - must not be the same as or a parent of the root directory of the
* project the linked resource is contained in
*
*
* This method also checks that the given resource can legally become a
* linked resource. This includes the following restrictions:
*
* - must have a project as its immediate parent
* - project natures and the team hook may disallow linked resources on
* projects they are associated with
* - the global workspace preference to disable linking,
*
ResourcesPlugin.PREF_DISABLE_LINKING must not be set to
* "true"
*
*
* This method will return a status with severity IStatus.ERROR
* if the location does not obey the above rules. Also, this method will
* return a status with severity IStatus.WARNING if the
* location overlaps the location of any existing resource in the workspace.
*
*
* Note: this method does not consider whether files or directories exist in
* the file system at the specified location.
*
* @param resource the resource to validate the location for
* @param location the location of the linked resource contents in some file system
* @return a status object with code IStatus.OK if the given
* location is valid as the linked resource location, otherwise a status
* object with severity IStatus.WARNING or
* IStatus.ERROR indicating what is wrong with the location
* @see IStatus#OK
* @see ResourcesPlugin#PREF_DISABLE_LINKING
* @since 3.2
*/
IStatus validateLinkLocationURI(IResource resource, URI location);
/**
* Validates the given string as the name of a resource valid for one of the
* given types.
*
* In addition to the basic restrictions on paths in general (see
* {@link IPath#isValidSegment(String)}), a resource name must also not
* contain any characters or substrings that are not valid on the file system
* on which workspace root is located. In addition, the names "." and ".."
* are reserved due to their special meaning in file system paths.
*
*
* This validation check is done automatically as a resource is created (but
* not when the resource handle is constructed); this means that any
* resource that exists can be safely assumed to have a valid name and path.
* Note that the name of the workspace root resource is inherently invalid.
*
*
* @param segment the name segment to be checked
* @param typeMask bitwise-or of the resource type constants (
* FILE,FOLDER,PROJECT or
* ROOT) indicating expected resource type(s)
* @return a status object with code IStatus.OK if the given
* string is valid as a resource name, otherwise a status object indicating
* what is wrong with the string
* @see IResource#PROJECT
* @see IResource#FOLDER
* @see IResource#FILE
* @see IStatus#OK
*/
IStatus validateName(String segment, int typeMask);
/**
* Validates that each of the given natures exists, and that all nature
* constraints are satisfied within the given set.
*
* The following conditions apply to validation of a set of natures:
*
*
* - all natures in the set exist in the plug-in registry
*
- all prerequisites of each nature are present in the set
*
- there are no cycles in the prerequisite graph of the set
*
- there are no two natures in the set that specify one-of-nature
* inclusion in the same group.
*
- there are no two natures in the set with the same id
*
*
* An empty nature set is always valid.
*
*
* @param natureIds an array of nature extension identifiers
* @return a status object with code IStatus.OK if the given
* set of natures is valid, otherwise a status object indicating what is
* wrong with the set
* @since 2.0
*/
IStatus validateNatureSet(String[] natureIds);
/**
* Validates the given string as a path for a resource of the given type(s).
*
* In addition to the restrictions for paths in general (see
* IPath.isValidPath), a resource path should also obey the
* following rules:
*
*
* - a resource path should be an absolute path with no device id
*
- its segments should be valid names according to
*
validateName
* - a path for the workspace root must be the canonical root path
*
- a path for a project should have exactly 1 segment
*
- a path for a file or folder should have more than 1 segment
*
- the first segment should be a valid project name
*
- the second through penultimate segments should be valid folder names
*
- the last segment should be a valid name of the given type
*
*
* Note: this method does not consider whether a resource at the specified
* path exists.
*
*
* This validation check is done automatically as a resource is created (but
* not when the resource handle is constructed); this means that any
* resource that exists can be safely assumed to have a valid name and path.
*
*
* @param path the path string to be checked
* @param typeMask bitwise-or of the resource type constants (
* FILE,FOLDER,PROJECT, or
* ROOT) indicating expected resource type(s)
* @return a status object with code IStatus.OK if the given
* path is valid as a resource path, otherwise a status object indicating
* what is wrong with the string
* @see IResource#PROJECT
* @see IResource#FOLDER
* @see IResource#FILE
* @see IStatus#OK
* @see IResourceStatus#getPath()
*/
IStatus validatePath(String path, int typeMask);
/**
* Validates the given path as the location of the given project on disk.
* The path must be either an absolute file system path, or a relative path
* whose first segment is the name of a defined workspace path variable. In
* addition to the restrictions for paths in general (see IPath.
* isValidPath),
* a location path should also obey the following rules:
*
* - must not be the same as another open or closed project
* - must not occupy the default location for any project, whether existing or not
* - must not be the same as or a parent of the platform's working directory
* - must not be the same as or a child of the location of any existing
* linked resource in the given project
*
*
* Note: this method does not consider whether files or directories exist in
* the file system at the specified path.
*
*
* @param project the project to validate the location for, can be null
* if non default project location is validated
* @param location the location of the project contents on disk, or null
* if the default project location is used
* @return a status object with code IStatus.OK if the given
* location is valid as the project content location, otherwise a status
* object indicating what is wrong with the location
* @see IProjectDescription#getLocationURI()
* @see IProjectDescription#setLocation(IPath)
* @see IStatus#OK
*/
IStatus validateProjectLocation(IProject project, IPath location);
/**
* Validates the given URI as the location of the given project.
* The location must be either an absolute URI, or a relative URI
* whose first segment is the name of a defined workspace path variable.
* A project location must obey the following rules:
*
* - must not be the same as another open or closed project
* - must not occupy the default location for any project, whether existing or not
* - must not be the same as or a parent of the platform's working directory
* - must not be the same as or a child of the location of any existing
* linked resource in the given project
*
*
* Note: this method does not consider whether files or directories exist in
* the file system at the specified path.
*
*
* @param project the project to validate the location for, can be null
* if non default project location is validated
* @param location the location of the project contents on disk, or null
* if the default project location is used
* @return a status object with code IStatus.OK if the given
* location is valid as the project content location, otherwise a status
* object indicating what is wrong with the location
* @see IProjectDescription#getLocationURI()
* @see IProjectDescription#setLocationURI(URI)
* @see IStatus#OK
* @since 3.2
*/
IStatus validateProjectLocationURI(IProject project, URI location);
/**
* Returns the path variable manager for this workspace.
*
* @return the path variable manager
* @see IPathVariableManager
* @since 2.1
*/
IPathVariableManager getPathVariableManager();
}