developers/validator/index.php

<?php  																														require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php");	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); 	require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); 	$App 	= new App();	$Nav	= new Nav();	$Menu 	= new Menu();		include($App->getProjectCommon());    # All on the same line to unclutter the user's desktop'

	#*****************************************************************************
	#
	# template.php
	#
	# Author: 		Denis Roy
	# Date:			2005-06-16
	#
	# Description: Type your page comments here - these are not sent to the browser
	#
	#
	#****************************************************************************
	
	#
	# Begin: page-specific settings.  Change these. 
	$pageTitle 		= "BPEL Validator";
	$pageKeywords	= "BPEL, process, designer, milestone,validator";
	$pageAuthor		= "BPEL Team";
	
	# Add page-specific Nav bars here
	include($_SERVER['DOCUMENT_ROOT'] . "/$projectShortName/items/developers_menu.php");
			
	# End: page-specific settings
	#
	$Runner_java_html=get_include_contents('Runner.java.html');
	$ARule_java_html=get_include_contents('ARule.java.html');
	$VariableValidator_java_html=get_include_contents("VariableValidator.java.html");
 	$IFactory_java_html=get_include_contents("IFactory.java.html");
	
	# Paste your HTML content between the EOHTML markers!	
	$html = <<<EOHTML
	
<STYLE type="text/css">
pre.java {
	padding: 5px;
	margin: 10px;
	margin-left: 20px;
	border: 1px dashed #000;
	overflow: auto;
}
</STYLE>
	
	
<div id="maincontent">

	<div id="midcolumn">
		<h1>$pageTitle</h1>

		<p>
			The BPEL validator is designed to validate BPEL 2.0 source files. In
			addition
			the BPEL validator checks the
			<i>executable</i>
			BPEL processes -
			support for abstract processes is not implement.
		</p>

		<p>
			The validator code is in the plugin
			<tt>org.eclipse.bpel.validator</tt>
			which must be present for validation support to be included.
		</p>

		<h2> Workbench integration </h2>

		The validator plugin implements 2 extension points which allow it to
		be
		executed automatically when BPEL resources are modified. These are:

		<ol>
			<li>
				The BPEL "builder". Here the project must be created with the
				builder defined
				in the
				<tt>.project</tt>
				file. The builder id is
				<tt>org.eclipse.bpel.validator.builder</tt>
			</li>
			<li> The WST validation. Here, a new validator (BPEL Validator) is
				registered with
				the WST validation extensions.
 			</li>
		</ol>

		<p>
			In either situation, the validator is run "on save" of a BPEL
			resource
			and it produces a list of markers as a result on the
			resources
			which have errors in them (which are primarily the BPEL
			resources).
		</p>

		<p>
			The validator plugin defines a "BPEL marker" which is essentially a
			problem marker.
</p>

		<p>
			As all markers in Eclipse these are displayed in the
			<i>Problem View</i>
			. The resulting
			markers are shown in text editors and in the BPEL
			editor and doubleclicking
			the error in the
			<i>Problem View</i>
			will navigate to the problem location.
		</p>


		<h2> Under the covers: INode, Act 1</h2>

		<p>
			The general approach was to write the validator with no
			<i>direct dependency</i>
			on Eclipse, the EMF BPEL model, or other workbench things. The reason
			was that it might be useful
			in other places - so no
			<i>direct dependency</i>
			...
		</p>

		<p>
			Having said that, the stake in the ground was a simple
			<tt>INode</tt>
			interface to the
			<b>model</b>
			nodes - your basic "tree" node type of concept.
		</p>
		<img src="inode.gif" style="margin-left: 20px;" />
		<p>
			This adapts very easily to DOM nodes (into which BPEL source is
			transformed inititially),
			and to a slightly lesser extend to EMF
			object nodes, since they do,
			for the most part, follow that pattern.
			The leap of faith here is that
			any BPEL entity model would
			follow that
			type of a pattern ("toma-toe" vs. "tomato") and that suitable
			adapters can be build if needed.
		</p>

		<p>
			Validation then becomes a
			<i>two pass walk</i>
			through this adapted model tree where validators
			are written to the
			specific BPEL model nodes
			(so there is a
			<tt>VariableValidator</tt>
			, an
			<tt>UntilValidator</tt>
			, a
			<tt>WhileValidator</tt>
			, etc). The
			<b>input</b>
			to the validator
			is a starting
			<b>node</b>
			<i>and</i>
			something we call
			<tt>IModelQuery</tt>
			(explained later),
			and the
			<b>output</b>
			is a list or
			<b>problems</b>
			that have been found.
		</p>

		<p>
			Why a 2 pass walk ? Because walking is simple and predictable and
			the
			1
			<sup>st</sup>
			pass captures certain
			state that is only useful on the 2
			<sup>nd</sup>
			pass.

			The code is actually so simple, that it might as well
			be
			included
			here. Take a look at
			<tt>org.eclipse.bpel.validator.model.Runner</tt>

			<pre class="java" style="height: 200px;">
				$Runner_java_html
			</pre>
		</p>

		<h2> Writing Rules: IModelQuery, Act 2</h2>

		<p>
			Some checks can be made using only this simple
			<tt>INode</tt>
			model. For example,
			can this node have that node as a child, and are
			certain attributes
			set on a given node.
		</p>

		<p>
			Other checks are a little more tricky.
			For example, how do you
			determine the type of a variable ?
			Well, you have to lookup it up
			someplace. So the question becomes where
			and how ? 
		</p>

		<p>
			From the perspective of the validator, this becomes an interface
			that
			it will query against the actual implementation model (we
			called it
			<tt>IModelQuery</tt>
			).
			So the validator code would say, lookup this XSD type,
			and the
			implementor of the interface will perform the query against
			the
			prevailing models.
			The return of the "lookup this XSD type" is an
			<tt>INode</tt>
			which adapts the actual model node
			(either EMF or DOM). The
			validator
			code can then answer simple questions
			about this returned
			node via its
			<tt>INode</tt>
			interface.
			For example:
			<i>are you resolved</i>
			, or
			<i>do you exist ?</i>
		</p>
		<p>
			Type compatibility checks are also delegated to
			<tt>IModelQuery</tt>
			and are answered by the implementing model using whatever means it
			has.
		</p>

		<p>
			XPath expressions are a little tricker in that you have to walk
			the
			XPath expression trees.
			In path expressions, you may know what
			variable is being used
			(and hence you can query its type from the
			model),
			then walk the path expression.
			Again an abstraction of that
			concept is present in the model query
			interface
			so the validator
			code
			says:
			<i>can I make the next step </i>
			while the implementation of it will say
			<i>yes</i>
			or
			<i>no</i>
			.
		</p>

		<p>
			Once a problem is found, a message is generated and the
			appropriate
			information
			is put into a
			<i>problem</i>
			and then the issue becomes how to pin
			the problem to the right
			location. Once again this is delegated to
			the
			<tt>IModelQuery</tt>
			interface which will fill the appropriate
			items like EMF paths,
			XPaths, line numbers, etc, that will help pin the
			problem to a
			particular location
			in the entity model.
		</p>

		<h2> Rule exposed: Annotations, Act 3 </h2>

		<p>
			Rules are just special methods on a validator object which may be
			annotated
			and are discovered once (by reflection). The only 2
			run-time
			things
			that are interesting about
			a rule method on a
			validator object
			are 2 items:
			<ol>
				<li>rule index (order of execution)</li>
				<li>rule tag name</li>
			</ol>

			The rule index is used to mark the order of execution of the rule
			and
			the tag name is used to distiguish
			between pass1 and pass2
			rules.
		</p>
		<p>
			The full rule annotation is shown below. The other fields of the
			annotation are used for generating
			completeness documentation from
			the
			validator code.
			</p>
		<pre class="java" style="height: 100px; overflow: auto;">
			$ARule_java_html
			</pre>

		A
		<tt>VariableValidator</tt>
		segment is shown below. Here we check to make sure that a variable
		has
		at least a messageType, type, or element set. There is a rule
		to
		check
		the NCName of the variable
		(no dots) and a rule to check
		the
		message
		type.
		<pre class="java" style="height: 250px; overflow: auto;">
			$VariableValidator_java_html
			</pre>


		<h2> Validator Creation: IFactory, Act 4</h2>

		The validators used by the adapted model tree are created using
		factories which are registered
		in
		<tt>org.eclipse.bpel.validation.model.RuleFactory</tt>
		. Here are the few basic rules regarding
		creating, registering, and
		writing node validators.

		<ol>
			<li>
				Validators are specific to nodes. So an
				<tt>assign</tt>
				activity
				will be queried for its list of validators. The
				<tt>copy</tt>
				node will do the same, and so
				will
				<tt>from</tt>
				and
				<tt>to</tt>
				(to use Assign as an exmaple).
			</li>

			<li>
				A factory for validator nodes may be registered. A factory must
				implement the
				<tt>IFactory</tt>
				interface, which is again very trivial.
				<tt>null</tt>
				should be returned if the factory does
				not supply validators for
				the
				given namespace.
				<pre class="java" style="height: 150px;">
					$IFactory_java_html
 					</pre>
			</li>

			<li>
				Validators can be
				<i>chained</i>
				. Meaning a several factories can add validators for the same
				node.
			</li>

			<li>
				All validators
				<i>must extend</i>
				<tt>org.eclipse.bpel.validator.model.Validator</tt>
			</li>

		</ol>


		<h2> Self Documentation </h2>

		<p>
			For a list of rules and coverage of the static analysis checks
			<a href="sa.php">look here</a>
			.
		</p>

	</div>
	
	$rightcolumn_links
	
</div>


EOHTML;


	# Generate the web page
	$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>