jst/components/j2ee/proposals/ValidatorFramework.xml - gerrit/www.eclipse.org/webtools - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <?xml-stylesheet type="text/s;" href="../../../../wtp.xsl"?>
 <html>
 	<head>
 		<meta name="root" content="../../../../.." />
 		<title>Validation framework</title>
 	</head>

 	<body>
 		<h1>jst j2ee</h1>
 <b>By:</b>
 <p>
  Chuck Bridgham (cbridgha@us.ibm.com) <br/>
  Neeraj Agrawal (nagrawal@us.ibm.com) <br/>
  Vijay Bhadriraju(vbhadrir@us.ibm.com)<br/>
  </p>

 		<h2>Introduction</h2>
 		<br/>
 		<p>
            This document describes the requirements and design of the proposed
            enhancements to the validation framework including Job integration.
            Most of these changes are performance related, and pushing the validation
            processing to the background. We also include additional enhancements to
            the framework.
 		</p>
 		<br/>
 		<h2>Requirements</h2>
 		<br/>
 		<b>Performance</b>
 		<ol>
 		<br/><br/>
 			<li>
 				<p>
 					 Executing validators asynchronously  (Jobs)
 				</p>
 				<ul>
 		       		<li>Validators are read-only.</li>
 			       	<li>
 			       		Validators can be stopped or canceled.
 			       	</li>
 			       	<li>
 			       		Validators must avoid locking any resources. - Minimal set of scheduling rules should be used – Default would use Empty scheduling rule.
 			       	</li>
 			       	<li>
                         Development time tracing to ensure locking rules are followed. (framework will log)
 					</li>
 		       	</ul>

 			</li>
 			<br/>
 			<li>
 			<p>
 				Collect status for each validation execution.
 			</p>
 				<ul>
 				<li>
 				     Configuring/Handling failed validators.
 				</li>
 				</ul>
 			</li>
 			<br/>
 			<li>
 				<p>Synchronous validator support using Jobs</p>
 				<ul>
 					<li>Dependent validation. – Allow defining dependent validators at the plugin extension level, determines which Jobs will run synchronously.</li>
 				</ul>

 			</li>
 			<br/>
 		</ol>
 		<b>Required Enhancements </b> <br/>
 		<ol>


 			<li>
 			Integration of Facet filters (facet regristration)
 			</li>
 			<br/>
 			<br/>
 			<li>
 				<p>Product/Plugin configuration</p>
 				<ul>
 					<li>Validator settings can be configured using workspace or  install level configuration.</li>
 				</ul>
 			</li>
 		</ol>

 		<h2>UI Requirements</h2>
 		<br/>
 		<li>
 			<p>
 				There should be two checkboxes per validator. One that controls whether
 				the validator runs during a manual validation and one that control
 				whether it runs during a build (either manual or incremental).
 				If both check boxes are unchecked the validator never runs.
 				By default the more expensive validators will have their build time checkbox unchecked.
 			</p>
 		</li>

 		<br/>
 		<h2>Bugzillas </h2>
 		<br/>
 		<li>
 		 <a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=91563">Background Validaton </a>
 		</li>

 		<li>
 		 <a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=124391">Post Validator</a>
 		</li>

 		<li>
 		 <a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=118448">Facet enabled Validator</a>
 		</li>

 		<li>
 		<a href= "https://bugs.eclipse.org/bugs/show_bug.cgi?id=125749">Preference  Configuration</a>
 		</li>
 		<br/>
 		<br/>

 		<h2>Design</h2>
 		<br/>

 		<p> <b>Client changes</b> </p>
 		<ol>

 		<li>
 		 <p>
 			New Interface: A new interface will be added to the framework, and will
 			need to be implemented by all client Validator authors.

 			<br/>
 			<br/>
 			Existing IValidator api will be used if not implemented, and will not use Jobs.

 			<br/>
 			<br/>
 				<pre>
 public interface IValidatorJob extends IValidator {

  public IStatus validateInJon(IValidationContext helper, IReporter reporter) throws ValidationException;
  public ISchedulingRule getSchedulingRule(IValidationContext helper);

 }
 				</pre>
 		 </p>
 		</li>

 		<li>
 		<p>
 			Several new rules are suggested or enforced:
 		</p>

 		<ul>
 			<li>
 				Read only validators- are only allowed to read resources with the exception of modifying markers.
 			</li>
 		 	<li>
 				Cancelable, need to poll the isCancelled() method of IReporter.
 		 	</li>
 		 	<li>
 				Publish task information to the progress monitor using displaySubtask() of IReporter.
 		 	</li>
 		 	<li>
 		 	   Use minimal set of scheduling rules, default is Empty scheduling rule.
 	<pre>
 	public class EmptyRule implements ISchedulingRule {

              public boolean contains(ISchedulingRule rule)
              {
                   return rule == this;
              }

              public boolean isConflicting(ISchedulingRule rule) {
                   return rule == this;
              }

 	}
 	</pre>

 		 	</li>

 		 	<li>
 		 	 return status of execution as IStatus to the framework.
 		 	</li>


 		 	<li>
 		 	<p>Synchronous dependent validator Jobs</p>
 					<p>
 					     Consider Validators A, B, C: <br/>
 					<pre>
                      A
                       |
                       B
                        |
                        C
 					</pre>
 				   </p>

 				   <p>
 					C shouldn't run until B is successfully executed and B shouldn't run unless A is successfully executed.
 					The ordering of execution is implemented in the framework using join mechanism provided by the
 					eclipse platform.
 				   </p>


                     A more concrete example is ejb-jar.xml validation, if XSD validator already exists as one
 					of the validators, ejb validator could be made dependent of the
 					XSD validator by defining a “runAfter” element in the Validator extension point.

 					<br/>

 					So ejb validator runs only when the XSD validator
 					has run successfully.

 					<br/>
 					<br/>
 					Sample validator extension point:
 <pre>
    &lt;extension
          id="WarValidator"
          name="WebValidator"
          point="org.eclipse.wst.validation.validator"&gt;
       &lt;validator>
          &lt;projectNature
                id="org.eclipse.wst.common.modulecore.ModuleCoreNature"&gt;
          &lt;/projectNature>
          &lt;filter
                objectClass="org.eclipse.core.resources.IFile"
                nameFilter="web.xml"&gt;
          &lt;/filter&gt;
          &lt;helper
                class="org.eclipse.jst.j2ee.internal.web.validation.UIWarHelper"&gt;
          &lt;/helper&gt;
          &lt;dependentValidator
                depValValue="true"&gt;
          &lt;/dependentValidator&gt;
          <b>&lt;runAfter&gt;</b>
              validator="org.eclipse.sample.validator"
          <b>&lt;/runAfter&gt;</b>
          &lt;run
                class="org.eclipse.jst.j2ee.internal.web.validation.UIWarValidator"&gt;
          &lt;/run&gt;
       &lt;/validator&gt;
    &lt;/extension>
 </pre>

 </li>

 		 	<li>
 				Integration of Facet filters (facet regristration)
 				New optional extensionpoint elements are available to register validators against facet ids rather than natures.

 				<pre>
 &lt;facet
     facetId="jst.ejb"&gt;
 &lt;/facet>
 				</pre>

 		 	</li>

 		</ul>
 		</li>

 		<br/>
 	</ol>

 	<ol>
 <b>Framework Changes</b>
 <br/>
 <br/>
 			<li>
 			    ValidationOperation will
 			    create Job for each Validator(implementer of IValidatorJob) and start them. <br/>
 			    On manual invocation of validation, the ValidationOperation will execute  as a Job and the existing IValidator implementors will run on the same job as ValidationOperation.
 			    <br/>
 			    <br/>

 			    <p>Example displaying a Validation operation running as a job: </p>
 			    <pre>

 where op is of type ValidationOperation,
 ValidationJobAdapter extends Job and EmptyRule is defined above in the document.

         ValidationJobAdapter jobAdapter = new ValidationJobAdapter(op);
         EmptyRule rule = new EmptyRule();
         jobAdapter.setRule(rule);
         jobAdapter.setUser(true);
         jobAdapter.schedule();

 			    </pre>


 		Example of a validator job running from the framework:<br/><br/>


 		<pre>

         Job validationJob = new Job(validator.getClass().getName())
         {

            protected IStatus run(IProgressMonitor monitor)
            {
                 IStatus status =  validator.validate(helper, reporter, monitor);

            }
         };
         validationJob.setRule(validator.getSchedulingRule());
         validationJob.schedule();
 		</pre>

 		<ul>
 		 <li>
 		 If a validator is running and a build is triggered, the runnnig validator
 		 is canceled since it will be executed again as part of the build.
 		 </li>
 		</ul>
 		</li>


 			<br/>
 			<li>
 				<p>Framework changes required to support synchronous dependent validators</p>

 <pre>
 <p>The framework will schedule dependent validators as shown in the following example: </p>
 Job validatorA = new Job("Validator A");
 validatorA.schedule();

 Job validatorB = new Job("Validator B");
 validatorB.setProperty("ParentValidator", validatorA);
 validatorB.schedule();


 <p> Validator B wont start until A finishes</p>
 protectded IStatus run(IProgressMonitor monitor){

 	try{

 	  //ValidatorB waiting on ValidatorA
 	  Job validatorA = (Job)getProperty("ParentValidator");
 	  validatorA.join();

 	  if( validatorA.getResult() == IStatus.OK){
 	  //validatorA done, can continue
 	  }

 	}catch(InterruptedException e){

 	}
 }

 </pre>


 			</li>
 	</ol>


 	</body>
 </html>
	<?xml version="1.0" encoding="UTF-8"?>
	<?xml-stylesheet type="text/s;" href="../../../../wtp.xsl"?>
	<html>
	<head>
	<meta name="root" content="../../../../.." />
	<title>Validation framework</title>
	</head>

	<body>
	<h1>jst j2ee</h1>
	<b>By:</b>
	<p>
	Chuck Bridgham (cbridgha@us.ibm.com) <br/>
	Neeraj Agrawal (nagrawal@us.ibm.com) <br/>
	Vijay Bhadriraju(vbhadrir@us.ibm.com)<br/>
	</p>

	<h2>Introduction</h2>
	<br/>
	<p>
	This document describes the requirements and design of the proposed
	enhancements to the validation framework including Job integration.
	Most of these changes are performance related, and pushing the validation
	processing to the background. We also include additional enhancements to
	the framework.
	</p>
	<br/>
	<h2>Requirements</h2>
	<br/>
	<b>Performance</b>
	<ol>
	<br/><br/>
	<li>
	<p>
	Executing validators asynchronously (Jobs)
	</p>
	<ul>
	<li>Validators are read-only.</li>
	<li>
	Validators can be stopped or canceled.
	</li>
	<li>
	Validators must avoid locking any resources. - Minimal set of scheduling rules should be used – Default would use Empty scheduling rule.
	</li>
	<li>
	Development time tracing to ensure locking rules are followed. (framework will log)
	</li>
	</ul>

	</li>
	<br/>
	<li>
	<p>
	Collect status for each validation execution.
	</p>
	<ul>
	<li>
	Configuring/Handling failed validators.
	</li>
	</ul>
	</li>
	<br/>
	<li>
	<p>Synchronous validator support using Jobs</p>
	<ul>
	<li>Dependent validation. – Allow defining dependent validators at the plugin extension level, determines which Jobs will run synchronously.</li>
	</ul>

	</li>
	<br/>
	</ol>
	<b>Required Enhancements </b> <br/>
	<ol>


	<li>
	Integration of Facet filters (facet regristration)
	</li>
	<br/>
	<br/>
	<li>
	<p>Product/Plugin configuration</p>
	<ul>
	<li>Validator settings can be configured using workspace or install level configuration.</li>
	</ul>
	</li>
	</ol>

	<h2>UI Requirements</h2>
	<br/>
	<li>
	<p>
	There should be two checkboxes per validator. One that controls whether
	the validator runs during a manual validation and one that control
	whether it runs during a build (either manual or incremental).
	If both check boxes are unchecked the validator never runs.
	By default the more expensive validators will have their build time checkbox unchecked.
	</p>
	</li>

	<br/>
	<h2>Bugzillas </h2>
	<br/>
	<li>
	<a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=91563">Background Validaton </a>
	</li>

	<li>
	<a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=124391">Post Validator</a>
	</li>

	<li>
	<a href = "https://bugs.eclipse.org/bugs/show_bug.cgi?id=118448">Facet enabled Validator</a>
	</li>

	<li>
	<a href= "https://bugs.eclipse.org/bugs/show_bug.cgi?id=125749">Preference Configuration</a>
	</li>
	<br/>
	<br/>

	<h2>Design</h2>
	<br/>

	<p> <b>Client changes</b> </p>
	<ol>

	<li>
	<p>
	New Interface: A new interface will be added to the framework, and will
	need to be implemented by all client Validator authors.

	<br/>
	<br/>
	Existing IValidator api will be used if not implemented, and will not use Jobs.

	<br/>
	<br/>
	<pre>
	public interface IValidatorJob extends IValidator {

	public IStatus validateInJon(IValidationContext helper, IReporter reporter) throws ValidationException;
	public ISchedulingRule getSchedulingRule(IValidationContext helper);

	}
	</pre>
	</p>
	</li>

	<li>
	<p>
	Several new rules are suggested or enforced:
	</p>

	<ul>
	<li>
	Read only validators- are only allowed to read resources with the exception of modifying markers.
	</li>
	<li>
	Cancelable, need to poll the isCancelled() method of IReporter.
	</li>
	<li>
	Publish task information to the progress monitor using displaySubtask() of IReporter.
	</li>
	<li>
	Use minimal set of scheduling rules, default is Empty scheduling rule.
	<pre>
	public class EmptyRule implements ISchedulingRule {

	public boolean contains(ISchedulingRule rule)
	{
	return rule == this;
	}

	public boolean isConflicting(ISchedulingRule rule) {
	return rule == this;
	}

	}
	</pre>

	</li>

	<li>
	return status of execution as IStatus to the framework.
	</li>



	<li>
	<p>Synchronous dependent validator Jobs</p>
	<p>
	Consider Validators A, B, C: <br/>
	<pre>
	A
	\|
	B
	\|
	C
	</pre>
	</p>

	<p>
	C shouldn't run until B is successfully executed and B shouldn't run unless A is successfully executed.
	The ordering of execution is implemented in the framework using join mechanism provided by the
	eclipse platform.
	</p>


	A more concrete example is ejb-jar.xml validation, if XSD validator already exists as one
	of the validators, ejb validator could be made dependent of the
	XSD validator by defining a “runAfter” element in the Validator extension point.

	<br/>

	So ejb validator runs only when the XSD validator
	has run successfully.

	<br/>
	<br/>
	Sample validator extension point:
	<pre>
	<extension
	id="WarValidator"
	name="WebValidator"
	point="org.eclipse.wst.validation.validator">
	<validator>
	<projectNature
	id="org.eclipse.wst.common.modulecore.ModuleCoreNature">
	</projectNature>
	<filter
	objectClass="org.eclipse.core.resources.IFile"
	nameFilter="web.xml">
	</filter>
	<helper
	class="org.eclipse.jst.j2ee.internal.web.validation.UIWarHelper">
	</helper>
	<dependentValidator
	depValValue="true">
	</dependentValidator>
	<b><runAfter></b>
	validator="org.eclipse.sample.validator"
	<b></runAfter></b>
	<run
	class="org.eclipse.jst.j2ee.internal.web.validation.UIWarValidator">
	</run>
	</validator>
	</extension>
	</pre>

	</li>

	<li>
	Integration of Facet filters (facet regristration)
	New optional extensionpoint elements are available to register validators against facet ids rather than natures.

	<pre>
	<facet
	facetId="jst.ejb">
	</facet>
	</pre>

	</li>

	</ul>
	</li>

	<br/>
	</ol>

	<ol>
	<b>Framework Changes</b>
	<br/>
	<br/>
	<li>
	ValidationOperation will
	create Job for each Validator(implementer of IValidatorJob) and start them. <br/>
	On manual invocation of validation, the ValidationOperation will execute as a Job and the existing IValidator implementors will run on the same job as ValidationOperation.
	<br/>
	<br/>

	<p>Example displaying a Validation operation running as a job: </p>
	<pre>

	where op is of type ValidationOperation,
	ValidationJobAdapter extends Job and EmptyRule is defined above in the document.

	ValidationJobAdapter jobAdapter = new ValidationJobAdapter(op);
	EmptyRule rule = new EmptyRule();
	jobAdapter.setRule(rule);
	jobAdapter.setUser(true);
	jobAdapter.schedule();

	</pre>


	Example of a validator job running from the framework:<br/><br/>


	<pre>

	Job validationJob = new Job(validator.getClass().getName())
	{

	protected IStatus run(IProgressMonitor monitor)
	{
	IStatus status = validator.validate(helper, reporter, monitor);

	}
	};
	validationJob.setRule(validator.getSchedulingRule());
	validationJob.schedule();
	</pre>

	<ul>
	<li>
	If a validator is running and a build is triggered, the runnnig validator
	is canceled since it will be executed again as part of the build.
	</li>
	</ul>
	</li>




	<br/>
	<li>
	<p>Framework changes required to support synchronous dependent validators</p>

	<pre>
	<p>The framework will schedule dependent validators as shown in the following example: </p>
	Job validatorA = new Job("Validator A");
	validatorA.schedule();

	Job validatorB = new Job("Validator B");
	validatorB.setProperty("ParentValidator", validatorA);
	validatorB.schedule();


	<p> Validator B wont start until A finishes</p>
	protectded IStatus run(IProgressMonitor monitor){

	try{

	//ValidatorB waiting on ValidatorA
	Job validatorA = (Job)getProperty("ParentValidator");
	validatorA.join();

	if( validatorA.getResult() == IStatus.OK){
	//validatorA done, can continue
	}

	}catch(InterruptedException e){

	}
	}

	</pre>


	</li>
	</ol>


	</body>
	</html>