You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ode.apache.org by va...@apache.org on 2012/12/28 14:13:33 UTC
svn commit: r1426497 [1/2] - in /ode/site/trunk: content/
content/extensions/ content/userguide/ templates/
Author: vanto
Date: Fri Dec 28 13:13:31 2012
New Revision: 1426497
URL: http://svn.apache.org/viewvc?rev=1426497&view=rev
Log:
restructuring.
Added:
ode/site/trunk/content/extensions/
ode/site/trunk/content/extensions/external-variables.mdtext
ode/site/trunk/content/extensions/flexible-assigns.mdtext
ode/site/trunk/content/extensions/headers-handling.mdtext
ode/site/trunk/content/extensions/implicit-correlations.mdtext
ode/site/trunk/content/extensions/index.mdtext
ode/site/trunk/content/extensions/iterable-foreach.mdtext
ode/site/trunk/content/extensions/process-contexts.mdtext
ode/site/trunk/content/extensions/restful-bpel-part-i.mdtext
ode/site/trunk/content/extensions/restful-bpel-part-ii.mdtext
ode/site/trunk/content/extensions/wsdl-11-extensions-for-rest.mdtext
ode/site/trunk/content/extensions/xpath-extensions.mdtext
ode/site/trunk/content/extensions/xquery-extensions.mdtext
ode/site/trunk/content/userguide/activity-failure-and-recovery.mdtext
ode/site/trunk/content/userguide/creating-a-process.mdtext
ode/site/trunk/content/userguide/direct-process-to-process-communication.mdtext
ode/site/trunk/content/userguide/endpoint-references.mdtext
ode/site/trunk/content/userguide/instance-data-cleanup.mdtext
ode/site/trunk/content/userguide/instance-replayer.mdtext
ode/site/trunk/content/userguide/management-api.mdtext
ode/site/trunk/content/userguide/ode-execution-events.mdtext
ode/site/trunk/content/userguide/process-versioning.mdtext
ode/site/trunk/content/userguide/wsdl-11-http-binding-support.mdtext
Removed:
ode/site/trunk/content/activity-failure-and-recovery.mdtext
ode/site/trunk/content/bpel-extensions.mdtext
ode/site/trunk/content/creating-a-process.mdtext
ode/site/trunk/content/direct-process-to-process-communication.mdtext
ode/site/trunk/content/endpoint-references.mdtext
ode/site/trunk/content/external-variables.mdtext
ode/site/trunk/content/flexible-assigns.mdtext
ode/site/trunk/content/headers-handling.mdtext
ode/site/trunk/content/implicit-correlations.mdtext
ode/site/trunk/content/instance-data-cleanup.mdtext
ode/site/trunk/content/instance-replayer.mdtext
ode/site/trunk/content/iterable-foreach.mdtext
ode/site/trunk/content/management-api.mdtext
ode/site/trunk/content/ode-execution-events.mdtext
ode/site/trunk/content/process-contexts.mdtext
ode/site/trunk/content/process-versioning.mdtext
ode/site/trunk/content/restful-bpel-part-i.mdtext
ode/site/trunk/content/restful-bpel-part-ii.mdtext
ode/site/trunk/content/wsdl-11-extensions-for-rest.mdtext
ode/site/trunk/content/wsdl-11-http-binding-support.mdtext
ode/site/trunk/content/xpath-extensions.mdtext
ode/site/trunk/content/xquery-extensions.mdtext
Modified:
ode/site/trunk/content/ambiguousreceive.mdtext
ode/site/trunk/content/bpel-management-api-specification.mdtext
ode/site/trunk/content/bpelc-command.mdtext
ode/site/trunk/content/index.mdtext
ode/site/trunk/content/userguide/index.mdtext
ode/site/trunk/content/ws-bpel-20-specification-compliance.mdtext
ode/site/trunk/content/ws-bpel-20.mdtext
ode/site/trunk/templates/skeleton.html
Modified: ode/site/trunk/content/ambiguousreceive.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/ambiguousreceive.mdtext?rev=1426497&r1=1426496&r2=1426497&view=diff
==============================================================================
--- ode/site/trunk/content/ambiguousreceive.mdtext (original)
+++ ode/site/trunk/content/ambiguousreceive.mdtext Fri Dec 28 13:13:31 2012
@@ -13,7 +13,7 @@ This fault is thrown when two (or more)
<a name="ambiguousReceive-{anchor:examples}Examples"></a>
### {anchor:examples} Examples
-The following BPEL (based on the example types in the [WS-BPEL 2.0](ws-bpel-2.0.html) specification) would generate the fault in the `<receive>`, and `<pick>` activities as soon as a matching message was received :
+The following BPEL (based on the example types in the [WS-BPEL 2.0](ws-bpel-20.html) specification) would generate the fault in the `<receive>`, and `<pick>` activities as soon as a matching message was received :
<correlationSets>
Modified: ode/site/trunk/content/bpel-management-api-specification.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/bpel-management-api-specification.mdtext?rev=1426497&r1=1426496&r2=1426497&view=diff
==============================================================================
--- ode/site/trunk/content/bpel-management-api-specification.mdtext (original)
+++ ode/site/trunk/content/bpel-management-api-specification.mdtext Fri Dec 28 13:13:31 2012
@@ -161,7 +161,7 @@ The _name_ and _namespace_ attributes re
An implementation must return a _name_ and _namespace_ attribute for every BPEL, WSDL and XSD documents that specify a name and/or namespace for their target definitions.
-The _type_ attribute uses a URI to identify the document type. For BPEL, WSDL and XSD, this attribute uses the namespace URI of the relevant specification, e.g. [...WSDL namespace...](...wsdl-namespace....html) for a WSDL 1.1 document.
+The _type_ attribute uses a URI to identify the document type. For BPEL, WSDL and XSD, this attribute uses the namespace URI of the relevant specification, e.g. (TODO: WSDL 1.1 namespace) for a WSDL 1.1 document.
The _src_ attribute provides a URL that can be used to access the definition.
Modified: ode/site/trunk/content/bpelc-command.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/bpelc-command.mdtext?rev=1426497&r1=1426496&r2=1426497&view=diff
==============================================================================
--- ode/site/trunk/content/bpelc-command.mdtext (original)
+++ ode/site/trunk/content/bpelc-command.mdtext Fri Dec 28 13:13:31 2012
@@ -3,7 +3,8 @@ The `bpelc` commandline tool {excerpt}co
<a name="bpelcCommand-Synopsis"></a>
## Synopsis
-bpelc [-q](-v|-vv.html) [-o directory] [-rr rrfile] [-wsdl uri] url ... url
+
+ bpelc [-q](-v|-vv.html) [-o directory] [-rr rrfile] [-wsdl uri] url ... url
<a name="bpelcCommand-Description"></a>
## Description
Added: ode/site/trunk/content/extensions/external-variables.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/external-variables.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/external-variables.mdtext (added)
+++ ode/site/trunk/content/extensions/external-variables.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,71 @@
+Title: External Variables
+<a name="ExternalVariables-ExternalVariables"></a>
+## External Variables
+
+ * [Declaring External Variables in the Process Definition](#ExternalVariables-DeclaringExternalVariablesintheProcessDefinition)
+ * [Incomplete Keys](#ExternalVariables-IncompleteKeys)
+ * [JDBC Mapping](#ExternalVariables-JDBCMapping)
+ * [REST Mapping](#ExternalVariables-RESTMapping)
+
+<a name="ExternalVariables-DeclaringExternalVariablesintheProcessDefinition"></a>
+### Declaring External Variables in the Process Definition
+
+<div class="alert alert-warning">
+ External variables are only available on ODE 1.2+
+</div>
+
+Syntax:
+
+ <scope>
+ <variables xmlns:xvar=" http://ode.apache.org/externalVariables">
+ <variable name="ext-var-name" element="ext-var-type" xvar:id="ext-var-id">
+ <xvar:key-map key="key-id">*
+ <expression>key-expression</expression>
+ </xvar:key-map>
+ </variable>
+ </variables>
+ </scope>
+
+
+External variables are declared in the `<variables>` section of the `<scope>` element, just like normal variables. However, unlike regular variables, external variables must specify the additional `xvar:id` attribute. This attribute identifies the variable as an external variable and links the external variable's declaration to the external variable's configuration in the deployment descriptor.
+
+In addition to this attribute, an external variable may also define a set of key mappings by nesting `xvar:key-map` elements within the declaration. The key mappings are a collection of name-expression pairs that is used to create a composite key (identity) for the external variable. This composite key is used to retrieve the correct "instance" of the variable from the underlying storage. The key mappings are BPEL expressions ( i.e. XPath expressions) that are evaluated once, at the time that the scope is instantiated. Therefore, the "identity" of an external variable is determined during scope creation, and cannot be changed by the process (for qualifications see Incomplete Keys below).
+
+Finally, any external variables must be of an "element" type, with a schema conforming to the requirements of the underlying storage mechanism.
+
+Consider the following example:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>process.bpel</B></DIV><DIV class="codeContent panelContent">
+ .
+ .
+ .
+ <scope>
+ <variables>
+ <variable name="customer" element="myns:CustomerElement" xvar:id="customer1" >
+ <xvar:key-map key="customer-id">
+ <expression>$order/customerid</expression>
+ </xvar:key-map>
+ </variables>
+ </scope>
+ .
+ .
+ .
+
+
+
+In the above, the "customer" variable is an external variable. The key for the external variable is derived from the value of the `customerid` element in the "order" variable. Note that the "order" variable must be declared in a scope above the scope declaring the "customer" external variable, otherwise it would not be possible to resolve the identify of the "customer" variable. In this scenario, the external variable can be "read" even if it was never assigned to in the process.
+
+<a name="ExternalVariables-IncompleteKeys"></a>
+### Incomplete Keys
+
+It is not required that the full identity of the external variable be resolved at scope creation. For example, an external variable may correspond to a database row where the identity is generated by the database during an insert operation. In such a scenario the key mapping can be omitted, and the identity of the external variable will be unknown until the variable is assigned to. Any attempt to access the variable before the first assignment will result in an uninitialized variable fault. In general it is possible to specify external variables where some portions of the identity are determined using the key mappings and some using some other (implementation-specific) mechanism. In any case, if when the variable is read, the key is incomplete an uninitialized variable fault will result.
+
+<a name="ExternalVariables-JDBCMapping"></a>
+### JDBC Mapping
+
+[External Variables - JDBC Mapping](external-variables---jdbc-mapping.html)
+
+<a name="ExternalVariables-RESTMapping"></a>
+### REST Mapping
+
+[External Variables - REST Mapping](external-variables---rest-mapping.html)
Added: ode/site/trunk/content/extensions/flexible-assigns.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/flexible-assigns.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/flexible-assigns.mdtext (added)
+++ ode/site/trunk/content/extensions/flexible-assigns.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,52 @@
+Title: Flexible Assigns
+<a name="FlexibleAssigns-AutoCompleteCopyDestination(L-Value)"></a>
+## Auto Complete Copy Destination (L-Value)
+
+A lot of times, users expect the <copy> operation in a WS-BPEL assign activity to behave such that the path specified by the destination ("to-spec") is automatically created, if it doesn't already exist. By default, if the to-spec used within a <copy> operation does not select exactly one XML information item during execution, then the standard fault bpel:selectionFailure is thrown (as mandated by the spec).
+
+To override this default behavior, we introduce a insertMissingToData attribute in the <copy> operation, which if it is set to "yes", will instruct the runtime to complete the (XPath) L-value specified by the to-spec, if no items were selected. For the sake of simplicity, we will complete the to-spec if and only if:
+1. It's a path expression whose steps are separated by "/", and
+1. Its steps have an axis, which is either "child" or "attribute", and
+1. Its steps have no following predicates, and
+1. Its steps test the name of a node, without the use of wildcards.
+
+Formally, the grammar of the to-spec, for which auto-complete is enabled, may be defined in terms of these productions:
+
+ PathExpr ::= ("/" RelativePathExpr?) | RelativePathExpr
+ RelativePathExpr ::= ForwardStep (("/" ) ForwardStep)*
+ ForwardStep ::= (ForwardAxis QName) | AbbrevForwardStep
+ AbbrevForwardStep ::= "@"? QName
+ ForwardAxis ::= ("child" "::") | ("attribute" "::")
+
+
+The example below illustrates the use of the insertMissingToData attribute. Let's say that the variable "response" is uninitialized. In that case, the first <copy> operation will fail, whereas the second one will succeed.
+
+
+
+ <copy>
+ <from>$request.requestMessageData/typeIndicators/types:indicatorTwo</from>
+ <to>$response/typeIndicators/types:indicatorTwo</to>
+ </copy>
+
+ <copy insertMissingToData="yes">
+ <from>$request.requestMessageData/typeIndicators/types:indicatorTwo</from>
+ <to>$response/typeIndicators/child::types:indicatorTwo</to>
+ </copy>
+
+
+<a name="FlexibleAssigns-AddsupportfortheignoreMissingFromDataattributein<copy>"></a>
+## Add support for the ignoreMissingFromData attribute in <copy>
+
+The attached patch adds support for the following attributes in the BPEL assign activity's copy operation:
+
+1. The optional @ignoreMissingFromData attribute, which if it has the value of "yes", and the from-spec returns zero XML information items, then no bpel:selectionFailure is thrown, and the to-spec is not evaluated.
+
+1. An extension @ignoreUninitializedFromVariable attribute, which if it has the value of "yes", and the from-spec contains an uninitialized variable, then no bpel:uninitializedVariable is thrown, and the to-spec is not evaluated.
+
+The informal syntax of the above attributes is shown below:
+
+
+ <copy ignoreMissingFromData="yes|no"? ignoreUninitializedFromVariable="yes|no"?>
+ from-spec to-spec
+ </copy>
+
Added: ode/site/trunk/content/extensions/headers-handling.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/headers-handling.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/headers-handling.mdtext (added)
+++ ode/site/trunk/content/extensions/headers-handling.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,41 @@
+Title: Headers Handling
+There are several situations where one would want to access headers form the wire format in their BPEL process. It could be to assign them to another message and pass them around or to execute some business logic that's header-dependent (often a bad idea but sometimes there's no choice). ODE supports the manipulation of wire format headers in two different ways.
+
+<a name="HeadersHandling-HeadersasAbstractMessageParts"></a>
+### Headers as Abstract Message Parts
+
+In SOAP, message parts can be bound to a SOAP header. This requires to define all the parts that you want to extract in the abstract message definition and then create an appropriate binding to specify the parts that actually go in the header.
+
+Once this is done, the header part is actually physically present in the abstract message definition and can be accessed like any other message part in your process. Headers can therefore be assigned using the classic from/part and to/part assignments, no specific extension is needed.
+
+<a name="HeadersHandling-DynamicHeaders"></a>
+### Dynamic Headers
+
+When headers aren't declared in the WSDL abstract message (or even in the binding), ODE still checks which headers are present in the exchanged SOAP messages and retrieve them. Those are dynamic headers, there's no validation as to which headers are present or absent, ODE just takes what's there.
+
+Those headers can't be manipulated and assigned directly like a normal part as they don't have a part definition. So ODE supports a specific and additional type of <from> and <to> for assignments:
+
+
+ <from variable="BPELVariableName" header="NCName"?>
+ <query queryLanguage="anyURI"?>?
+ queryContent
+ </query>
+ </from>
+
+ <to variable="BPELVariableName" header="NCName"?>
+ <query queryLanguage="anyURI"?>?
+ queryContent
+ </query>
+ </to>
+
+
+Using these <from> and <to> specifications, dynamic headers can be accessed and manipulated in your BPEL process. For example, passing a ConversationId SOAP header from an incoming to an outgoing message could look like:
+
+
+ <copy>
+ <from variable="inputMsg" header="ConversationId"/>
+ <to variable="outputMsg" header="ConversationId"/>
+ </copy>
+
+
+Note that SOAP headers being *always* elements, a simple type (like a string) can't be used to assign to a header.
Added: ode/site/trunk/content/extensions/implicit-correlations.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/implicit-correlations.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/implicit-correlations.mdtext (added)
+++ ode/site/trunk/content/extensions/implicit-correlations.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,55 @@
+Title: Implicit Correlations
+ * [Introduction](#ImplicitCorrelations-Introduction)
+ * [Process to Process Interaction Use Case](#ImplicitCorrelations-ProcesstoProcessInteractionUseCase)
+ * [Process to Service Interaction Use Case](#ImplicitCorrelations-ProcesstoServiceInteractionUseCase)
+
+<a name="ImplicitCorrelations-Introduction"></a>
+### Introduction
+
+BPEL process instances are stateful --- therefore, a client interacting with the BPEL engine must identify the particular instance with which it intends to interact in all of its communications. The BPEL specification defines a mechanism --- _correlation_ --- which allows the process designer to specify which parts of an incoming message (i.e. a message going from a client to the BPEL server) should be used to identify the target process instance. Correlation is a powerful mechanism --- however it is a bit complicated and relies on "in-band" message data to associate a messages with a process instance.
+
+To keep simple cases simple, ODE provides an alternative correlation mechanism --- _implicit correlation_ --- that automatically handles correlation through "out-of-band" session identifiers. The mechanism is simple: a unique session identifier is associated with every every partner link instance. When a message is sent on a partner link, the session identifier is sent along with the message. The recipient is then able to use the received session identifier in subsequent communications with the process instance. Messages received by the BPEL engine that have a session identifier are routed to the correct instance (and partner link) by that session identifer.
+
+There are two major use cases for the implicit correlation mechanism requiring different levels of familiarity with the mechanism's details: process to process and process to service interactions. The former case deals with situations where the ODE BPEL process instance is communicating with another ODE process instance. The latter deals with situations where a ODE BPEL process instance is communicating with an external (non-ODE) service.
+
+<a name="ImplicitCorrelations-ProcesstoProcessInteractionUseCase"></a>
+### Process to Process Interaction Use Case
+
+When an ODE process needs to communicate with other ODE processes, using implicit correlations is quite simple. Simply omit the `<correlations>` element from the `<receive>`, `<pick>`, and `<invoke>` activities. The following is an example showing one process (processA) starting another (processB) and then being called back:
+
+* ProcessA
+
+ .
+ .
+ .
+ <invoke name="initiate" partnerLink="responderPartnerLink" portType="test:MSResponderPortType"
+ operation="initiate" inputVariable="dummy"/>
+ <receive name="callback" partnerLink="responderPartnerLink"
+ portType="test:MSMainPortType" operation="callback" variable="dummy"/>
+ .
+ .
+ .
+
+
+* ProcessB
+
+ .
+ .
+ .
+ <receive name="start" partnerLink="mainPartnerLink" variable="dummy"
+ portType="resp:MSResponderPortType" operation="initiate" createInstance="yes"/>
+ <invoke name="callback" partnerLink="mainPartnerLink"
+ portType="resp:MSMainPortType" operation="callback" inputVariable="dummy"/>
+ .
+ .
+ .
+
+
+In the above example, ODE will use the implicit correlation mechanism because no explicit correlations are specified. Communication between the two processes will reach the correct instance as long as the same partner link is used.
+
+For a complete example check [MagicSession](https://svn.apache.org/repos/asf/ode/trunk/distro/src/examples-war/MagicSession/).
+
+<a name="ImplicitCorrelations-ProcesstoServiceInteractionUseCase"></a>
+### Process to Service Interaction Use Case
+
+See the [Stateful Exchange Protocol](stateful-exchange-protocol.html).
Added: ode/site/trunk/content/extensions/index.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/index.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/index.mdtext (added)
+++ ode/site/trunk/content/extensions/index.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,100 @@
+Title: BPEL Extensions
+Category: documentation
+
+# Overview
+ODE extends the [WS-BPEL](ws-bpel-20.html) in areas that aren't covered by the spec. This page details these extensions.
+
+ * [Implicit Correlations](#BPELExtensions-ImplicitCorrelations)
+ * [Activity Failure and Recovery](#BPELExtensions-ActivityFailureandRecovery)
+ * [Extension Activities & Extensible Assign Operations](#BPELExtensions-ExtensionActivities-ExtensibleAssignOperations)
+ * [XPath Extensions](#BPELExtensions-XPathExtensions)
+ * [External Variables](#BPELExtensions-ExternalVariables)
+ * [Headers Handling](#BPELExtensions-HeadersHandling)
+ * [RESTful BPEL, Part I](#BPELExtensions-RESTfulBPEL-PartI)
+ * [RESTful BPEL, Part II](#BPELExtensions-RESTfulBPEL-PartII)
+ * [Iterable ForEach](#BPELExtensions-IterableForEach)
+ * [Flexible Assigns](#BPELExtensions-FlexibleAssigns)
+ * [Process Contexts](#BPELExtensions-ProcessContexts)
+
+<a name="BPELExtensions-ImplicitCorrelations"></a>
+## [Implicit Correlations](implicit-correlations.html)
+
+BPEL process instances are stateful â therefore, a client interacting with the BPEL engine must identify the particular instance with which it intends to interact in all of its communications. The BPEL specification defines a mechanism â *correlation* â which allows the process designer to specify which parts of an incoming message (i.e. a message going from a client to the BPEL server) should be used to identify the target process instance. Correlation is a powerful mechanism â however it is a bit complicated and relies on "in-band" message data to associate a messages with a process instance.
+
+To keep simple cases simple, ODE provides an alternative correlation mechanism â *implicit correlation* â that automatically handles correlation through "out-of-band" session identifiers. The mechanism is simple: a unique session identifier is associated with every every partner link instance. When a message is sent on a partner link, the session identifier is sent along with the message. The recipient is then able to use the received session identifier in subsequent communications with the process instance. Messages received by the BPEL engine that have a session identifier are routed to the correct instance (and partner link) by that session identifier.
+
+[Read more](implicit-correlations.html)
+
+<a name="BPELExtensions-ActivityFailureandRecovery"></a>
+## [Activity Failure and Recovery](activity-failure-and-recovery.html)
+
+There are several types of error conditions. In this document we introduce a class of error condition called *failures*, distinct from *faults*, and describe how failures are caught and handled by the process engine.
+
+For example, when the process is unable to perform DNS resolution to determine the service endpoint, it generates a failure. An administrator can fix the DNS server and tell the process engine to retry the activity. Had the DNS error been reported as a fault, the process would either terminate or require complex fault handling and recovery logic to proceed past this point of failure.
+
+In short, failures shields the process from common, non-terminal error conditions while retaining simple and straightforward process definitions that do not need to account for these error conditions.
+
+[Read more](activity-failure-and-recovery.html)
+
+<a name="BPELExtensions-ExtensionActivities-ExtensibleAssignOperations"></a>
+## [Extension Activities & Extensible Assign Operations](extension-activities-extensible-assign-operations.html)
+
+Apache ODE provides a plug-in architecture for custom activity implementations and custom variable assignment logic. Such plug-ins can be registered to ODE and can be used according to the WS-BPEL 2.0 extensibility mechnisms (`<extensionActivity>` & `<extensionAssignOperation>`).
+
+[Read more](extension-activities-extensible-assign-operations.html)
+
+<a name="BPELExtensions-XPathExtensions"></a>
+## [XPath Extensions](xpath-extensions.html)
+
+Apache ODE extends the default XPath coverage provided by the WS-BPEL specification mostly by adding support for [XPath 2.0](http://www.w3.org/TR/xpath20/) and by offering a few utility extension functions to make some assignments easier.
+
+[Read more](xpath-extensions.html)
+
+<a name="BPELExtensions-ExternalVariables"></a>
+## [External Variables](external-variables.html)
+
+External variables are an easy way to share data between the process and external systems, by treating those independent entities as BPEL variables that can be used in expressions and assignments. External variables may be records stored in the database, REST resources, etc.
+
+[Read more](external-variables.html)
+
+<a name="BPELExtensions-HeadersHandling"></a>
+## [Headers Handling](headers-handling.html)
+
+There are several situations where one would want to access headers form the wire format in their BPEL process. It could be to assign them to another message and pass them around or to execute some business logic that's header-dependent (often a bad idea but sometimes there's no choice). ODE supports the manipulation of wire format headers in two different ways.
+
+[Read more](headers-handling.html)
+
+<a name="BPELExtensions-RESTfulBPEL-PartI"></a>
+## [RESTful BPEL, Part I](restful-bpel-part-i.html)
+
+Extends the invoke activity to handle RESTful Web services. This extension uses BPEL variables of type xsd:uri and xsd:string instead of partner links, and does away with the WSDL indirection, making it straightforward to develop processes that use RESTful Web services.
+
+[Read more](restful-bpel-part-i.html)
+
+<a name="BPELExtensions-RESTfulBPEL-PartII"></a>
+## [RESTful BPEL, Part II](restful-bpel-part-ii.html)
+
+Extends receive and onEvent to expose RESTful resources that. This extension adds the ability to declare and instantiate resources, and specific handling for the HTTP methods GET, POST, PUT and DELETE.
+
+[Read more](restful-bpel-part-ii.html)
+
+<a name="BPELExtensions[IterableForEach"></a>
+## [Iterable ForEach](iterable-foreach.html)
+
+Extends the <forEach> activity so that the counter variable iterates over the items contained in a given sequence. This extension provides an alternative and more dynamic way of generating M branches, where M is the size of the binding sequence. The semantics of the <completionCondition> stays the same, in that the loop is deemed to be complete if B out of the M branches complete (successfully), where B is its actual value.
+
+[Read more](iterable-foreach.html)
+
+<a name="BPELExtensions-FlexibleAssigns"></a>
+## [Flexible Assigns](flexible-assigns.html)
+
+Extends the <assign> activity so that it can be made to either ignore or insert data that is missing in the to-spec of a copy operation. This shortcut allows users to handle what would normally be fault scenarios, in a more graceful and intuitive way.
+
+[Read more](flexible-assigns.html)
+
+<a name="BPELExtensions-ProcessContexts"></a>
+## [Process Contexts](process-contexts.html)
+
+Extends BPEL and ODE to allow the circulation of transport metadata (like security tokens, correlation keys, or tracing informations) from messages to processes and then from processes to messages.
+
+[Read more](process-contexts.html)
Added: ode/site/trunk/content/extensions/iterable-foreach.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/iterable-foreach.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/iterable-foreach.mdtext (added)
+++ ode/site/trunk/content/extensions/iterable-foreach.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,57 @@
+Title: Iterable ForEach
+This extension simplifies a common usage pattern in which forEach is used to iterate over a selected sequence of nodes.
+
+The common use case involves selecting a sequence of nodes, storing it in a scope variable, and using forEach to iterate over that sequence, using the current counter value to extract and operate on the indexed value from the sequence. This extension captures the pattern in a form that's easier to author and debug, by replacing counter with iterator and eliminating the use of temporary variables.
+
+
+<a name="IterableForEach-ProcessingMultipleBranches-ForEach"></a>
+## Processing Multiple Branches - ForEach
+
+The <forEach> activity will execute its contained <scope> activity exactly M times where M is the number of items in the <sequenceValue>.
+
+
+
+ <forEach rangeName="BPELVariableName" parallel="yes|no"
+ standard-attributes>
+ standard-elements
+ <sequenceValue expressionLanguage="anyURI"? instanceOf="sequenceType">
+ unsigned-integer-expression
+ </sequenceValue>
+ <completionCondition>?
+ <branches expressionLanguage="anyURI"?
+ successfulBranchesOnly="yes|no"?>?
+ unsigned-integer-expression
+ </branches>
+ </completionCondition>
+ <scope ...>...</scope>
+ </forEach>
+
+
+
+When the <forEach> activity is started, the expression in <sequenceValue> is evaluated. Once that value is returned it remains constant for the lifespan of the activity. [SA00074](sa00074.html) That expressions MUST return a sequence of items (meaning it comprises nodes, texts or atomic values), where ach item can be validated to be the type specified by the instanceOf attribute. If that expression does not return a valid sequence value, a bpel:invalidExpressionValue fault will be thrown (see section 8.3. Expressions). If the <sequenceValue> is empty, then the child <scope> activity MUST NOT be performed and the <forEach> activity is complete.
+
+The child activity of a <forEach> MUST be a <scope> activity. The <forEach> construct introduces an implicit range variable, and also introduces dynamic parallelism (i.e. having parallel branches of which number is not known ahead of time). The <scope> activity provides a well-defined scope snapshot semantic and a way to name the dynamic parallel work for compensation purposes (see scope snapshot description in section 12.4.2. Process State Usage in Compensation Handlers).
+
+If the value of the parallel attribute is no then the activity is a serial <forEach>. The enclosed <scope> activity MUST be executed M times, each instance starting only after the previous repetition is complete. If premature termination occurs such as due to a fault, or the completion condition evaluates to true, then this M requirement does not apply. During each repetition, a variable of type specified by the instanceOf attribute is implicitly declared in the <forEach> activity's child <scope>. This implicit variable has the name specified in the rangeVariableName attribute. The first iteration of the scope will see the range variable initialized to the first item in <sequenceValue>. The next iteration will cause the range variable to be initialized to the second item in <sequenceValue>. Each subsequent iteration will move the range variable to the next item in the sequence until the final iteration where the range will be set to the last item in <sequenceValue>. The rang
e variable is local to the enclosed <scope> and although its value can be changed during an iteration, that value will be lost at the end of each iteration. Therefore, the range variable value will not affect the value of the next iteration's range.
+
+If the value of the parallel attribute is yes then the activity is a parallel <forEach>. The enclosed <scope> activity MUST be concurrently executed M times. In essence an implicit <flow> is dynamically created with M copies of the <forEach>'s enclosed <scope> activity as children. Each copy of the <scope> activity will have the same range variable declared in the same manner as specified for serial <forEach>. Each instance's range variable MUST be uniquely initialized in parallel to one of the teim values starting with first and up to and including the last item in <sequenceValue>, as a part of <scope> instantiation.
+
+[SA00076](sa00076.html) If a variable of the same name as the value of the rangeName attribute is declared explicitly in the enclosed scope, it would be considered a case of duplicate variable declaration and MUST be reported as an error during static analysis.
+
+The <forEach> activity without a <completionCondition> completes when all of its child <scope>'s have completed. The <completionCondition> element is optionally specified to prevent some of the children from executing (in the serial case), or to force early termination of some of the children (in the parallel case).
+
+The <branches> element represents an unsigned-integer expression (see section 8.3.4. Unsigned Integer Expressions) used to define a completion condition of the "at least N out of M" form. The actual value B of the expression is calculated once, at the beginning of the <forEach> activity. It will not change as the result of the <forEach> activity's execution. At the end of execution of each directly enclosed <scope> activity, the number of completed children is compared to B, the value of the <branches> expression. If at least B children have completed, the <completionCondition> is triggered: No further children will be started, and currently running children will be terminated (see section 12.6 Termination Handlers). Note that enforcing the semantic of "exactly N out of M" in parallel <forEach> would involve a race condition, and is therefore not specified.
+
+When the completion condition B is calculated, if its value is larger than the number of directly enclosed activities M, then the standard bpel:invalidBranchCondition fault MUST be thrown. [SA00075](sa00075.html) Both B and M may be constant expressions, and in such cases, static analysis SHOULD reject processes where it can be detected that B is greater than M.
+
+The <branches> element has an optional successfulBranchesOnly attribute with the default value of no. If the value of successfulBranchesOnly is no, all <scope>'s which have completed (successfully or unsuccessfully) MUST be counted. If successfulBranchesOnly is yes, only <scope>'s which have completed successfully MUST be counted.
+
+The <completionCondition> is evaluated each time a directly enclosed <scope> activity completes. If the <completionCondition> evaluates to true, the <forEach> activity completes:
+
+* When the <completionCondition> is fulfilled for a parallel <forEach> activity, all still running directly enclosed <scope> activities MUST be terminated (see section 12.6 Termination Handlers).
+
+* When the <completionCondition> is fulfilled for a serial <forEach> activity, further child <scope>'s MUST NOT be instantiated, and the <forEach> activity completes.
+
+If upon completion of a directly enclosed <scope> activity, it can be determined that the <completionCondition> can never be true, the standard bpel:completionConditionFailure fault MUST be thrown.
+
+When a <completionCondition> does not have any sub-elements or attributes understood by the WS-BPEL processor, it MUST be treated as if the <completionCondition> does not exist.
Added: ode/site/trunk/content/extensions/process-contexts.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/process-contexts.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/process-contexts.mdtext (added)
+++ ode/site/trunk/content/extensions/process-contexts.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,244 @@
+Title: Process Contexts
+<a name="ProcessContexts-ProcessContexts"></a>
+## Process Contexts
+
+<div class="alert alert-warning">
+ This feature is implemented in Apache ODE 2.0 only.
+</div>
+
+<a name="ProcessContexts-Abstract"></a>
+### Abstract
+
+To allow the circulation of transport metadata from messages to processes and then from processes to messages, we want to add support for different levels of contextual data to our process engine. The main use cases are:
+
+* Conversation ids, such as those of the Stateful Exchange Protocol and WS-Context
+* Tracing ids, mostly with ServiceMix.
+* Credentials (such as tokens) for authentication and authorization
+* Eventually some WS-RM related context.
+
+<a name="ProcessContexts-Architecture"></a>
+### Architecture
+
+The aim of this proposal is to make transport metadata accessible within BPEL processes and allow modelers and deployers to define which metadata should be propagated between process and partners. Therefore, we model such metadata in terms of contexts. _Contexts_ are modeled as a bag of metadata information represented as key-value pairs and are attached to partner links. A partner link may maintain multiple contexts; each of them is identifiable by a name attribute to distinguish context used for different purposes (e.g. security context vs. tracing context).
+Whenever a message arrives through ODE's integration layer, the message is passed through a defined set of _context interceptors_. These interceptors are in charge to extract relevant transport metadata from messages, prepare the data and store it in terms of key-value pairs into a named context associated to the partner link from which the message came from. The context data is persistently stored in the runtime database.
+For outgoing messages, <invoke> activities can be configured to take context data from a (different) partner link, pass it again through a _context interceptor_ which translates the data back to transport-specific metadata. Such propagation configuration can be defined per invoke activity in the process model or on a global level in the deployment descriptor.
+Context data can be assigned to variables. Therefore, the context data is translated into XML data, following a predefined schema. It is possible to define which contexts of a partner link are copied to a variable. Similarly, context data can be copied from a variable back into the context of a certain partner link.
+Contexts can be used to classify or tag process instances and it is useful to make this information accessible for process management tools. Hence, this specification extends the process management API to make context data queryable and accessible.
+
+<a name="ProcessContexts-{anchor:contexts}Contexts"></a>
+### {anchor:contexts}Contexts
+
+Contexts are modeled as a bag of metadata information represented as key-value pairs `(string, string)` and are attached to partner links. Contexts have a name attribute. Contexts are persisted in ODE's runtime database. Long values are stored as a CLOB whereas shorter values (< 250 characters) are automatically stored in an indexed VARCHAR field.
+
+Since contexts should also be accessible in BPEL, there is also an XML-based representation. It is defined as follows, the according XMLSchema can be found [here](http://svn.apache.org/viewvc/ode/trunk/bpel-schemas/src/main/xsd/contexts.xsd?view=markup)
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>"Example: Context data in its XML representation"</B></DIV><DIV class="codeContent panelContent">
+ <?xml version="1.0" encoding="UTF-8"?>
+ <ctx:contexts xmlns:ctx="http://www.apache.org/ode/schemas/context/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.apache.org/ode/schemas/context/2009 contexts.xsd ">
+ <ctx:context name="foo">
+ <ctx:value key="bar">baz</ctx:value>
+ </ctx:context>
+ <ctx:context name="tracing">
+ <ctx:value key="id">0815</ctx:value>
+ </ctx:context>
+ </ctx:contexts>
+
+
+<a name="ProcessContexts-ContextInterceptors"></a>
+### Context Interceptors
+
+At the transport level, message headers can be translated to context data and contexts can be translated to message headers. Context interceptors define how the headers are set to/from contexts and which contexts are affected. Interceptors are Java classes that implement the following interface. They can be registered either globally in ode's property configuration file or per process in the `deploy.xml`.
+
+
+ /**
+ * Context Interceptors can map message headers (or even payload) to
+ * context information that is attached to process models.
+ */
+ public interface ContextInterceptor {
+
+ /**
+ * Configures the interceptor. This method will be called immediatedly after
+ * instantiation of the implementing class. The passed element will contain the
+ * configuration elements given in the deploy.xml. In case of a declaration in
+ * ode-xxx.properties, the method won't be called.
+ *
+ * @param configuration
+ */
+ void configure(Element configuration);
+
+ /**
+ * Translates the data stored within the context object into SOAP headers or
+ * vice versa.
+ *
+ * If direction is OUTBOUND, context data must be converted into message headers
+ * if direction is INBOUND, context data must be extracted from the message.
+ */
+ void process(ContextData ctx, MessageExchangeDAO mexdao, IOContext.Direction dir) throws ContextException;
+ }
+
+
+There is also a more high-level interface defined in terms of an abstract class:
+
+
+ public abstract class AbstractContextInterceptor implements ContextInterceptor {
+
+ public abstract void configure(Element configuration);
+
+ /**
+ * @see org.apache.ode.bpel.context.ContextInterceptor#process(org.apache.ode.bpel.rapi.ContextData, org.apache.ode.bpel.dao.MessageExchangeDAO, org.apache.ode.bpel.rapi.IOContext.Direction)
+ */
+ public void process(ContextData ctx, MessageExchangeDAO mexdao, IOContext.Direction dir) throws ContextException {
+ // dispatch
+ }
+
+ abstract void onPartnerInvoke(ContextData ctx, Message msg);
+ abstract void onPartnerReply(ContextData ctx, Message msg);
+ abstract void onProcessInvoke(ContextData ctx, Message msg);
+ abstract void onProcessReply(ContextData ctx, Message msg);
+
+ }
+
+
+
+<a name="ProcessContexts-WorkingwithContextsinBPEL"></a>
+### Working with Contexts in BPEL
+
+<a name="ProcessContexts-DeclaringContextInterceptors"></a>
+#### Declaring Context Interceptors
+
+In order to use context interceptors, their implementation must be registered with ODE. There are two options to do this:
+* Engine-wide registration - the context interceptor will be available for all processes that are deployed to this ODE instance.
+* Per-process registration - the context interceptor will only be available for a particular process model.
+
+Engine-wide context interceptors are registered in ODE's properties file (either `ode-axis2.properties` or `ode-jbi.properties`) using the properties key `context.interceptors`.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>ode-axis2.properties</B></DIV><DIV class="codeContent panelContent">
+ ...
+ ode-axis2.context.interceptors = my.full.qualified.context.interceptor.class.name
+ ...
+
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>ode-jbi.properties</B></DIV><DIV class="codeContent panelContent">
+ ...
+ ode-jbi.context.interceptors = my.full.qualified.context.interceptor.class.name
+ ...
+
+
+Per-process context interceptors are declared in ODE's deployment descriptor deploy.xml:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>deploy.xml</B></DIV><DIV class="codeContent panelContent">
+ <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
+ xmlns:pns="http://ode/bpel/unit-test"
+ xmlns:wns="http://ode/bpel/unit-test.wsdl">
+
+ <process name="pns:HelloWorld2">
+ <active>true</active>
+ <provide partnerLink="helloPartnerLink">
+ <service name="wns:HelloService" port="HelloPort"/>
+ </provide>
+ <context>
+ <propagate from="helloPartnerLink" to="helloPartnerLink2" context="*"/>
+ <interceptor>
+ <class-name>org.apache.ode.bpel.context.TestInterceptor</class-name>
+ <config>
+ <myparam1>x</myparam1>
+ <myparam2>y</myparam2>
+ </config>
+ </interceptor>
+ </context>
+ </process>
+ </deploy>
+
+
+The context-specific configuration takes place in the `<context>` element. The `<interceptor>` element is used to declare and register context interceptor implementations. The `<class-name>` element takes the full qualified class name of the context interceptor implementation (which must implement the `ContextInterceptor` interface). The content of the `<config>` element will be passed to configure method of the interceptor, immediately after instantiation.
+
+Static propagation rules can be configured directly in the `deploy.xml`. Using the `<propagate>` element, ODE can be configured to propagate all contexts named in the `context` attribute (space-separated list) from a certain partner link to another partner link. To propagate all contexts the `context` attribute should be set to `\*`. These rules are automatically evaluated when an invoke activity is being executed. Before a BPEL process instance invokes an operation of a certain partner link, the propagation logic performs a look-up for propagation rules that have that partner link referenced by their `to` attribute. Subsequently the specified contexts are retrieved from the partner link specified by the `from` attribute of the rule, passed to the context interceptor that translates the context data into transport meta data, which is then added to the outgoing message.
+
+<a name="ProcessContexts-CustomizeContextPropagationintheProcessModel"></a>
+#### Customize Context Propagation in the Process Model
+
+In addition to static propagation rules, context propagation can be explicitly configured for outbound interaction activities (i.e. `<invoke>` and `<reply>`. Therefore, we introduce a new BPEL extension element `<ctx:propagate>` in the `[http://ode.apache.org/contextPropagation](http://ode.apache.org/contextPropagation)` namespace (to which the `ctx`\-prefix is bound to), following the syntax as described below:
+
+
+ <bpel:invoke ...>
+ <ctx:propagate ctx:fromPartnerLink="testPartnerLink" ctx:context="*"/>
+ </bpel:invoke>
+
+
+
+ <bpel:reply ...>
+ <ctx:propagate ctx:fromPartnerLink="testPartnerLink" ctx:context="*"/>
+ </bpel:reply>
+
+
+- `ctx:fromPartnerLink` identifies the partner link the context data should be retrieved from.
+- `ctx:context` identifies which contexts should be propagates. This is a space-separated list of context names. `\*` serves as a wild card to copy all contexts.
+
+The context data identified by this propagation rule will be passed to all registered context interceptors which enhance the outgoing message accordingly.
+
+<div class="alert alert-info">
+ All partner link references are resolved by the interaction activity, i.e. only partner links can be referenced that are visible to the respective activity.
+</div>
+
+<a name="ProcessContexts-AccessingandAssigningContextData"></a>
+#### Accessing and Assigning Context Data
+
+Context data should be accessible within BPEL processes and from the outside, e.g. for management purposes. For the former, the `<assign>` activity has been extended to support copying data from and to contexts of a partner link. The according `from`/`to` specs are defined as follows:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>"from/to specs for the work with context data"</B></DIV><DIV class="codeContent panelContent">
+ <assign>
+ <!-- copy 'tracing' and 'security' contexts to a variable. -->
+ <copy>
+ <from partnerLink="pl1" context="tracing security"/>
+ <to>$var</to>
+ </copy>
+
+ <!-- copy context data from $var to pl1. Only 'tracing' and 'security' contexts will be written, other contexts remain unchanged. -->
+ <copy>
+ <from>$var</from>
+ <to partnerLink="pl1" context="tracing security"/>
+ </copy>
+
+ <!-- copy 'tracing' and 'security' contexts from pl1 to pl2. Pre-existing contexts in pl2 will be purged (*). -->
+ <copy>
+ <from partnerLink="pl1" context="tracing security"/>
+ <to partnerLink="pl2" context="*"/>
+ </copy>
+
+ <!-- copy 'tracing' and 'security' contexts from pl1 to pl2. Pre-existing contexts in pl2 will be merged (+). -->
+ <copy>
+ <from partnerLink="pl1" context="tracing security"/>
+ <to partnerLink="pl2" context="+"/>
+ </copy>
+
+ <!-- copy all contexts from pl1 to pl2. Pre-existing contexts in pl2 will be merged (+). -->
+ <copy>
+ <from partnerLink="pl1" context="*"/>
+ <to partnerLink="pl2" context="+"/>
+ </copy>
+
+ </assign>
+
+
+
+<div class="alert alert-info">
+ - `context="*"` in `from`\-specs selects all contexts.
+ - `context="*"` in `to`\-specs replaces existing contexts with context data selected by the `from`\-spec.
+ - `context="+"` in `to`\-specs merges existing contexts with context data selected by the `from`\-spec.
+</div>
+
+When assigning context data to variables, the variable should be declared to be an instance of the context XSD (see [Contexts section](#contexts.html)). It is also possible to copy only fragments of a context data set by applying an XPath query to the `from`\-spec:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>"Applying XPath-query to context data"</B></DIV><DIV class="codeContent panelContent">
+ <assign>
+ <!-- copy tracing id to a string variable. -->
+ <copy>
+ <from partnerLink="pl1" context="*">
+ <query>/ctx:contexts/ctx:context[@name='tracing']/ctx:value[@key='id']</query>
+ </from>
+ <to>$tracingId</to>
+ </copy>
+ </assign>
+
+
+In order to make context data accessible for external management tools, the ProcessManagement-API has been extended. TODO: to be completed.
Added: ode/site/trunk/content/extensions/restful-bpel-part-i.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/restful-bpel-part-i.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/restful-bpel-part-i.mdtext (added)
+++ ode/site/trunk/content/extensions/restful-bpel-part-i.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,35 @@
+Title: RESTful BPEL, Part I
+<div class="alert alert-warning">
+ This feature is not yet implemented in ODE. This is a proposal and is subject to change based on feedback, implementation experience, etc.
+</div>
+
+<a name="RESTfulBPEL,PartI-Invoke"></a>
+### Invoke
+
+The RESTfulvariant of the invoke activity replaces the attributes partnerLink/operation with resource and method. The method attribute identifies the HTTP method. All HTTP methods are supported, although this spec is only concerned with GET, POST, PUT and DELETE. The resource attribute identifies a BPELvariable of a simple type (xsd:uri, xsd:string, etc) used as the URL of the actual resource. The resource element can be used instead of the resource attribute to calculate the URL using an expression.
+
+In addition to the above, the invoke activity adds a way to map values to/from HTTP headers, using a syntax similar to that for mapping message parts, but specifying the corresponding HTTP header instead. Headers mapped by the process override default values, and some headers have special handling.
+
+The implementation shields the invoke activity from some of the details of the HTTP protocol, specifically:
+* Requests automatically follow redirects.
+* The Location and Content-Location headers are expanded to absolute URLs and will only use HTTP/HTTPS URLs.
+* Content negotiation and compression are handled automatically.
+* Proxies are handled automatically.
+* GET, PUT and DELETE requests retried automatically for certain error conditions.
+* GET requests may be cached by the engine, private caching is never shared across process instances.
+
+This example uses the myPost variable to create a new blog post, store the response in the newPost variable, and the location of the new post in the variable newPostUrl:
+
+ invoke resource=createPostsUrl method=post
+ input=myPost output=newPost
+ from header=location to=newPostUrl
+
+And to update the post:
+
+ invoke resource=newPostUrl method=put input=updatedPost
+
+
+<a name="RESTfulBPEL,PartI-XPathfunctions"></a>
+### XPath functions
+
+The use or URLs requires the ability to combine URLs with two new XPath functions: `combine-url(base, relative)` and `compose-url(template, [name, value]*)` / `compose-url(template, pairs)`. See [xpath extensions](xpath-extensions.html#combineurl(base,relative)) for details.
Added: ode/site/trunk/content/extensions/restful-bpel-part-ii.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/restful-bpel-part-ii.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/restful-bpel-part-ii.mdtext (added)
+++ ode/site/trunk/content/extensions/restful-bpel-part-ii.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,95 @@
+Title: RESTful BPEL, Part II
+<div class="alert alert-warning">
+ This feature is not yet implemented in ODE. This is a proposal subject to feedback, implementation experience, etc.
+</div>
+
+<a name="RESTfulBPEL,PartII-UseCases"></a>
+### Use Cases
+
+_Use case 1_: A client needs to process _foo_, which it does by creating a new resource which it can operate on. The client starts by making a POST request to /foos. This results in a new resource, a response with status code 201 (Created), relevant document and the Location header pointing to the URL of the new resource (/foos/123). The client can then operate on the new resource, e.g. reading its state at various points in time (GET), changing its state (PUT), or even discarding it (DELETE).
+
+_Use case 2_: Continuing with use case 1, the client may need to process _bar_ or _baz_, as part of the larger processing of _foo_. The client will attempt to create a new resource under /foos/123/bar or /foos/123/baz, but to do so the client must first determine the URL for either resource. This is done in a separate step, maybe in the response to the request that created /foos/123 or a subsequent operation against that resource (or in fact some other resource).
+
+_Use case 3_: Continuing with use case 1, the client is able to operate on a collection of items that are part of the larger processing of _foo_. Those are exposed behind a URL like /foos/123/items/456, where 456 is the item number. The exact number of resources available depend on the number of items in that collection.
+
+To achive these use cases we need the following features:
+
+1. Ability to instantiate (create) resources that are unique to the processing unit (process, scope).
+2. Ability to map resources (URL) into the content of a variable or message.
+3. Ability to operate on nested resources, i.e. a resource defined relative to another resource.
+4. Ability to recieve messages on a resource signifying a collection and map part of the request URL into member identification.
+
+The above deal specifically with resources, but in addition we will also need a way to handle HTTP variables and query string parameters. We also expect the process engine to take care of common protocol details, such as status codes, redirection, cache control, content negotiation and encoding, HEAD and OPTIONs requests, etc.
+
+<a name="RESTfulBPEL,PartII-Resources"></a>
+### Resources
+
+Resources are declared in a scope, and a scope may declare any number of resources. A resource declaration consists of two properties, the resource *name*, which we use to reference the resource, and a relative *path* that denotes the relationship between this resource and other resources. Once instantiated, the value of the resource is an absolute URL.
+
+The process can use resources in two ways. It can reference a resource for the purpose of receiving requests on that resource or a member of the collection denoted by the resource. It can also access the value of the resource (URL), for example, to send it as part of a message.
+
+To access the value of the resource, we treat the resource as a read-only variable with the type xsd:uri. Expressions can access the resource as they would any other variable available in the scope, but cannot modify (assign to) its value. For that reason, all resources declared in a scope must have unique name and in addition no variable and resource declared in the same scope may have the same name.
+
+A resource that specifies no path (or the empty path) will be instantiated using a URL unique to that process instance. A resource that specifies a static path will be instantiated by appending that path to the instance URL. A resource that specifies a path relative to another resource will be instantiated by appending that path to the URL of the other resource. We use the $ notation to reference another resource, so the path $foo/bar will append /bar to the URL denoted by the resource $foo.
+
+
+<a name="RESTfulBPEL,PartII-Recievingrequests"></a>
+### Recieving requests
+
+To expose themselves as resources, the receive activity and event handler introduce four new properties. The *method* property specifies the HTTP method to accept, and the semantics of each HTTP method are described below. The *resource* property references a resource declaration available in the scope.
+
+The *instantiateResource* property is true if the resource is instantiated by the receive activity or event handler, and false if the resource must be instantiated before the activity executes. This property can only be set to true when using the POST method, and is always true for the instantiating activity of the process.
+
+When instantiateResource is false, the resource is instantiated first and the activity receives requests on that URL. When instantiateResource is true, the resource value is calculated and the activity receives requests on that URL. Once received, the resource is instantiated by appending a unique identifier to that URL. For example, the receive activity listens on the URL /foos, and upon receipt instantiates the resource to the URL /foos/123. In addition, the corresponding reply activity will set the status code to 201 (Created) and set the Location header to the resource URL.
+
+The *resourceIdentity* activity names a variable that will be set to the member identity when receiving requests on behalf of a collection resource. When used in event handlers, the variable is implicitly defined in the implicit scope of the event handler and has the type xsd:string.
+
+For example, if the resource is /foos/123/bars and the resourceIdentity is set to bar, then the activity will receive requests on the URL /foos/123/bars/\{bar\}, and the last part of the request URL path (the member identity \{bar\}) is assigned to the value of the variable bar.
+
+<a name="RESTfulBPEL,PartII-POST"></a>
+#### POST
+
+The POST method has two uses, one involving the creation of a new resource, and the other involving processing of requests that do not map to any other HTTP method. The receive activity is coupled to a reply activity, and no other receive or wait is allowed to occur between the two.
+
+When using the POST method to create a new resource, including in the instantiating activity of the process, the instantiateResource property is set to true, and the resource is instantiated by the activity. The reply activity uses the status code 201 (Created).
+
+When using the POST method to process requests, the instantiate property is set to false. The reply activity sets the status code to 200 (OK), or if there is no document entity, to 204 (No Content).
+
+<a name="RESTfulBPEL,PartII-GET/HEAD"></a>
+#### GET/HEAD
+
+The GET method has on side effects. To preserve this constraint only event handlers are allowed to use the GET method, and the event handler may only contain the reply activity. In addition, the event handler can only assign to variables declared in the implicit scope of the event handler, and faults occurring in the event handler are not propagated to the enclosing scope.
+
+The process engine uses cache control to optimize the GET method by handling conditional GETs and setting the Last-Modified/ETag headers. These are set to detect any change in the state of the process instance (which excludes responding to a GET request).
+
+The HEAD method is handled using receives for the GET method, without constructing a document entity in the response.
+
+<a name="RESTfulBPEL,PartII-PUT"></a>
+#### PUT
+
+The PUT method is used to modify state. To be used successfully in combination with GET, the process engine supports conditional PUTs and returns 412 (Precondition Failed) if it detects a change in the process state since the corresponding GET.
+
+The receive activity is coupled to a reply activity, and no other receive or wait is allowed to occur between the two. The reply activity sets the status code to 200 (OK), or if there is no document entity, to 204 (No Content).
+
+<a name="RESTfulBPEL,PartII-DELETE*"></a>
+#### DELETE*
+
+The DELETE method does not have a corresponding reply activity and returns the status code 200 (OK).
+
+<a name="RESTfulBPEL,PartII-OPTIONS"></a>
+#### OPTIONS
+
+The OPTIONS method is handled by the process engine.
+
+<a name="RESTfulBPEL,PartII-Additional"></a>
+### Additional
+
+Since all incoming requests must disambiguate a receive activity, no two receive activities can be outstanding on the same URL using the same method. This behavior is defined in term of URLs not resources, since it is possible for two resources to denote the same URL. It is also possible for the same resource to be used, once with the resourceIdentity property and once without, since those map two distinct URLs (/foos/something vs /foos).
+
+The reply activity is matched to the corresponding receive activity based on the resource name.
+
+Both receive and reply activities have access to an implicit message part called bodythat contains the internal representation of the document entity. Receive activities have access to an implicit message part called params, instantiated from the query string parameters. The XML representation of this part consists of the element Parameters, which maps query string parameters as follows:
+
+* foo -- Maps to the element foo.
+* foo\[bar\](bar\.html) -- Maps to the element bar contained in the parent element foo.
+* foo\[\](\.html) -- Each value is mapped to an element called foo in the parent element foos.
Added: ode/site/trunk/content/extensions/wsdl-11-extensions-for-rest.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/extensions/wsdl-11-extensions-for-rest.mdtext?rev=1426497&view=auto
==============================================================================
--- ode/site/trunk/content/extensions/wsdl-11-extensions-for-rest.mdtext (added)
+++ ode/site/trunk/content/extensions/wsdl-11-extensions-for-rest.mdtext Fri Dec 28 13:13:31 2012
@@ -0,0 +1,281 @@
+Title: WSDL 1.1 Extensions for REST
+
+## Overview
+
+The [Resource-Oriented Architecture](http://en.wikipedia.org/wiki/Representational_State_Transfer) defines four concepts:
+
+1. Resources
+1. Their names (URIs)
+1. Their representations
+1. The link bet ween them
+
+and four properties:
+
+1. Addressability
+1. Statelesness
+1. Connectedness
+1. A uniform interface
+
+HTTP binding as defined in WSDL 1.1 is not well suitable to describe services implementing these concepts and properties, mainly because a port type may access 4 different locations/resources but with only one HTTP method.
+
+To better describe RESTful services, and turn a port type into a "resource type", ODE brings a set of 4 extensions:
+
+1. one HTTP method per operation (instead of one per binding)
+1. a unique URI Template for all operations
+1. access to HTTP headers
+1. fault support
+
+Further details below.
+
+In this page, we use an imaginary blog service as a use case to illustrate and make things more palpable. We will focus on the resources defined by the following URI template: `http://blog.org/post/{id}`
+
+Let's assume that such a resource accept four operations:
+
+* GET to retrieve a post
+* DELETE to delete it
+* PUT to update the post
+* POST to add a comment to a post
+
+<div class="alert alert-info"><h4 class="alert-heading">Check out unit tests!</h4></div>
+
+### One verb per operation
+
+According to the WSDL 1.1 specification, the verb describing the HTTP method has to be at [the binding level](http://www.w3.org/TR/wsdl#A4.3). Which implies that the same HTTP method is used by all operations of a given port type. But RESTful web services leverage HTTP methods as a uniform interface to describe operation on resources. So for instance, if you want to use the following HTTP operations -- GET, POST, PUT, DELETE -- for a given resource, four different bindings would be required. And consequently four port types and four ports. Quite verbose and unusable, isn't it?
+
+So, this extension is to push down the HTTP verb at the operation level. And if an operation does not have its own verb, then the verb defined at the binding level will be used.
+This extension is declared in the namespace: `http://www.apache.org/ode/type/extension/http`
+
+Please note that ODE supports GET, POST, PUT, DELETE only.
+
+ :::xml
+ <definitions ...
+ xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
+
+ <!-- many wsdl elements are ommited to highlight the interesting part -->
+
+ <binding name="blogBinding" type="blogPortType">
+ <operation name="GET">
+ <odex:binding verb="GET" />
+ </operation>
+ <operation name="DELETE">
+ <odex:binding verb="DELETE"/>
+ </operation>
+ </binding>
+ </definitions>
+
+### URI Template
+
+A RESTful service exposed a set of resources, each of them being accessible through a uniform interface: HTTP methods for a web service. So we need a way to define four operations (at most) for a single resource.
+
+Moreover it's very likely that the resource URI actually describes a set of resources. For instance, the set of posts contained in our imaginary blog: `http://blog.org/post/{post_id}`.
+
+HTTP binding offers the [http:operation ](http://www.w3.org/TR/wsdl#_http:operation) element to set the path of an operation. While the service address is set in the [http:address](http://www.w3.org/TR/wsdl#_http:address) of the [wsdl:port](http://www.w3.org/TR/wsdl#_ports) element.
+So one could imagine splitting the URL this way:
+
+ :::xml
+ <definitions ...
+ xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
+
+ <service name="blogService">
+ <port name="blogPort" binding="blogPortType">
+ <http:address location="http://blog.org"/>
+ </port>
+ </service>
+
+ <binding name="blogBinding" type="blogPortType">
+ <operation name="PUT">
+ <odex:binding verb="PUT" />
+ <http:operation location="post/(post_id)"/>
+ <input>
+ <http:urlReplacement/>
+ </input>
+ <output/>
+ </operation>
+ </binding>
+ </definitions>
+
+
+However, here 3 issues show up:
+
+* the location is not accessible from the End Point Reference. _=> ODE cannot process it before invoking the external service._
+* [http:urlReplacement](http://www.w3.org/TR/wsdl#_http:urlReplacement) is only accepted for GET _=> what about the uniform interface?!_
+* http:urlReplacement requires all parts of the operation input message to be mentioned in the operation location. Meaning that:
+ * => the resource id (in the present example) must be a part of the message.
+ * => no parts may be stored in the HTTP body. this conflicts with a PUT operation for instance. With a PUT you would like to set the id in the url and the resource data in the HTTP request body.
+
+To solve this, ODE allows [http:operation](http://www.w3.org/TR/wsdl#_http:operation) elements to be omitted or empty, and the full resource URI to be set in a single place, the http:address element.
+
+<div class="alert alert-info">Please note that curly brackets '{}' are the preferred argument delimiters in URI templates. So that URLs can be dynamically composed using <a href="restful-bpel-part-i.html#XPath functions">compose-url, combine-url and expand-template XPath Functions</a>.</div>
+
+In addition, the http:urlReplacement is relaxed: all parts are *not* required in the URI template anymore. One part could go in the URI, another in the request body.
+
+ :::xml
+ <definitions ...
+ xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
+
+ <service name="blogService">
+ <port name="blogPort" binding="blogPortType">
+ <!-- here is the full URI template, using curly brackets -->
+ <http:address location="http://blog.org/post/{post_id}"/>
+ </port>
+ </service>
+
+ <binding name="blogBinding" type="blogPortType">
+ <operation name="PUT">
+ <odex:binding verb="PUT" />
+ <!-- location attribute intentionally blank -->
+ <http:operation location=""/>
+ <input>
+ <http:urlReplacement/>
+ <!-- an additional part can be mapped to the request body even if urlReplacement is used-->
+ <mime:content type="text/xml" part="post_content"/>
+ </input>
+ <output/>
+ </operation>
+ </binding>
+ </definitions>
+
+### HTTP Headers manipulation
+
+HTTP protocal convey a lot of information in Request/Response Headers. Caching information, Content description for instance. All this data is completely left out by WSDL 1.1 HTTP Binding. To fix this, ODE provides a header element. This element can be used to insert a part or a static value into a given HTTP request header (standard or custom). And the way around, a HTTP request header into a part. Also note that all HTTP response headers are inserted into the message headers, and thus are available from the BPEL process.
+
+ :::xml
+ <definitions ...
+ xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
+
+ <binding name="blogBinding" type="blogPortType">
+ <operation name="PUT">
+ <odex:binding verb="PUT" />
+ <http:operation location=""/>
+ <input>
+ <http:urlReplacement/>
+ <mime:content type="text/xml" part="post_content"/>
+ <!-- set a standard request header from a part -->
+ <odex:header name="Authorization" part="credentials_part"/>
+ <!-- set a custom request header with a static value -->
+ <odex:header name="MyCustomHeader" value="ode@apache.org" />
+ </input>
+ <output>
+ <mime:content type="text/xml" part="post_content"/>
+ <!-- set 1 response header to a part -->
+ <odex:header name="Age" part="age_part"/>
+ </output>
+ </operation>
+ </binding>
+ </definitions>
+
+For every HTTP response, in addition to HTTP response headers, the [Status-Line](http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1) is passed as a message header. To save some painful XPath string manipulations, the Status-line is already parsed into the following structure:
+
+ :::xml
+ <Status-Line>
+ <HTTP-Version>HTTP/1.1</HTTP-Version>
+ <Status-Code>200</Status-Code>
+ <Reason-Phrase>OK</Reason-Phrase>
+ <!-- the original unaltered Status-Line -->
+ <original>HTTP/1.1 200 OK</original>
+ </Status-Line>
+
+So that you can write the following BPEL lines:
+
+ :::xml
+ <assign>
+ <copy>
+ <from variable="postMsg" header="Status-Line"/>
+ <to>$statusLine</to>
+ </copy>
+ </assign>
+ <if>
+ <condition>number($statusLine/Status-Code) > 200 and number($statusLine/Status-Code) < 300</condition>
+ <assign>
+ <copy>
+ <from>'Request successful!!!'</from>
+ <to>$outputVar.TestPart</to>
+ </copy>
+ </assign>
+ </if>
+
+### Fault Support
+
+Another domain completely neglected by WSDL 1.1 HTTP Binding is Fault management. The word is not even mentioned in the [HTTP Binding section](http://www.w3.org/TR/wsdl#_http).
+ODE allows you to bind a fault with HTTP Binding. If a [4xx or a 5xx](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4) is returned, the following logic is applied:
+
+A failure is thrown if the code is one of these:
+
+<table>
+ <thead>
+ <tr>
+ <th>Status-Codes triggering a Failure</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>3xx Redirections</td>
+ </tr>
+ <tr>
+ <td>401_UNAUTHORIZED</td>
+ </tr>
+ <tr>
+ <td>408_REQUEST_TIMEOUT</td>
+ </tr>
+ <tr>
+ <td>503_SERVICE_UNAVAILABLE</td>
+ </tr>
+ <tr>
+ <td>504_GATEWAY_TIMEOUT</td>
+ </tr>
+ </tbody>
+</table>
+
+<div class="alert alert-info">Note that 3xx errors should be pretty rare since by default the first hundred redirections are followed. You can tweak this value by setting the property <code>http.protocol.max-redirects</code> in the <a href="endpoint-configuration.html">enpoint-configuration.properties</a> of your process.</div>
+
+Here what ODE does, if the status code is one of those listed in the next table (500, 501, etc):
+
+* check that the operation has at least one fault in its abstract part, and one fault binding
+* check that the Content-type header describes an xml document ('application/xml', 'application/atom+xml' etc)
+* check that the body is not empty
+
+If so far everything is fine, the HTTP response body is parsed into an xml document. Then the fault to be thrown is inferred from the qname of the response root element, i.e the fault having a message part matching the root element. This matching process is exactly the same as for a SOAP service.
+If one of these steps fails, a failure is thrown.
+
+Status-Codes that may trigger a Fault |if the body element matches a fault declaration
+-----------------------------------------------------------------------------------------
+500_INTERNAL_SERVER_ERROR | 407_PROXY_AUTHENTICATION_REQUIRED
+501_NOT_IMPLEMENTED | 409_CONFLICT
+502_BAD_GATEWAY | 410_GONE
+505_HTTP_VERSION_NOT_SUPPORTED | 412_PRECONDITION_FAILED
+400_BAD_REQUEST | 413_REQUEST_TOO_LONG
+402_PAYMENT_REQUIRED | 414_REQUEST_URI_TOO_LONG
+403_FORBIDDEN | 415_UNSUPPORTED_MEDIA_TYPE
+404_NOT_FOUND | 411_LENGTH_REQUIRED
+405_METHOD_NOT_ALLOWED | 416_REQUESTED_RANGE_NOT_SATISFIABLE
+406_NOT_ACCEPTABLE | 417_EXPECTATION_FAILED
+
+Note that you can't bind a given fault to a specific status code.
+
+ :::xml
+ <definitions ...
+ xmlns:odex="http://www.apache.org/ode/type/extension/http"/>
+
+ <portType name="BlogPortType">
+ <operation name="PUT">
+ <input message="..."/>
+ <output message="..."/>
+ <fault name="UpdateFault" message="tns:UpdateFault"/>
+ </operation>
+ </portType>
+
+ <binding name="blogBinding" type="blogPortType">
+ <operation name="PUT">
+ <odex:binding verb="PUT" />
+ <http:operation location=""/>
+ <input> ... </input>
+ <output> ... </output>
+ <!-- fault binding -->
+ <fault name="UpdateException">
+ <!-- name attribute is optional if there is only one fault for this operation -->
+ <!-- <odex:fault name="UpdateFault"/> -->
+ <odex:fault/>
+ </fault>
+ </operation>
+ </binding>
+ </definitions>