platform-core/documents/rfc/0005/validate-edit-save.html - www.eclipse.org/eclipse - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <meta name="Author" content="Build">
    <meta name="GENERATOR" content="Mozilla/4.5 [en] (Win98; I) [Netscape]">
    <title>Validate Edit/Save</title>
 </head>
 <body>

 <h1>
 Eclipse Platform<br>
 Core Support for Validate Edit/Save</h1>
 Last revised 11:03 EST Thursday December 6 2001
 <p>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.
 <p>There are two parts to the mechanism:
 <ul>
 <li>
 <b>Validate-edit</b> - Explicitly activated by clients who expect&nbsp;
 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.</li>

 <li>
 <b>Validate-save</b> - 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.</li>
 </ul>
 An internal prototype of the validate-save mechanism was included in Eclipse
 1.0. This proposal improves and extends that early effort, and makes it
 public API in the Core resources plug-in.
 <h3>
 Core API for regular workspace clients</h3>
 The validate-save hook is hidden in the internal implementation of IFile.
 The affected methods are setContents and appendContents. Note that this
 hook does not apply to the operations that create new files (create, copy,
 move); it only affects existing files whose contents are to be modified.
 <p>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.
 <p>The preamble looks like:
 <p>if there is a registered validator then
 <br>&nbsp;&nbsp;&nbsp; call validator.validateSave passing this file
 <br>&nbsp;&nbsp;&nbsp; if the returned status is not OK then
 <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; throw a core exception with
 the given status (after closing the given input stream)
 <p>The hook implementation runs headless, and should not invoke UI operations
 on pain of deadlock.
 <p>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.
 <p>The validate-edit mechanism would be exposed in the IWorkspace API interface
 so that a client can trigger it explicitly:
 <p><font face="MS Sans Serif">public IStatus validateEdit(IFile[] files,
 Object context);</font>
 <p>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.
 <p>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.
 <h3>
 Core API for the client implementing the hook</h3>
 The following API interface would be added to the Core resources API. This
 interface would be implemented by the VCM component.
 <p><font face="MS Sans Serif">public interface <tt>IFileModificationValidator
 </tt>{</font>
 <br><font face="MS Sans Serif">&nbsp;&nbsp;&nbsp; public IStatus validateSave(IFile
 file);</font>
 <br><font face="MS Sans Serif">&nbsp;&nbsp;&nbsp; public IStatus validateEdit(IFile[]
 files, Object context);</font>
 <br><font face="MS Sans Serif">}</font>
 <h3>
 Core Resources extension point</h3>
 The Core resources plug-in would provide a new extension point, called
 fileModificationValidator, intended to be extended by none other than the
 VCM component.
 <br><b><i>Identifier: </i></b>org.eclipse.core.resources.fileModificationValidator
 <p><b><i>Description:</i></b> 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.
 <p><b><i>Configuration Markup:</i></b>
 <p><tt>&nbsp;&nbsp; &lt;!ELEMENT fileModificationValidator EMPTY></tt>
 <br><tt>&nbsp;&nbsp; &lt;!ATTLIST fileModificationValidator class CDATA
 #REQUIRED></tt>
 <ul>
 <li>
 <b>class</b> - a fully qualified name of a class which implements <tt>org.eclipse.core.resource.IFileModificationValidator</tt>.</li>
 </ul>
 <b><i>Examples:</i></b>
 <p>The following is an example of using the <tt>fileModificationValidator
 </tt>extension point.
 <p>(in file <tt>plugin.xml</tt>)
 <p><tt>&nbsp;&nbsp; &lt;extension point="org.eclipse.core.resources.fileModificationValidator"></tt>
 <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;fileModificationValidator class="com.xyz.vcm.VCMFileModificationValidator"/></tt>
 <br><tt>&nbsp;&nbsp; &lt;/extension></tt>
 <h3>
 API Compatibility</h3>
 In summary, the changes affect the Eclipse Platform Core component API
 in the following ways:
 <ul>
 <li>
 Adding a new API method to IWorkspace.</li>

 <li>
 Changing the contract of 3 existing API methods (IFile.appendContents and
 two IFile.setContents) in a compatible way.</li>

 <li>
 Adding a new extension point.</li>

 <li>
 Adding a new API interface to go with the new extension point.</li>
 </ul>
 The changes maintain full API compatibility with existing plug-ins in compliance
 with the 1.0 API.
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<meta name="Author" content="Build">
	<meta name="GENERATOR" content="Mozilla/4.5 [en] (Win98; I) [Netscape]">
	<title>Validate Edit/Save</title>
	</head>
	<body>

	<h1>
	Eclipse Platform<br>
	Core Support for Validate Edit/Save</h1>
	Last revised 11:03 EST Thursday December 6 2001
	<p>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.
	<p>There are two parts to the mechanism:
	<ul>
	<li>
	<b>Validate-edit</b> - 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.</li>

	<li>
	<b>Validate-save</b> - 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.</li>
	</ul>
	An internal prototype of the validate-save mechanism was included in Eclipse
	1.0. This proposal improves and extends that early effort, and makes it
	public API in the Core resources plug-in.
	<h3>
	Core API for regular workspace clients</h3>
	The validate-save hook is hidden in the internal implementation of IFile.
	The affected methods are setContents and appendContents. Note that this
	hook does not apply to the operations that create new files (create, copy,
	move); it only affects existing files whose contents are to be modified.
	<p>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.
	<p>The preamble looks like:
	<p>if there is a registered validator then
	<br>    call validator.validateSave passing this file
	<br>    if the returned status is not OK then
	<br>        throw a core exception with
	the given status (after closing the given input stream)
	<p>The hook implementation runs headless, and should not invoke UI operations
	on pain of deadlock.
	<p>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.
	<p>The validate-edit mechanism would be exposed in the IWorkspace API interface
	so that a client can trigger it explicitly:
	<p><font face="MS Sans Serif">public IStatus validateEdit(IFile[] files,
	Object context);</font>
	<p>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.
	<p>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.
	<h3>
	Core API for the client implementing the hook</h3>
	The following API interface would be added to the Core resources API. This
	interface would be implemented by the VCM component.
	<p><font face="MS Sans Serif">public interface <tt>IFileModificationValidator
	</tt>{</font>
	<br><font face="MS Sans Serif">    public IStatus validateSave(IFile
	file);</font>
	<br><font face="MS Sans Serif">    public IStatus validateEdit(IFile[]
	files, Object context);</font>
	<br><font face="MS Sans Serif">}</font>
	<h3>
	Core Resources extension point</h3>
	The Core resources plug-in would provide a new extension point, called
	fileModificationValidator, intended to be extended by none other than the
	VCM component.
	<br><b><i>Identifier: </i></b>org.eclipse.core.resources.fileModificationValidator
	<p><b><i>Description:</i></b> 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.
	<p><b><i>Configuration Markup:</i></b>
	<p><tt>   <!ELEMENT fileModificationValidator EMPTY></tt>
	<br><tt>   <!ATTLIST fileModificationValidator class CDATA
	#REQUIRED></tt>
	<ul>
	<li>
	<b>class</b> - a fully qualified name of a class which implements <tt>org.eclipse.core.resource.IFileModificationValidator</tt>.</li>
	</ul>
	<b><i>Examples:</i></b>
	<p>The following is an example of using the <tt>fileModificationValidator
	</tt>extension point.
	<p>(in file <tt>plugin.xml</tt>)
	<p><tt>   <extension point="org.eclipse.core.resources.fileModificationValidator"></tt>
	<br><tt>      <fileModificationValidator class="com.xyz.vcm.VCMFileModificationValidator"/></tt>
	<br><tt>   </extension></tt>
	<h3>
	API Compatibility</h3>
	In summary, the changes affect the Eclipse Platform Core component API
	in the following ways:
	<ul>
	<li>
	Adding a new API method to IWorkspace.</li>

	<li>
	Changing the contract of 3 existing API methods (IFile.appendContents and
	two IFile.setContents) in a compatible way.</li>

	<li>
	Adding a new extension point.</li>

	<li>
	Adding a new API interface to go with the new extension point.</li>
	</ul>
	The changes maintain full API compatibility with existing plug-ins in compliance
	with the 1.0 API.
	</body>
	</html>