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