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 passedas 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.
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
| |
| |
| |