developers/validator/index.php - www.eclipse.org/bpel - Git at Google

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