developers/model.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 Model";
 	$pageKeywords	= "BPEL, model";
 	$pageAuthor		= "BPEL Team";

 	# Add page-specific Nav bars here
 	# Format is Link text, link URL (can be http://www.someothersite.com/), target (_self, _blank), level (1, 2 or 3)
 	include($_SERVER['DOCUMENT_ROOT'] . "/$projectShortName/items/developers_menu.php");

 	# End: page-specific settings
 	#

 	# Paste your HTML content between the EOHTML markers!
 	$html = <<<EOHTML


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

 Last modified on December 7, 2005

 <p>
 This document attempts to explain many of the design decisions present in
 the BPEL model, as well as where to locate key code and how to make changes.
 </p>

 <h2>Spec Level</h2>

 <p>
 The model will track the evolving OASIS WS-BPEL specification as it
 approaches 2.0. Current support of the model is at the 1.1 level plus the
 following resolved OASIS issues:
 </p>
 <ul class="midlist">
 <li>Issue 13 (Expressions and Queries in Elements instead of Attributes)</li>
 <li>Issue 34 (No Dependency on WS-A)</li>
 <li>Issue 37 and 202 (Add "join" value to initiate attribute of Correlation)</li>
 <li>Issue 68 (Catch syntax broken)</li>
 </ul>

 <h2>Model Objects</h2>

 <p>
 Most of the BPEL model objects, with some exceptions, are located in the
 <i>org.eclipse.bpel.model</i> package.
 </p>

 <p>
 Message properties and property aliases are located in
 <i>org.eclipse.bpel.model.messageproperties</i>.
 </p>

 <p>
 Partner link types and roles are located in
 <i>org.eclipse.bpel.model.partnerlinktype.</i>
 </p>

 <h2>Reading and Writing BPEL Files</h2>

 <p>
 Most of the conversion from the .bpel file into an EMF model occurs in
 <i>org.eclipse.bpel.core.resources.BPELReader</i>. This class is instantiated
 by <i>BPELResourceImpl</i>, which in turn is created by <i>BPELResourceFactoryImpl</i>,
 which is registered in the plugin.xml file as the extension parser for
 .bpel files.
 </p>

 <p>
 <i>BPELReader</i> has methods for translating each of the BPEL elements and
 attributes from DOM objects into EMF objects. At the moment, the DOM
 objects are discarded by the reader once the EMF objects are created,
 and they are recreated by the <i>BPELWriter</i>. However, this has the
 disadvantage of losing any user formatting and comments in the source
 file upon save. The model should use the same approach as the WSDL model
 in that the DOM tree would be kept in memory in parallel to the EMF model,
 and the two kept in sync.
 </p>

 <p>
 Here is a snippet of code which will load a BPEL process from an IFile:
 </p>
 <pre>
 	// New resource set, or add to an existing one
 	ResourceSet resourceSet = new ResourceSetImpl();
 	// In non-workbench cases, find another way to create your URI
 	URI uri = URI.createPlatformResourceURI(file.getFullPath().toString());
 	// Use getResource(), not createResource()
 	Resource resource = resourceSet.getResource(uri, true);
 	// There's only one thing in the list
 	Process process = (Process)resource.getContents().get(0);
 </pre>
 <p>
 To save the process, call <i>resource.save()</i>.
 </p>

 <h2>Extensibility</h2>

 <p>
 BPEL is an extensible language. The specification builds upon the
 extensibility support in WSDL. Many BPEL elements are subtypes of
 <i>ExtensibleElement</i>. Such elements may contain attributes and
 elements which are not defined in the BPEL specification. The reader
 must therefore be extensible. When it encounters an unknown attribute
 or element (an <i>ExtensibilityElement</i>), it should query an appropriate
 deserializer to reconstitute the EMF model object. Likewise, the
 writer should query an appropriate serializer to reconstitute the
 DOM element from the EMF model object.
 </p>

 <p>
 Extenders of the BPEL model should register a <i>BPELExtensionSerializer</i>
 and <i>BPELExtensionDeserializer</i> for each of their <i>ExtensibilityElements</i>.
 The <i>BPELExtensionRegistry</i> holds onto these registrations, and they may
 be made during the execution of your EMF Package�s init() method.
 If the reader or writer encounters an <i>ExtensibilityElement</i> for which
 a serializer or deserializer is not found in the registry, the default
 implementations <i>BPELUnknownExtensionSerializer</i> and
 <i>BPELUnknownExtensionDeserializer</i> will be used.
 </p>

 <h2>Support for non-Workbench scenarios</h2>

 <p>
 The BPEL Model, while based on EMF, is intended to be functional both in
 an Eclipse Workbench (either a full Workbench or headless scenario) and
 independently of an Eclipse Workbench. The latter scenario makes the
 model suitable to scenarios such as command-line validation, or use in a
 Java-based runtime which is not based on Eclipse.
 </p>

 <p>
 To facilitate the non-Workbench scenario, the plug-in class
 <i>org.eclipse.bpel.core.BPELPlugin</i> extends <i>EMFPlugin</i>.
 <i>EMFPlugin</i> is designed for exactly this scenario. Also see
 <i>org.eclipse.bpel.core.terms.BPELTerms</i>, which has special logic to handle
 both the Workbench and non-Workbench cases.
 </p>

 <p>
 Committers must ensure that they do not introduce any code which relies
 on the Workbench running. <i>Platform.isRunning()</i> is a safe test that can
 be performed to determine whether or not the Workbench is running.
 </p>

 <h2>Dependencies</h2>

 <p>
 <i>org.eclipse.xsd</i> is the Eclipse XSD model, referenced by BPEL Variables
 and other locations.
 </p>
 <p>
 <i>org.eclipse.wst.wsdl</i> and <i>org.wsdl4j</i> are the WSDL model, referenced
 in a number of places from BPEL.
 </p>
 <p>
 <i>org.eclipse.emf.*</i> is the EMF runtime.
 </p>
 <p>
 <i>org.apache.xerces</i> is the Xerces parser from Apache. The BPEL reader and
 writer use this to turn the XML into model elements and vice versa.
 </p>
 <p>
 <i>org.eclipse.core.runtime</i> is used by all plug-ins in an Eclipse environment.
 </p>
 <p>
 <i>org.eclipse.core.resources</i> is used only in <i>BPELPlugin</i>. In general,
 the model should not use IResources or any other functionality from
 this plug-in due to the required support for non-Workbench scenarios.
 </p>

 <h2>Proxies</h2>

 <p>
 EMF supports object references in such a way that it is not necessary to
 load all referenced files up front. To this end, a particular EMF object
 may be a Proxy, which is resolved when a getter method returns a
 particular object.
 </p>
 <p>
 As an example, consider a BPEL Variable, which references an XSD type
 (as represented by <i>org.eclipse.xsd.XSDTypeDefinition</i>). The Variable
 API <i>getType()</i> is used to access this type. However, until <i>getType()</i>
 is called, the referenced XSD file is not loaded, and the
 <i>XSDTypeDefinition</i> is only a proxy. The auto-generated logic in <i>getType()</i>
 causes the proxy to be resolved, causing the XSD file to be loaded
 and the proxy replaced with a real <i>XSDTypeDefinition</i>, which is
 returned to the caller.
 </p>
 <p>
 In package <i>org.eclipse.bpel.model.proxy</i>, find proxy classes for all
 referenced object types. These proxies each have a unique URI encoding
 which contains all of the information necessary to resolve the proxy.
 </p>
 <p>
 Notice also that there are proxy classes for object references within
 the BPEL file, for references such as Variables. When deserializing a
 BPEL file, when the reader encounters a variable reference (in a Receive,
 for example), it should create a <i>VariableProxy</i> to put in the Receive.
 This proxy would be resolved to the appropriate Variable when
 <i>getVariable()</i> is called. However, it doesn�t work like that today.
 Instead, <i>Process.getPostLoadRunnables()</i> provides access to a list of
 runnables which are executed after the first reading pass.
 Today, classes such as <i>VariableProxy</i> are only used when the post-load
 runnable fails to find a particular referenced object.
 </p>

 <h2>Extensibility Points</h2>

 <ul class="midlist">
 <li>
 Registration of serializers and deserializers for extensibility elements
 may be registered with the <i>BPELExtensionRegistry</i>. This registration
 should be made in the package <i>init()</i> method of the plugin containing
 your serializer and deserializer, and these classes must implement
 <i>BPELExtensionSerializer</i> and <i>BPELExtensionDeserializer</i>, respectively.
 </li>
 <li>
 BPEL provides for an extensible ServiceReference scheme, in the same
 way as it allows language extensibility for expressions and queries.
 To serialize and deserialize the service references, implement
 <i>ServiceReferenceDeserializer</i> and <i>ServiceReferenceSerializer</i>, and
 make your registrations in your package <i>init()</i> method, calling
 <i>BPELExtensionRegistry.registryServiceReference[De]serializer()</i>.
 </li>
 <li>
 Depending on how one defines a schema for extensibility elements,
 order of elements and attributes may be important. To do this,
 register in the plug-in extension point
 <i>org.eclipse.bpel.model.extensions_reordering</i>, and provide a class which
 implements <i>IExtensibilityElementListHandler</i>. This class will be called
 upon serialization and you will be given the opportunity to rearrange
 the list of extensibility elements for a given BPEL element. Note that
 this currently only works in a Workbench environment, as it relies on
 the plug-in extension point.
 </li>
 </ul>

 <h2>Tolerance for incomplete files</h2>
 <p>
 The BPEL model, generally speaking, is tolerant of BPEL files which are
 incomplete (and hence, technically, syntactically invalid), as long as
 they are well-formed XML and have a process at the document root. This
 is necessary because, from an editing point of view, it is clearly
 unreasonable to force the user to specify all mandatory attributes
 and elements before saving for the first time � it is an iterative
 process. The model must then save and load this incomplete file, even
 though it may not pass syntactic validation.
 </p>

 <h2>Making Changes to the Model</h2>
 <p>
 The model classes are generated from the EMF Ecore models located in
 the org.eclipse.bpel.model/src/model folder.
 </p>
 <p>
 To set your workspace up to regenerate the model, you need to do the following:
 <ol>
 <li>Have org.eclipse.bpel.model in loaded in your workspace from CVS</li>
 <li>File-&gt;Import-&gt;External Plug-ins and Fragments. Select org.eclipse.xsd, org.eclipse.emf.ecore and org.eclipse.wst.wsdl and import them into your workspace. These plug-ins need to be in the workspace so their ecore and genmodel files can be loacted by EMF.</li>
 </ol>
 </p>
 <p>
 If you double-click on one of the ecore files (such as bpel.ecore),
 you can add or remove model objects or properties. After making changes,
 save the ecore file and close it. Double-click to open the corresponding
 genmodel file. Right-click on the root node in the editor, and Generate
 Model Code. EMF will generate all of the necessary Java code.
 </p>
 <p>
 Please note that any methods in the model objects which do not contain
 the @generated javadoc tag will be left alone. (As a convention, we
 usually mark hand-modified methods with @customized for clarity).
 </p>
 <p>
 After doing this, please open the class CorrelationPattern and replace
 <pre>
 	public static final CorrelationPattern OUTIN_LITERAL = new CorrelationPattern(OUTIN, "outin");
 </pre>
 with
 <pre>
 	public static final CorrelationPattern OUTIN_LITERAL = new CorrelationPattern(OUTIN, "out-in");
 </pre>
 </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 Model";
	$pageKeywords = "BPEL, model";
	$pageAuthor = "BPEL Team";

	# Add page-specific Nav bars here
	# Format is Link text, link URL (can be http://www.someothersite.com/), target (_self, _blank), level (1, 2 or 3)
	include($_SERVER['DOCUMENT_ROOT'] . "/$projectShortName/items/developers_menu.php");

	# End: page-specific settings
	#

	# Paste your HTML content between the EOHTML markers!
	$html = <<<EOHTML


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

	Last modified on December 7, 2005

	<p>
	This document attempts to explain many of the design decisions present in
	the BPEL model, as well as where to locate key code and how to make changes.
	</p>

	<h2>Spec Level</h2>

	<p>
	The model will track the evolving OASIS WS-BPEL specification as it
	approaches 2.0. Current support of the model is at the 1.1 level plus the
	following resolved OASIS issues:
	</p>
	<ul class="midlist">
	<li>Issue 13 (Expressions and Queries in Elements instead of Attributes)</li>
	<li>Issue 34 (No Dependency on WS-A)</li>
	<li>Issue 37 and 202 (Add "join" value to initiate attribute of Correlation)</li>
	<li>Issue 68 (Catch syntax broken)</li>
	</ul>

	<h2>Model Objects</h2>

	<p>
	Most of the BPEL model objects, with some exceptions, are located in the
	<i>org.eclipse.bpel.model</i> package.
	</p>

	<p>
	Message properties and property aliases are located in
	<i>org.eclipse.bpel.model.messageproperties</i>.
	</p>

	<p>
	Partner link types and roles are located in
	<i>org.eclipse.bpel.model.partnerlinktype.</i>
	</p>

	<h2>Reading and Writing BPEL Files</h2>

	<p>
	Most of the conversion from the .bpel file into an EMF model occurs in
	<i>org.eclipse.bpel.core.resources.BPELReader</i>. This class is instantiated
	by <i>BPELResourceImpl</i>, which in turn is created by <i>BPELResourceFactoryImpl</i>,
	which is registered in the plugin.xml file as the extension parser for
	.bpel files.
	</p>

	<p>
	<i>BPELReader</i> has methods for translating each of the BPEL elements and
	attributes from DOM objects into EMF objects. At the moment, the DOM
	objects are discarded by the reader once the EMF objects are created,
	and they are recreated by the <i>BPELWriter</i>. However, this has the
	disadvantage of losing any user formatting and comments in the source
	file upon save. The model should use the same approach as the WSDL model
	in that the DOM tree would be kept in memory in parallel to the EMF model,
	and the two kept in sync.
	</p>

	<p>
	Here is a snippet of code which will load a BPEL process from an IFile:
	</p>
	<pre>
	// New resource set, or add to an existing one
	ResourceSet resourceSet = new ResourceSetImpl();
	// In non-workbench cases, find another way to create your URI
	URI uri = URI.createPlatformResourceURI(file.getFullPath().toString());
	// Use getResource(), not createResource()
	Resource resource = resourceSet.getResource(uri, true);
	// There's only one thing in the list
	Process process = (Process)resource.getContents().get(0);
	</pre>
	<p>
	To save the process, call <i>resource.save()</i>.
	</p>

	<h2>Extensibility</h2>

	<p>
	BPEL is an extensible language. The specification builds upon the
	extensibility support in WSDL. Many BPEL elements are subtypes of
	<i>ExtensibleElement</i>. Such elements may contain attributes and
	elements which are not defined in the BPEL specification. The reader
	must therefore be extensible. When it encounters an unknown attribute
	or element (an <i>ExtensibilityElement</i>), it should query an appropriate
	deserializer to reconstitute the EMF model object. Likewise, the
	writer should query an appropriate serializer to reconstitute the
	DOM element from the EMF model object.
	</p>

	<p>
	Extenders of the BPEL model should register a <i>BPELExtensionSerializer</i>
	and <i>BPELExtensionDeserializer</i> for each of their <i>ExtensibilityElements</i>.
	The <i>BPELExtensionRegistry</i> holds onto these registrations, and they may
	be made during the execution of your EMF Package�s init() method.
	If the reader or writer encounters an <i>ExtensibilityElement</i> for which
	a serializer or deserializer is not found in the registry, the default
	implementations <i>BPELUnknownExtensionSerializer</i> and
	<i>BPELUnknownExtensionDeserializer</i> will be used.
	</p>

	<h2>Support for non-Workbench scenarios</h2>

	<p>
	The BPEL Model, while based on EMF, is intended to be functional both in
	an Eclipse Workbench (either a full Workbench or headless scenario) and
	independently of an Eclipse Workbench. The latter scenario makes the
	model suitable to scenarios such as command-line validation, or use in a
	Java-based runtime which is not based on Eclipse.
	</p>

	<p>
	To facilitate the non-Workbench scenario, the plug-in class
	<i>org.eclipse.bpel.core.BPELPlugin</i> extends <i>EMFPlugin</i>.
	<i>EMFPlugin</i> is designed for exactly this scenario. Also see
	<i>org.eclipse.bpel.core.terms.BPELTerms</i>, which has special logic to handle
	both the Workbench and non-Workbench cases.
	</p>

	<p>
	Committers must ensure that they do not introduce any code which relies
	on the Workbench running. <i>Platform.isRunning()</i> is a safe test that can
	be performed to determine whether or not the Workbench is running.
	</p>

	<h2>Dependencies</h2>

	<p>
	<i>org.eclipse.xsd</i> is the Eclipse XSD model, referenced by BPEL Variables
	and other locations.
	</p>
	<p>
	<i>org.eclipse.wst.wsdl</i> and <i>org.wsdl4j</i> are the WSDL model, referenced
	in a number of places from BPEL.
	</p>
	<p>
	<i>org.eclipse.emf.*</i> is the EMF runtime.
	</p>
	<p>
	<i>org.apache.xerces</i> is the Xerces parser from Apache. The BPEL reader and
	writer use this to turn the XML into model elements and vice versa.
	</p>
	<p>
	<i>org.eclipse.core.runtime</i> is used by all plug-ins in an Eclipse environment.
	</p>
	<p>
	<i>org.eclipse.core.resources</i> is used only in <i>BPELPlugin</i>. In general,
	the model should not use IResources or any other functionality from
	this plug-in due to the required support for non-Workbench scenarios.
	</p>

	<h2>Proxies</h2>

	<p>
	EMF supports object references in such a way that it is not necessary to
	load all referenced files up front. To this end, a particular EMF object
	may be a Proxy, which is resolved when a getter method returns a
	particular object.
	</p>
	<p>
	As an example, consider a BPEL Variable, which references an XSD type
	(as represented by <i>org.eclipse.xsd.XSDTypeDefinition</i>). The Variable
	API <i>getType()</i> is used to access this type. However, until <i>getType()</i>
	is called, the referenced XSD file is not loaded, and the
	<i>XSDTypeDefinition</i> is only a proxy. The auto-generated logic in <i>getType()</i>
	causes the proxy to be resolved, causing the XSD file to be loaded
	and the proxy replaced with a real <i>XSDTypeDefinition</i>, which is
	returned to the caller.
	</p>
	<p>
	In package <i>org.eclipse.bpel.model.proxy</i>, find proxy classes for all
	referenced object types. These proxies each have a unique URI encoding
	which contains all of the information necessary to resolve the proxy.
	</p>
	<p>
	Notice also that there are proxy classes for object references within
	the BPEL file, for references such as Variables. When deserializing a
	BPEL file, when the reader encounters a variable reference (in a Receive,
	for example), it should create a <i>VariableProxy</i> to put in the Receive.
	This proxy would be resolved to the appropriate Variable when
	<i>getVariable()</i> is called. However, it doesn�t work like that today.
	Instead, <i>Process.getPostLoadRunnables()</i> provides access to a list of
	runnables which are executed after the first reading pass.
	Today, classes such as <i>VariableProxy</i> are only used when the post-load
	runnable fails to find a particular referenced object.
	</p>

	<h2>Extensibility Points</h2>

	<ul class="midlist">
	<li>
	Registration of serializers and deserializers for extensibility elements
	may be registered with the <i>BPELExtensionRegistry</i>. This registration
	should be made in the package <i>init()</i> method of the plugin containing
	your serializer and deserializer, and these classes must implement
	<i>BPELExtensionSerializer</i> and <i>BPELExtensionDeserializer</i>, respectively.
	</li>
	<li>
	BPEL provides for an extensible ServiceReference scheme, in the same
	way as it allows language extensibility for expressions and queries.
	To serialize and deserialize the service references, implement
	<i>ServiceReferenceDeserializer</i> and <i>ServiceReferenceSerializer</i>, and
	make your registrations in your package <i>init()</i> method, calling
	<i>BPELExtensionRegistry.registryServiceReference[De]serializer()</i>.
	</li>
	<li>
	Depending on how one defines a schema for extensibility elements,
	order of elements and attributes may be important. To do this,
	register in the plug-in extension point
	<i>org.eclipse.bpel.model.extensions_reordering</i>, and provide a class which
	implements <i>IExtensibilityElementListHandler</i>. This class will be called
	upon serialization and you will be given the opportunity to rearrange
	the list of extensibility elements for a given BPEL element. Note that
	this currently only works in a Workbench environment, as it relies on
	the plug-in extension point.
	</li>
	</ul>

	<h2>Tolerance for incomplete files</h2>
	<p>
	The BPEL model, generally speaking, is tolerant of BPEL files which are
	incomplete (and hence, technically, syntactically invalid), as long as
	they are well-formed XML and have a process at the document root. This
	is necessary because, from an editing point of view, it is clearly
	unreasonable to force the user to specify all mandatory attributes
	and elements before saving for the first time � it is an iterative
	process. The model must then save and load this incomplete file, even
	though it may not pass syntactic validation.
	</p>

	<h2>Making Changes to the Model</h2>
	<p>
	The model classes are generated from the EMF Ecore models located in
	the org.eclipse.bpel.model/src/model folder.
	</p>
	<p>
	To set your workspace up to regenerate the model, you need to do the following:
	<ol>
	<li>Have org.eclipse.bpel.model in loaded in your workspace from CVS</li>
	<li>File->Import->External Plug-ins and Fragments. Select org.eclipse.xsd, org.eclipse.emf.ecore and org.eclipse.wst.wsdl and import them into your workspace. These plug-ins need to be in the workspace so their ecore and genmodel files can be loacted by EMF.</li>
	</ol>
	</p>
	<p>
	If you double-click on one of the ecore files (such as bpel.ecore),
	you can add or remove model objects or properties. After making changes,
	save the ecore file and close it. Double-click to open the corresponding
	genmodel file. Right-click on the root node in the editor, and Generate
	Model Code. EMF will generate all of the necessary Java code.
	</p>
	<p>
	Please note that any methods in the model objects which do not contain
	the @generated javadoc tag will be left alone. (As a convention, we
	usually mark hand-modified methods with @customized for clarity).
	</p>
	<p>
	After doing this, please open the class CorrelationPattern and replace
	<pre>
	public static final CorrelationPattern OUTIN_LITERAL = new CorrelationPattern(OUTIN, "outin");
	</pre>
	with
	<pre>
	public static final CorrelationPattern OUTIN_LITERAL = new CorrelationPattern(OUTIN, "out-in");
	</pre>
	</p>

	</div>

	$rightcolumn_links
	</div>

	EOHTML;


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