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