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