|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 subdirectory, 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 snapshoting 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.
This interface is not intended to be implemented by clients.
Workspaces implement the IAdaptable
interface;
extensions are managed by the platform's adapter manager.
Method Summary | |
void |
addResourceChangeListener(IResourceChangeListener listener)
Adds the given listener for resource change events to this workspace. |
void |
addResourceChangeListener(IResourceChangeListener listener,
int eventMask)
Adds the given listener for the specified resource change events to this workspace. |
ISavedState |
addSaveParticipant(Plugin plugin,
ISaveParticipant participant)
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. |
void |
build(int kind,
IProgressMonitor monitor)
Builds all projects in this workspace. |
void |
checkpoint(boolean build)
Checkpoints the operation currently in progress. |
IProject[][] |
computePrerequisiteOrder(IProject[] projects)
Returns the prerequisite ordering of the given projects. |
IStatus |
copy(IResource[] resources,
IPath destination,
boolean force,
IProgressMonitor monitor)
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. |
IStatus |
copy(IResource[] resources,
IPath destination,
int updateFlags,
IProgressMonitor monitor)
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. |
IStatus |
delete(IResource[] resources,
boolean force,
IProgressMonitor monitor)
Deletes the given resources. |
IStatus |
delete(IResource[] resources,
int updateFlags,
IProgressMonitor monitor)
Deletes the given resources. |
void |
deleteMarkers(IMarker[] markers)
Removes the given markers from the resources with which they are associated. |
void |
forgetSavedTree(String pluginId)
Forgets any resource tree being saved for the plug-in with the given name. |
Map |
getDanglingReferences()
Finds all dangling project references in this workspace. |
IWorkspaceDescription |
getDescription()
Returns the workspace description. |
IProjectNatureDescriptor |
getNatureDescriptor(String natureId)
Returns the nature descriptor with the given unique identifier, or null if there is no such nature. |
IProjectNatureDescriptor[] |
getNatureDescriptors()
Returns all nature descriptors known to this workspace. |
IWorkspaceRoot |
getRoot()
Returns the root resource of this workspace. |
ISynchronizer |
getSynchronizer()
Returns the synchronizer for this workspace. |
boolean |
isAutoBuilding()
Returns whether this workspace performs auto-builds. |
IProjectDescription |
loadProjectDescription(IPath projectDescriptionFile)
Reads the project description file (".project") from the given location in the local file system. |
IStatus |
move(IResource[] resources,
IPath destination,
boolean force,
IProgressMonitor monitor)
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. |
IStatus |
move(IResource[] resources,
IPath destination,
int updateFlags,
IProgressMonitor monitor)
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. |
IProjectDescription |
newProjectDescription(String projectName)
Creates and returns a new project description for a project with the given name. |
void |
removeResourceChangeListener(IResourceChangeListener listener)
Removes the given resource change listener from this workspace. |
void |
removeSaveParticipant(Plugin plugin)
Removes the workspace save participant for the given plug-in from this workspace. |
void |
run(IWorkspaceRunnable action,
IProgressMonitor monitor)
Runs the given action as an atomic workspace operation. |
IStatus |
save(boolean full,
IProgressMonitor monitor)
Saves this workspace's valuable state on disk. |
void |
setDescription(IWorkspaceDescription description)
Sets the workspace description. |
void |
setWorkspaceLock(WorkspaceLock lock)
Sets the lock to use for controlling write access to this workspace. |
String[] |
sortNatureSet(String[] natureIds)
Returns a copy of the given set of natures sorted in prerequisite order. |
IStatus |
validateEdit(IFile[] files,
Object context)
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. |
IStatus |
validateName(String segment,
int typeMask)
Validates the given string as the name of a resource valid for one of the given types. |
IStatus |
validateNatureSet(String[] natureIds)
Validates that each of the given natures exists, and that all nature constraints are satisfied within the given set. |
IStatus |
validatePath(String path,
int typeMask)
Validates the given string as a path for a resource of the given type(s). |
IStatus |
validateProjectLocation(IProject project,
IPath location)
Validates the given path as the location of the given project on disk. |
Methods inherited from interface org.eclipse.core.runtime.IAdaptable |
getAdapter |
Method Detail |
public void addResourceChangeListener(IResourceChangeListener listener)
This method is equivalent to:
addResourceChangeListener(listener, IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE | IResourceChangeEvent.POST_CHANGE);
listener
- the listenerIResourceChangeListener
,
IResourceChangeEvent
,
addResourceChangeListener(IResourceChangeListener, int)
,
removeResourceChangeListener(org.eclipse.core.resources.IResourceChangeListener)
public void addResourceChangeListener(IResourceChangeListener listener, int eventMask)
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.
listener
- the listenereventMask
- the bit-wise OR of all event types of interest to the listenerIResourceChangeListener
,
IResourceChangeEvent
,
removeResourceChangeListener(org.eclipse.core.resources.IResourceChangeListener)
public ISavedState addSaveParticipant(Plugin plugin, ISaveParticipant participant) throws CoreException
Once registered, the workspace save participant will actively participate in the saving of this workspace.
plugin
- the plug-inparticipant
- the participant
null
if the plug-in has not participated before
CoreException
- if the method fails to add the participant.
Reasons include:
ISaveParticipant
,
removeSaveParticipant(org.eclipse.core.runtime.Plugin)
public void build(int kind, IProgressMonitor monitor) throws CoreException
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.
kind
- the kind of build being requested. Valid values are
FULL_BUILD
- indicates a full build.INCREMENTAL_BUILD
- indicates a incremental build.monitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
CoreException
- if some of the builds fail.
The status contained in the exception is a multi-status with
entries for the project builds that failed.IProject.build(int, java.lang.String, java.util.Map, org.eclipse.core.runtime.IProgressMonitor)
,
computePrerequisiteOrder(org.eclipse.core.resources.IProject[])
,
IncrementalProjectBuilder.FULL_BUILD
,
IncrementalProjectBuilder.INCREMENTAL_BUILD
public void checkpoint(boolean build)
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 auto-build (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).
build
- whether or not to run a buildrun(org.eclipse.core.resources.IWorkspaceRunnable, org.eclipse.core.runtime.IProgressMonitor)
public IProject[][] computePrerequisiteOrder(IProject[] projects)
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.
projects
- the projects to order
public IStatus copy(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException
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.
resources
- the resources to copydestination
- the destination container pathforce
- a flag controlling whether resources that are not
in sync with the local file system will be toleratedmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages
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.copy(IResource[],IPath,int,IProgressMonitor)
public IStatus copy(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException
This method can be expressed as a series of calls to
IResource.copy(IPath,int,IProgressMonitor
, with "best effort"
semantics:
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.
resources
- the resources to copydestination
- the destination container pathupdateFlags
- bit-wise or of update flag constantsmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages
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:
FORCE
is not specified.IResource.copy(IPath,int,IProgressMonitor)
public IStatus delete(IResource[] resources, boolean force, IProgressMonitor monitor) throws CoreException
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.
resources
- the resources to deleteforce
- a flag controlling whether resources that are not
in sync with the local file system will be toleratedmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages
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.delete(IResource[],int,IProgressMonitor)
public IStatus delete(IResource[] resources, int updateFlags, IProgressMonitor monitor) throws CoreException
This method can be expressed as a series of calls to
IResource.delete(int,IProgressMonitor)
.
The semantics of multiple deletion are:
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.
resources
- the resources to deleteupdateFlags
- bit-wise or of update flag constantsmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages
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.IResource.delete(int,IProgressMonitor)
public void deleteMarkers(IMarker[] markers) throws CoreException
This method changes resources; these changes will be reported in a subsequent resource change event.
markers
- the markers to remove
CoreException
- if this method fails. Reasons include:
public void forgetSavedTree(String pluginId)
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
a 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.
pluginId
- the unique identifier of the plug-inISaveContext.needDelta()
public IProjectNatureDescriptor[] getNatureDescriptors()
public IProjectNatureDescriptor getNatureDescriptor(String natureId)
null
if there is no such nature.
natureId
- the nature extension identifer
(e.g. "com.example.coolNature"
).
null
public Map getDanglingReferences()
IProject
, value type: IProject[]
)
from project to dangling project referencespublic IWorkspaceDescription getDescription()
IWorkspace.setDescription
needs to be called.
setDescription(org.eclipse.core.resources.IWorkspaceDescription)
public IWorkspaceRoot getRoot()
public ISynchronizer getSynchronizer()
ISynchronizer
public boolean isAutoBuilding()
true
if auto-building is on, false
otherwisepublic IProjectDescription loadProjectDescription(IPath projectDescriptionFile) throws CoreException
The returned value is writeable.
projectDescriptionFile
- the path in the local file system of an
existing project description file
CoreException
- if the operation failed, either because the
project description file does not exist, or cannot be opened, or
cannot be parsed as a legal project description filenewProjectDescription(java.lang.String)
,
IProject.getDescription()
public IStatus move(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException
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.
resources
- the resources to movedestination
- the destination container pathforce
- a flag controlling whether resources that are not
in sync with the local file system will be toleratedmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages.
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.move(IResource[],IPath,int,IProgressMonitor)
public IStatus move(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException
This method can be expressed as a series of calls to
IResource.move
, with "best effort" semantics:
force
flag has the same meaning as it does
on the corresponding single-resource method.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.
resources
- the resources to movedestination
- the destination container pathupdateFlags
- bit-wise or of update flag constantsmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
OK
if there were no problems;
otherwise a description (possibly a multi-status) consisting of
low-severity warnings or informational messages.
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:
FORCE
is false
.IResource.move(IPath,int,IProgressMonitor)
public IProjectDescription newProjectDescription(String projectName)
The project description is initialized to:
The returned value is writeable.
projectName
- the name of the project
IProject.getDescription()
,
IProject.create(org.eclipse.core.resources.IProjectDescription, org.eclipse.core.runtime.IProgressMonitor)
,
IResource.copy(org.eclipse.core.resources.IProjectDescription, boolean, org.eclipse.core.runtime.IProgressMonitor)
,
IProject.move(org.eclipse.core.resources.IProjectDescription, boolean, org.eclipse.core.runtime.IProgressMonitor)
public void removeResourceChangeListener(IResourceChangeListener listener)
listener
- the listenerIResourceChangeListener
,
addResourceChangeListener(org.eclipse.core.resources.IResourceChangeListener)
public void removeSaveParticipant(Plugin plugin)
Once removed, the workspace save participant no longer actively participates in any future saves of this workspace.
plugin
- the plug-inISaveParticipant
,
addSaveParticipant(org.eclipse.core.runtime.Plugin, org.eclipse.core.resources.ISaveParticipant)
public void run(IWorkspaceRunnable action, IProgressMonitor monitor) throws CoreException
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.
action
- the action to performmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
CoreException
- if the operation failed.public IStatus save(boolean full, IProgressMonitor monitor) throws CoreException
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 infos. 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 anytime 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:
save
save
save
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.
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).
prepareToSave(context)
, passing in its own context object.
prepareToSave
fails (throws an exception),
the problem is logged and the participant is marked as unstable.
saving(context)
, passing in its own context object.
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.
saving
fails (throws an exception),
the problem is logged and the participant is marked as unstable.
doneSaving(context)
, passing in its own context object.
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.)
rollback(context)
, passing in its own context object.
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.)
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.)
full
- true
if this is a full save, and
false
if this is only a snapshot
for protecting against crashesmonitor
- a progress monitor, or null
if progress
reporting and cancellation are not desired
CoreException
- if this method fails to save
the state of this workspace. Reasons include:
addSaveParticipant(org.eclipse.core.runtime.Plugin, org.eclipse.core.resources.ISaveParticipant)
public void setDescription(IWorkspaceDescription description) throws CoreException
description
- the new workspace description.
CoreException
- if the method fails.
Reasons include:
getDescription()
public void setWorkspaceLock(WorkspaceLock lock)
This method is for internal use by the platform-related plug-ins. Clients should not call this method.
lock
- the lock to install on this workspace.public String[] sortNatureSet(String[] natureIds)
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.
natureIds
- a valid set of nature extension identifiers
validateNatureSet(java.lang.String[])
public IStatus validateEdit(IFile[] files, Object context)
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 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 IFileModificationValidator.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 IStatus.ERROR
code if one of the
files is read-only, and a status with an IStatus.OK
code otherwise.
files
- the files that are to be modified; these files must all exist in the workspacecontext
- 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)
public IStatus validateName(String segment, int typeMask)
In addition to the basic restrictions on paths in general
(see IPath.isValidSegment
),
a resource name must also obey the following rules:
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.
segment
- the name segment to be checkedtypeMask
- bitwise-or of the resource type constants (
FILE
, FOLDER
,
PROJECT
or ROOT
) indicating
expected resource type(s)
IStatus.OK
if
the given string is valid as a resource name, otherwise a status
object indicating what is wrong with the stringIResource.PROJECT
,
IResource.FOLDER
,
IResource.FILE
,
IStatus.OK
public IStatus validateNatureSet(String[] natureIds)
The following conditions apply to validation of a set of natures:
An empty nature set is always valid.
natureIds
- an array of nature extension identifiers
IStatus.OK
if
the given set of natures is valid, otherwise a status
object indicating what is wrong with the setpublic IStatus validatePath(String path, int typeMask)
In addition to the restrictions for
paths in general (see IPath.isValidPath
),
a resource path should also obey the following rules:
validateName
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.
path
- the path string to be checkedtypeMask
- bitwise-or of the resource type constants (
FILE
, FOLDER
, PROJECT
,
or ROOT
) indicating expected resource type(s)
IStatus.OK
if
the given path is valid as a resource path, otherwise a status
object indicating what is wrong with the stringIResource.PROJECT
,
IResource.FOLDER
,
IResource.FILE
,
IStatus.OK
,
IResourceStatus.getPath()
public IStatus validateProjectLocation(IProject project, IPath location)
IPath.isValidPath
),
a location path should also obey the following rules:
Note: this method does not consider whether files or directories exist in the filesystem at the specified path.
project
- the project to validate the location forlocation
- the location of the project contents on disk
IStatus.OK
if
the given location is valid as the project content location, otherwise a status
object indicating what is wrong with the stringIProjectDescription.getLocation()
,
IProjectDescription.setLocation(org.eclipse.core.runtime.IPath)
,
IStatus.OK
|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |