Eclipse Platform
Core Support for Validate Edit/Save

This proposal describes a Platform Core mechanism that allows clients to trigger VCM involvement in Core operations that change the content of file resources in the workspace. The mechanism is done in such a way that the client requires no direct knowledge on the VCM component, or even of its existence. This permits client code to work in a uniform way in all configurations.

There are two parts to the mechanism:

• Validate-edit - Explicitly activated by clients who expect  to modify a file and would like to "tickle" the VCM component so that it has an opportunity to ask the user whether they would like to check out the file (or something along those lines). A typical text editor might invoke this mechanism the first time the user dirties an editor buffer that the user has opened on a file that is read-only.
• Validate-save - Implicitly activated by clients as they modify the contents of a file resource on disk. This hook provides a final opportunity for the VCM component to check out a file that is about to be written without prior approval/check-out.

Core API for regular workspace clients

In both methods, the hook is activated in the method preamble before the method does any real work. The hook is activated unconditionally on each invocation as long as a party (i.e., the VCM component) has registered a validator. The hook method returns a status code so that it can veto the operation and provide a reason that could be presented to the user. If the veto is exercised, the client will be unable to modify the contents of the file.

The preamble looks like:

if there is a registered validator then
    call validator.validateSave passing this file
    if the returned status is not OK then
        throw a core exception with the given status (after closing the given input stream)

The hook implementation runs headless, and should not invoke UI operations on pain of deadlock.

The API specifications of IFile.appendContents and both IFile.setContents methods would be changed to add a note to the effect that these method invoke IFileModificationValidator the registered via the org.eclipse.core.resources.fileModificationValidator extension point.

The validate-edit mechanism would be exposed in the IWorkspace API interface so that a client can trigger it explicitly:

public IStatus validateEdit(IFile[] files, Object context);

This operation allows a client to declare its intent to modify all of the given files and ask for permission to proceed. The files must all exist in the workspace. The mechanism allows the VCM component to provide the implementation of this method; a typical behavior would be to check out any files that haven't already been checked out. The context passed in is a SWT shell used to parent any windows that the implementation may need to bring up to interact with the user; if no context is supplied (null is passed in), the validation must be done in a headless manner. A returned status of OK indicates to the client that it may proceed; other returned statuses indicate the reason why the individual files cannot be modified. When a UI context is supplied, the caller should assume that the user has been informed of the problems; if no UI context is passed, the caller may describe the problem to the user by displaying the returned status. Note that this operation should not change resources in the workspace.

Threading-wise, if this method is invoked from the UI thread and passed a shell, there should be no problem (even if the workspace lock is held). However, if the caller is not in the UI thread and passes a shell, you will get deep trouble if you are holding the workspace lock - because the UI brought up by the validation will be in the UI thread and will deadlock if it tries if do any workspace modification operations of its own.

Core API for the client implementing the hook

public interface IFileModificationValidator {
    public IStatus validateSave(IFile file);
    public IStatus validateEdit(IFile[] files, Object context);
}

Core Resources extension point

Description: For providing an implementation of an IFileModificationValidator to be used in the validate-edit and validate-save mechanism. This extension point tolerates at most one extension.

Configuration Markup:

   <!ELEMENT fileModificationValidator EMPTY>
   <!ATTLIST fileModificationValidator class CDATA #REQUIRED>

• class - a fully qualified name of a class which implements org.eclipse.core.resource.IFileModificationValidator.

The following is an example of using the fileModificationValidator extension point.

(in file plugin.xml)

   <extension point="org.eclipse.core.resources.fileModificationValidator">
      <fileModificationValidator class="com.xyz.vcm.VCMFileModificationValidator"/>
   </extension>

API Compatibility

• Adding a new API method to IWorkspace.
• Changing the contract of 3 existing API methods (IFile.appendContents and two IFile.setContents) in a compatible way.
• Adding a new extension point.
• Adding a new API interface to go with the new extension point.