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/11 13:48:00 UTC
svn commit: r1420130 [1/2] - in /ode/site/trunk/content: ./ developerguide/
userguide/
Author: vanto
Date: Tue Dec 11 12:47:58 2012
New Revision: 1420130
URL: http://svn.apache.org/viewvc?rev=1420130&view=rev
Log:
restructuring.
Added:
ode/site/trunk/content/developerguide/
ode/site/trunk/content/developerguide/architectural-overview.mdtext
ode/site/trunk/content/developerguide/atomic-scopes-extension-for-bpel.mdtext
ode/site/trunk/content/developerguide/eclipse-ide.mdtext
ode/site/trunk/content/developerguide/index.mdtext
ode/site/trunk/content/developerguide/jacob.mdtext
ode/site/trunk/content/developerguide/release-guidelines.mdtext
ode/site/trunk/content/developerguide/stateful-exchange-protocol.mdtext
ode/site/trunk/content/userguide/
ode/site/trunk/content/userguide/index.mdtext
ode/site/trunk/content/userguide/jbi-deployment.mdtext
ode/site/trunk/content/userguide/smx4-osgi-deployment.mdtext
ode/site/trunk/content/userguide/upgrading-ode.mdtext
ode/site/trunk/content/userguide/war-deployment.mdtext
Removed:
ode/site/trunk/content/architectural-overview.mdtext
ode/site/trunk/content/atomic-scopes-extension-for-bpel.mdtext
ode/site/trunk/content/developer-guide.mdtext
ode/site/trunk/content/eclipse-ide.mdtext
ode/site/trunk/content/jacob.mdtext
ode/site/trunk/content/jbi-deployment.mdtext
ode/site/trunk/content/release-guidelines.mdtext
ode/site/trunk/content/smx4-osgi-deployment.mdtext
ode/site/trunk/content/stateful-exchange-protocol.mdtext
ode/site/trunk/content/upgrading-ode.mdtext
ode/site/trunk/content/user-guide.mdtext
ode/site/trunk/content/war-deployment.mdtext
Added: ode/site/trunk/content/developerguide/architectural-overview.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/architectural-overview.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/architectural-overview.mdtext (added)
+++ ode/site/trunk/content/developerguide/architectural-overview.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,55 @@
+Title: Architectural Overview
+Category: documentation
+
+<a name="ArchitecturalOverview-Introduction"></a>
+## Introduction
+
+The purpose of this document is to outline the high-level architecture of Apache ODE. First, we describe the architectural objectives, then the various ODE components and how they interact. It is assumed that the reader is familiar with BPEL and the BPEL specification.
+
+<a name="ArchitecturalOverview-Objectives"></a>
+## Objectives
+
+The principal objective in the development of ODE was to create a reliable, compact, and embedable component capable of managing the execution of long-running business processes defined using the BPEL process description language. The focus has been on developing small modules with minimal dependencies that could be assembled (and easily reassembled) to construct a full featured BPMS.
+
+<a name="ArchitecturalOverview-Components"></a>
+## Components
+
+The key components of the ODE architecture include the ODE BPEL Compiler, ODE BPEL Engine Runtime, ODE Data Access Objects (DAOs), ODE Integration Layers (ILs), and user tooling. A high-level depiction of the relationships between these components is shown in the Figure below. It can be summarized as: "The compiler converts BPEL documents into a form executable by the run-time, which executes them in a reliable fashion by relying on a persistent store accessible via the DAOs; the run-time executes in the context of an Integration Layer which connects the engine to the broader execution environment ( i.e. the "world").
+
+
+
+<a name="ArchitecturalOverview-ODEBPELCompiler"></a>
+### ODE BPEL Compiler
+
+The BPEL compiler is responsible for the conversion of the source BPEL artifacts (i.e. BPEL process documents, WSDLs, and schemas) into a compiled representation suitable for execution. The output of the compiler is either a "good" compiled representation, or a list of error messages indicating problems with the source artefacts.
+
+The compiled BPEL representation generated by the compiler is an object model similar in structure to the underlying BPEL process document. However, the compiled representation has resolved the various named references present in the BPEL (such as variable names), internalized the required WSDL and type information, and generated various constructs (e.g. default compensation handlers). The compiled representation (typically a file with the .cbp extension) is the sole artifact required by the BPEL runtime.
+
+<a name="ArchitecturalOverview-ODEBPELEngineRuntime"></a>
+### ODE BPEL Engine Runtime
+
+The ODE BPEL Engine Runtime ("runtime") is found in the bpel-runtime module and provides for the execution of compiled BPEL processes. The runtime handles the dirty work of process execution by providing implementations of the various BPEL constructs. The runtime also implements the logic necessary to determine when a new instance should be created, and to which instance an incoming message should be delivered. Finally, the runtime implements the Process Management API that is used by user tooling to interact with the engine.
+
+To achieve reliable execution of processes in unreliable environments, the runtime relies on Data Access Objects (DAOs) to provide persistence facilities. The implementation of these DAOs can be customized, but is typically provided by a transactional relational database. The DAOs are described in more detail in the next section.
+
+The runtime implementation of BPEL constructs at the instance level is via ODE's Java Concurrent Objects ([JaCOb](jacob.html)) framework. [JaCOb](jacob.html) provides an application-level concurrency mechanism (i.e. it does not rely on threads) and a transparent mechanism for interrupting execution and persisting execution state. [JaCOb](jacob.html) is in very large part a Java implementation of the ACTORS [[Agha](agha.html)] concurrency model and shares many features with process algebras such as π-calculus. Essentially, [JaCOb](jacob.html) provides a persistent virtual machine for executing BPEL constructs.
+
+<a name="ArchitecturalOverview-ODEDataAccessObjects"></a>
+### ODE Data Access Objects
+
+ODE Data Access Objects mediate the interaction between the BPEL Engine Runtime and an underlying data store. Typically the data store is a JDBC relational database: in this case, the DAOs is implemented via the OpenJPA data access library. It is possible to create custom DAO implementations that employ a mechanism other than JDBC to achieve persistence, although no such implementation is provided. The BPEL Engine Runtime requires DAO objects to deal with the following persistence issues:
+
+* active instances -- keeping track of which instances have been created
+* message routing -- which instance is waiting for which message
+* variables -- the values of the BPEL variables for each instance
+* partner links -- the values of the BPEL partner links for each instance
+* process execution state -- the serialized state of the [JaCOb](jacob.html) "persistent virtual machine"
+
+For the OpenJPA/JDBC DAO implementation, the relational structure used to provide the above is shown in TODO.
+
+<a name="ArchitecturalOverview-ODEIntegrationLayers"></a>
+### ODE Integration Layers
+
+The ODE BPEL Engine Runtime cannot exist in a vacuum: by itself it is incapable of affecting any interaction with the outside world. For this it relies on an the ODE Integration Layers (ILs). Integration Layers embed the runtime in an execution environment. For example, there are integration layers for AXIS2 and JBI. The fundamental function of an IL is to provide communication channels for the runtime. The AXIS2 IL achieves this by using the AXIS2 libraries to allow the runtime to communicate via Web Service interactions. The JBI IL achieves this same goal by tying the runtime into the JBI message bus.
+
+In addition to communication, an IL provides the runtime with a thread scheduling mechanisms, and manages the life-cycle of the runtime (i.e. configuring and starting the runtime).
Added: ode/site/trunk/content/developerguide/atomic-scopes-extension-for-bpel.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/atomic-scopes-extension-for-bpel.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/atomic-scopes-extension-for-bpel.mdtext (added)
+++ ode/site/trunk/content/developerguide/atomic-scopes-extension-for-bpel.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,126 @@
+Title: Atomic Scopes Extension for BPEL
+Category: documentation
+
+<a name="AtomicScopesExtensionforBPEL-Introduction"></a>
+# Introduction
+The goal of this specification is to provide a simple extension to WS-BPEL 2.0 that enables atomic scopes. Atomic scopes allow the process definition to demarcate atomic transactions against any number of invoked services, and participate in a distributed transaction.
+
+The extension defines atomic scope as an extension of the already defined isolated scopes. It describes the atomic semantics for state changing operatings, such as assignments, for service invocations and for receiving and responding to service calls. It also covers the use of compensation handlers and event handlers.
+
+<a name="AtomicScopesExtensionforBPEL-AtomicScopes"></a>
+# Atomic Scopes
+An *atomic scope* is marked with the attribute ```atomic``` set to ```yes```. This attribute applies to processes, *scope* activities and event handlers (their implicit scopes).
+
+Atomic scopes provide isolation semantics, inheriting these semantics from isolated scopes. However, atomic scopes are not isolated scopes, specifically their compensation handler do not have isolated semantics. Atomic scopes cannot be nested inside atomic scopes or isolated scopes, and cannot enclose isolated scopes.
+
+<a name="AtomicScopesExtensionforBPEL-StateChangesandAssignments"></a>
+# State Changes and Assignments
+Atomic scopes provide '*all-or-nothing*'' behavior for all state changes made during the execution of activities inside the scope, and the status of all links crossing the scope boundary.
+
+State changes include changes to variables, partner links and correlations sets declared in any scope enclosing the atomic scope. These state changes are not visible outside the atomic scope until the scope activity completes (successfully or unsuccessfully). These state changes are discarded if the atomic scope throws a fault in the enclosed scope.
+
+The status of links that cross the boundary of an atomic scope and have a source activity inside the atomic scope is set only when the scope completes. If the scope completes without throwing a fault, the status of these links is set as per the result of their transition conditions. If the scope throws a fault, the status of all these links is set to false.
+
+The status of message exchange is not affected by the atomic scope. Specifically all message exchanges made inside the atomic scope must complete before the scope is allowed to complete.
+
+Since atomic scopes provide all-or-nothing semantics, *assign* activities inside the scope are not by themselves atomic. Rather, all *assign* activities occurring in the scope are collectively atomic, since the scope will discard all state changes if it throws a fault.
+
+However, catching and handling the ```bpws:selectionFailure``` fault or any other fault throws by an *assign* activity could lead to partial assignments if the scope is allowed to complete. If fault handlers must be used inside the atomic scope, use them with discretion. This rule also applies to other unintended consequences of indiscriminately catching and handling faults inside an atomic scope.
+
+<a name="AtomicScopesExtensionforBPEL-ActivitiesThatWait"></a>
+# Activities That Wait
+Since atomic scopes are intended to complete in a short duration of time, they are not allowed to wait for events occurring outside the scope, with the exception of events that trigger the scope.
+
+Atomic scope are not allowed to use the *receive*, *wait* and *pick* activities, except for the case described below. Atomic scopes are not allowed to use event handlers, including not in any scope nested within the atomic scope.
+
+An atomic scope may begin by receiving a message from a partner. In this case it can use the *receive* activity if that *receive* activity is the first basic activity to execute in the scope and no other basic activity is allowed to execute before it. Alternatively, it can use a *pick* activity with two or more *onMessage* handlers if no other basic or *pick* activity is allowed to execute before it.
+
+Such a scope may begin with the block activity *sequence* or *flow* as long as it can guarantee that the first basic activity to execute is the *receive* or *pick* activity. These restrictions are similar to the start activity of a process.
+
+An *onEvent* event handler can use the ```atomic``` attribute to specify atomic behavior for its implicit scope. In this case, the received message is treated as if the event handler started with a *receive* activity for that message. All other atomic scope restrictions are applied to the implicit scope created by the event handler.
+
+If an atomic scope has a *receive* activity for a request-response operation, it must also include all *reply* activities that may send the corresponding response message. Specifically, it is an error for a *receive*/*reply* pair to cross the boundaries of an atomic scope.
+
+An atomic scope is allowed to include an activity that is the target of a link, where the source activity resides outside the scope, only if the status of the link is determined before the atomic scope begins executing that activity.
+
+If the process engine detects a violation of these restrictions if must throw an ```atomic:scopeRollback``` fault. If the process engine detects such a violation during static analysis, it should reject the process definition.
+
+<a name="AtomicScopesExtensionforBPEL-FaultsandTermination"></a>
+# Faults and Termination
+Atomic scopes complete with one of three possible outcomes:
+
+1. *Successful Completion* -- The *scope* activity, process or event handler completes without throwing a fault. For the *scope* activity this also includes evaluation of all transition conditions. All state changes made by the scope become visible to enclosing scopes and the compensation handler is installed.
+1. *Unsuccessful Completion* -- A fault is thrown in the atomic scope and is handled by a fault handler. The behavior is similar to successful completion with the exception that the compensation handler is not installed.
+1. *Scope Rollback* -- A fault is thrown by the *scope* activity or event handler, or the process terminates. All state changes made by the scope are discarded, no compensation handler is installed, and the status of all links originating from the scope is set to false.
+
+The first two outcomes are similar to the successful and unsuccessful completion of non-atomic scopes. The last outcome is the case of a non-atomic scope throwing a fault, with the exception that all state changes are discarded.
+
+An atomic scope that catches a fault and its fault handler rethrows that fault or throws a different fault, would result in the rollback outcome and discard all state changes.
+
+It is recommended not to use fault handlers inside atomic scopes, since atomic scopes already provide a mechanism for dealing with failure, and indiscreminate use of fault handlers could lead to partial state changes and other unexpected results. However, there are some cases where fault handling is necessary, and the spec allows the use of fault handlers to deal with these situations.
+
+Atomic scopes are intended to execute for a short duration of time, in particular since they may tie up global resources beyond the specific process. Like atomic activities, they cannot be interrupted by a fault thrown in an enclosing scope. However, implementations would terminate scopes that take too long to complete. It is up to the implementation to decide on the appropriate time duration.
+
+In terminating the atomic scope, the implementation must force a rollback outcome, effectively throwing an ```atomic:scopeRollback``` fault in the enclosing scope. The behavior is similar to the way termination occurs in non-atomic scopes, with the exception that the scope has to terminate quickly and all state changes are discarded. As such, atomic scopes are not allowed to use termination handlers.
+
+<a name="AtomicScopesExtensionforBPEL-Compensation"></a>
+# Compensation
+The compensation handler associated with an atomic scope is not by itself atomic. Some atomic scopes can use atomic compensation, however, other atomic scopes can only use non-atomic compensation. We cannot enforce an atomic scope to have an atomic compensation handler. To perform atomic compensation, the compensation handler may itself use an atomic scope.
+
+The behavior of a compensation handler depends not on the scope in which it is defined, but the scope in which it is invoked. This could lead to situations where the compensation handler is potentially invoked in three different and incompatible scopes.
+
+Consider a non-atomic outer scope *So*, enclosing an atomic scope *Sa*, itself enclosing an inner scope *Si* (perhaps an *invoke* activity). The scope *Si* installs a compensation handler *Ci*. The default fault handler associated with the scope *Si* will invoke the compensation handler *Ci* in that atomic scope, and then discard all state changes (by rethrowing the fault).
+
+The atomic scope *Sa* can have a compensation handler *Ca* that invokes the compensation handler *Ci* from a non-atomic scope. However, the outer scope *So* may have a compensation handler that invokes *Ca* and through it *Ci* from within an atomic scope. Besides these three explicitly defined handlers, we also have to consider default and defined compensation, fault and termination handlers of each enclosing scope. This makes it hard to define compensation handlers that execute reliably.
+
+Atomic scopes are generally simple in their logic and do not benefit much from the ability to compose compensation handlers though invocation of inner compensation handlers. In favor of simplicity the specification imposes the following constraints:
+
+1. *Installing* -- Scopes nested inside an atomic scope (including the *invoke* activity shortcut) are not allowed to define a compensation handler.
+1. *Invoking* -- Atomic scopes are not allowed to invoke any compensation handler through use of the *compensate* and *compensateScope* activities (or any other mechanism).
+
+Since scopes nested inside an atomic scope are not allowed to install compensation handlers, the default fault handling behavior of an atomic scope is to rethrow the fault. The behavior is consistent with the outcome that discards all state changes (scope rollback).
+
+Since atomic scopes are not allowed to invoke compensation handlers explicitly, and are not allowed to enclose compensation handler, a compensation handler is never invoked from within an atomic scope, explicitly of from a default compensation handler or fault handler.
+
+<a name="AtomicScopesExtensionforBPEL-WebServiceInvocation"></a>
+# Web Service Invocation
+Atomic scopes are primarily used to provide all-or-nothing behavior that includes Web service invocations. As such they must use appropriate protocols that guarantee operations complete only if the scope completes, and rollback if the scope outcome is a rollback.
+
+<a name="AtomicScopesExtensionforBPEL-Request-ResponseOperations"></a>
+## Request-Response Operations
+The atomic scope invokes a service using a distributed transaction protocol (e.g. *WS-AtomicTransaction*) to propagate a transaction context to the invoked service. The invoked service enrolls in the transaction and participates in determining the transaction outcome. An atomic scope must use the same transaction context with all services invoked in that scope.
+
+An atomic scope that begins by receiving a message using a distributed transaction protocol must enroll in the transaction and participate in determining the outcome of that transaction. The atomic scope must then use that transaction context with all service invocations. If the scope begins without receiving a message, or receives a message without using a distributed transaction protocol, it creates its own transaction context.
+
+The following rules govern the outcome of the atomic scope and associated distributed transaction:
+
+1. *Commit* -- The atomic scope can complete, successfully or unsuccessfully, only if the transaction outcome has been determined to be *commit*.
+1. *Rollback on fault* -- If the atomic scope throws a fault, it must vote for the outcome of *rollback*. Therefore, it must determine that it can complete before allowing the transaction outcome of *commit*.
+1. *Fault on rollback* -- If the transaction outcome is *rollback* and the atomic scope has not thrown a fault, then it must throw the fault ```atomic:scopeRollback```.
+1. *Retry* -- In cases 2 and 3, when the atomic scope creates the transaction context, the implementation is allowed to rollback the transaction and execute the scope again using a different transaction context.
+
+The *invoke* activity is not allowed to use the ```atomic``` attribute as a shortcut for a scope. However, it is allowed to use the ```atomic``` attribute with the value ```no``` to invoke a service without using a distributed transaction protocol. Such an invocation does not affect the rules above, but could break the isolation and atomicity semantics of the distributed transaction.
+
+In either case, the service must be invoked using a synchronous protocol, such as sending the request and response messages over the same HTTP connection.
+
+<a name="AtomicScopesExtensionforBPEL-One-WayOperations"></a>
+## One-Way Operations
+The atomic scope invokes a service using a one-way operation by sending the message only if the scope completes. If the scope throws a fault, the message is discarded. No transaction context is propagated to the invoked service, since the transaction must commit before the message is sent.
+
+An atomic scope that receives a message from a one-way operation consumes the message only if the scope activity completes. If the scope throws a fault, the message is not consumed. As with one-way *invoke*, the one-way *receive* activity does not use a distributed transaction protocol.
+
+A message that was *consumed* will not be available again to the process. A message that was not consumed may be available again to be received by a different *receive* activity, or by the same *receive* activity if the atomic scope is restarted. The availability of messages not consumed is left up to the implementation, this specification does not address the possibility of message loss.
+
+<a name="AtomicScopesExtensionforBPEL-Concurrency"></a>
+## Concurrency
+Performing concurrent service invocations using the same transaction context can lead to a diamond scenario, whereby two services are operating on the same shared resource without any means to coordinate their work. Such scenarios are impossible to detect by looking at the process definition alone, and the risk from failure outweighs any benefits from allowing them.
+
+In addition, *assign* activities are not atomic when enclosed in an atomic scope. As such, atomic scopes are not allowed to perform basic activities concurrently. Atomic scopes that use parallel composition such as the *flow* and *foreach* activity must serialize all basic activities with respect to each other. Basic activities can assume they are not executed concurrently, but cannot assume any order of execution unless they use links to establish dependencies.
+
+<a name="AtomicScopesExtensionforBPEL-Appendix"></a>
+# Appendix
+Stuff that comes here:
+* Namespace URL.
+* Syntax for atomic attribute on scope/invoke.
+* Definition of atomic:rollback fault.
+* Reference to relevant specifications.
Added: ode/site/trunk/content/developerguide/eclipse-ide.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/eclipse-ide.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/eclipse-ide.mdtext (added)
+++ ode/site/trunk/content/developerguide/eclipse-ide.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,46 @@
+Title: Eclipse IDE
+Category: documentation
+
+<a name="EclipseIDE-DevelopingOdewiththeEclipseIDE"></a>
+## Developing ODE with the Eclipse IDE
+
+First, be sure to read [Building ODE](building-ode.html) to learn how to install Ruby, Rake and Buildr.
+
+
+<a name="EclipseIDE-1.BuildOde"></a>
+### 1. Build ODE
+
+At the root of the checkout, run
+
+ :::text
+ buildr package
+
+
+<a name="EclipseIDE-2.GeneratetheEclipseprojectfiles"></a>
+### 2. Generate the Eclipse project files
+
+Still in the root,
+
+ :::text
+ buildr eclipse
+
+
+<a name="EclipseIDE-3.ImportprojectsfilesintoEclipse"></a>
+### 3. Import projects files into Eclipse
+
+In Eclipse,
+
+ :::text
+ File -> Import -> Existing Projects into Workspace
+
+then select the root directory of your ODE checkout (e.g. ode/trunk)
+
+It's generally recommended to have a dedicated Eclipse workspace for ODE, since there's a fair amount of code and projects.
+
+<a name="EclipseIDE-RandomNotes"></a>
+### Random Notes
+
+* You must use JDK 5.0 compiler
+* You may need to exclude .svn directories to avoid duplicate resource copying.
+* You must define the M2_REPO classpath variable to point to your local Maven2 repository (Window -> Preference -> Java -> Build Path -> Classpath Variables)
+* Be ware that there are quite a few things in the Buildr-based build that are not done by the Eclipse build system. You will occasionally need to run "buildr" build in order to regenerate XMLBeans schemas, OpenJPA mapping files, JACOB channel interfaces, etc...
\ No newline at end of file
Added: ode/site/trunk/content/developerguide/index.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/index.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/index.mdtext (added)
+++ ode/site/trunk/content/developerguide/index.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,18 @@
+Title: Developer Guide
+Category: documentation
+
+<a name="DeveloperGuide-GeneralDocumentation"></a>
+## General Documentation
+
+These documents are intended for those of you wanting an in-depth look into ODE. You'll learn a bit more about our Web Services interfaces, our internal interfaces and how the engine works.
+
+* [Architectural Overview](architectural-overview.html)
+* ODE's virtual machine: [JaCOb](jacob.html)
+* Notes about using [Eclipse IDE](eclipse-ide.html) with Apache ODE
+* [Release Guidelines](release-guidelines.html)
+
+<a name="DeveloperGuide-Specifications"></a>
+## Specifications
+
+* [Stateful Exchange Protocol](stateful-exchange-protocol.html) Protocol for handling stateful interactions (aka automagic correlation).
+* [Atomic Scopes Extension for BPEL](atomic-scopes-extension-for-bpel.html)
Added: ode/site/trunk/content/developerguide/jacob.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/jacob.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/jacob.mdtext (added)
+++ ode/site/trunk/content/developerguide/jacob.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,519 @@
+Title: JaCOb – Virtual Processing Unit
+Category: documentation
+
+<a name="Jacob-Introduction"></a>
+## Introduction
+
+ODE's BPEL implementation relies on the JaCOb (Java Concurrent Objects) framework to implement the BPEL constructs. The framework provides the mechanism necessary to deal with two key issues in implementing BPEL constructs:
+
+1. Persistence of execution state.
+1. Concurrency.
+
+By rolling up these concerns in the framework, the implementation of the BPEL constructs can be simpler by limiting itself to implementing the BPEL logic and not the infrastructure necessary to support it.
+
+The approach we'll take in this tutorial is looking at the [rationale](#rationale) of JaCOb and its [concepts](#concepts) first. Then we'll illustrate with one complete [example](#example). But if you're a reverse reader, you can also decide to start with the [example](#example).
+
+<a name="rationale"></a>
+## Rationale behind the model
+
+Let's start from the most classical example of all:
+
+ :::java
+ void process(order) {
+ billingService.bill(order.billing);
+ shippingService.ship(order.product, order.shipping, self);
+ shipping = receive("shipping")
+ order.customer.send(shipping.details);
+ }
+
+
+It's Java like pseudo code that works extremely well, unless:
+
+* You fail somewhere in the middle and the customer has to order a second time.
+* Your have too many waiting threads and the VM crashes.
+
+So you change it to:
+
+ :::java
+ void process(order) {
+ billingService.bill(order.billing);
+ shippingService.ship(order.product, order.shipping, self);
+ listenOn("shipping", part2);
+ }
+
+ void part2(shipping) {
+ order.customer.send(shipping.details);
+ }
+
+
+That's almost better, but still has a lot of points of failure, where you're not sure if you actually billed the customer and shipped the product or not. So:
+
+ :::java
+ void process(order) {
+ billingService.bill(order.billing);
+ continue("part2");
+ }
+
+ void part2() {
+ shippingService.ship(order.product, order.shipping, self);
+ listenOn("shipping", part2);
+ }
+
+ void part2(shipping) {
+ order.customer.send(shipping.details);
+ }
+
+
+You're just fracturing the code with two primitives: *continue* which lets you persist state and go to the next one, and *listenOn* which lets you persist state and wait for an external event.
+
+Fracturing the code also addresses concurrency of execution even if you only have one thread. For example you could have a large number of 'process' calls to bill and ship an order. As we've broken down the whole treatment into several small parts, we can control when these separate parts actually get called and executed. And we're free to order them.
+
+Let's say we have a small process doing in a sequence:
+
+1. Invoke
+2. Receive
+3. Wait
+4. Invoke
+
+If we have 2 parrallel executions of this process and implement it in a simple way we'd have:
+
+1. Invoke1
+2. Receive1
+3. Wait1
+4. Invoke1
+5. Invoke2
+6. Receive2
+7. Wait2
+8. Invoke2
+
+However if we break down the code as shown above by introducing a "middle man" (or stack) and do not allow activities to directly call each other (or do not have the activity directly calling the sequence that directly calls the next activity) we could well obtain the following:
+
+1. Invoke1
+5. Invoke2
+2. Receive1
+3. Wait1
+6. Receive2
+7. Wait2
+4. Invoke1
+8. Invoke2
+
+From a client standpoint, we've achieved concurrency of execution even with one thread.
+
+Next step is adding links, fault handling/termination, compensation and event handlers and seeing that continue/listenOn is all you need. The last step is just adding implementation details.
+
+<a name="example"></a>
+## JaCOb Example
+
+Consider the issue of persistence. Imagine a simplified and naive implementation of the BPEL constructs ```<sequence>```, ```<wait>```, and ```<empty>```:
+
+ :::java
+ class Sequence extends Activity {
+ /** From BPEL Definition */
+ OSequence def;
+ ...
+ void run() {
+ for (OActivity child:def.children)
+ createActivity(child).run();
+ }
+ }
+
+ class Wait extends Activity {
+ /** From BPEL Definition */
+ OWait def;
+ ...
+ void run() {
+ Thread.wait(def.duration);
+ }
+ }
+
+ class Empty extends Activity {
+ /** From BPEL Definition */
+ OEmpty def;
+ ...
+ void run() {
+ // <empty> activity: do nothing.
+ }
+ }
+
+
+The above is the "natural" implementation of the constructs in the Java language. However, this implementation has some serious and obvious problems: the ```<wait>``` may specify a duration of days in which case a system failure during those days of waiting would mean that the process execution state would be lost. It would be nice to replace Thread.wait() in the Wait class with some sort of "suspend" operator that would save the execution state to disk.
+
+However there are practical issues to "suspending" to disk. At the point we wish to suspend, the call stack looks like:
+ :::java
+ Sequence.run()
+ Wait.run()
+
+In order to save the process to disk, we need to end the current thread of control which means popping both stack frames. To do this we have no choice but to require the implementation of Wait and Sequence to "cooperate" with this requirement thereby greatly complicating the implementation of those constructs. This also means that the "natural" implementation model cannot be used directly.
+
+JaCOb aims to solve this problem by providing an alternate "natural" model that allows execution state to be suspended ''without cooperation from the implementation classes''. The idea in JaCOb is to flatten the call stack and rely on explicit communication channels to handle control flow. We now consider a simplified JaCOb representation of our three BPEL activities:
+
+ :::java
+ class Empty {
+ OEmpty def;
+
+ /** channel we use to notify parent we are done. */
+ CompletionChannel myCompletionChannel;
+ ...
+ void run() {
+ // <empty> activity: do nothing...except to
+ // notify our parent that we are done.
+ myCompletionChannel.completed();
+ }
+ }
+
+ class Sequence {
+ OSequence def;
+ CompletionChannel myCompletionChannel;
+ ...
+ void run() {
+ // Start of by instantiating a sequential child runner for the first
+ // (0th) child...
+ instance(new SequenceChildRunner(0))
+ }
+
+ class SequenceChildRunner {
+ int currentchild;
+ SequenceChildRunner(int childNumber) { currentchild = childNumber; }
+ void run() {
+ if(currentChild == def.children.size()) {
+ // We are past the last child, the sequence is done.
+ myCompletionChannel.completed();
+ } else {
+ // We still have more children to run..
+
+ // Create a completion channel for our child.
+ CompletionChannel childCompletionChannel =
+ newChannel(CompletionChannel.class);
+
+ // create a child activity based on the activity type
+ // and parameterized with the model and the completion
+ // channel we just created
+ Activity childActivity =
+ createActivity(def.children.get(currentChild),
+ childCompletionChannel);
+
+ // instantiate the child activity
+ instance(childActivity);
+
+ // create an object to wait for the "completed()" notification
+ // from the child activity.
+ object(new CompletionChannelML(childCompletionChannel)) {
+ void completed() {
+ // Ok, finished with the child, create a runner
+ // to do the next child.
+ instance(new SequenceChildRunner(currentChild+1));
+ }
+ }
+ }
+ }
+ }
+ }
+
+ class Wait extends Activity {
+ OWait def;
+ CompletionChannel myCompletionChannel;
+
+ ...
+ void run() {
+ // Create a channel for an externally managed alarm.
+ TimerChannel timerChannel = newChannel(TimerChannel.class);
+ // register the alarm with the runtime.
+ getRuntimeContext().registerTimer(timerChannel, def.duration);
+
+ // create an object to wait for the alarm and then send an
+ // activity completed message to our parent.
+ object(new TimerChannelML(timerChannel) {
+ onTimer() {
+ myCompletionChannel.completed();
+ }
+ });
+
+ }
+ }
+
+
+So JaCOb constructs help us in breaking the execution stack.
+
+<a name="concepts></a>
+## Main JaCOb Concepts
+
+<a name="Jacob-Channels"></a>
+### Channels
+
+As briefly demonstrated above, channels are interfaces used for communication between activities in ODE engine. There are several types of channels like TerminationChannel, ParentScopeChannel or CompensationChannel (their respective purpose should be obvious from their name). Some basic channels are provided to all activities when they're created to allow them to interact with their environment. When an activity wants to notifies its parent that it has terminated for example, it just calls its parent TerminationChannel (see the Empty example above).
+
+Don't look for channels implementations because there are none. Channels implementation is provided through a dynamic proxy (see [ChannelFactory](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/vpu/ChannelFactory.java).createChannel() and [ChannelFactory](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/vpu/ChannelFactory.java).ChannelInvocationHandler for more). That's one of the levels of decoupling between invocation and actual execution in JaCOb.
+
+<a name="Jacob-JacobObject/JacobRunnable"></a>
+### JacobObject / JacobRunnable
+
+If you don't care much about the details, the bottom line is: a [JacobObject](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/JacobObject.java) and an [JacobRunnable](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/JacobRunnable.java) are just a method implementation. This method gets executed when the abstraction is executed.
+
+A JacobObject is meant to be a closure. From Wikipedia: "A closure combines the code of a function with a special lexical environment bound to that function (scope). Closure lexical variables differ from global variables in that they do not occupy the global variable namespace. They differ from object oriented object variables in that they are bound to functions, not objects.". Normally closures aren't supported in Java so [JacobObject](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/JacobObject.java) tries to feel that gap. But it's not a true closure anyway, which makes thing easier. Closures in JaCOb are statically coded, whereas in most languages supporting closures these are dynamic. So basically in JaCOb, a closure is expected to implement some methods and provides other utility methods to manipulate channels and replicate itself.
+
+[JacobRunnable](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/JacobRunnable.java) is just a JacobObject that requires the implementation of only one method: run(). As ''all activities inherit from [JacobRunnable](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/JacobRunnable.java) they're all supposed to implement their main processing in this run() method. Their initialization occur in their respective constructors.
+
+<a name="Jacob-MethodLists(MLs)"></a>
+### Method Lists (MLs)
+
+ML classes can be seen as the other end of a channel. Only they're not invoked directly when one calls a channel method, but only once the JaCOb engine has popped the channel invocation from its internal stack (again you can see how the execution stack gets broken here).
+
+Usually MLs implementations in ODE are inlined because it's just easier to declare them in the activities run() method. For example if you look at the Sequence example shown above you'll see something like:
+
+ :::java
+ void run() {
+ ...
+ // create an object to wait for the "completed()" notification
+ // from the child activity.
+ object(new CompletionChannelML(childCompletionChannel)) {
+ void completed() {
+ // Ok, finished with the child, create a runner
+ // to do the next child.
+ instance(new SequenceChildRunner(currentChild+1));
+ }
+ }
+ }
+ }
+
+
+The object method here is inherited from !JacobObject and is just a way to hand our ML to JaCOb. So that the JaCOb runtime can match it with an incoming channel message later on.
+
+## VPU and ExecutionQueue
+
+The [VPU](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/vpu/JacobVPU.java) is where all the JaCOb processing is occuring. When a JacobObject is injected inside the VPU, it's actually registered as a [Continuation](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/soup/Continuation.java), which is just wrapping the JacobObject with the method to call on the JacobObject to execute it (in our case always the run() method as we're only dealing with JacobRunnable instances).
+
+The [ExecutionQueue](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/soup/ExecutionQueue.java) (and its implementation [FastExecutionQueueImpl](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/vpu/FastExecutionQueueImpl.java)) is just a container for all the artifacts managed by the VPU (mostly channels and reactions) to organize them in queues where artifacts can be pushed and popped. It also records some execution statistics.
+
+So the VPU main processing is just dequeuing a reaction from the soup and executing it by calling its abstraction's run() method (remember that the reaction just wraps an abstraction). That's all (check [JacobVPU](http://svn.apache.org/repos/asf/ode/trunk/jacob/src/main/java/org/apache/ode/jacob/vpu/JacobVPU.java).execute(), you'll see that I'm not lying). However when the JacobRunnable (usually an activity) gets executed the following things can happen:
+
+* if other abstractions (usually other activities) are created, they will be appended to the reaction queue,
+* if new channels are created, they will be saved for later usage,
+* if channels are invoked, the message will be saved to match against a new ML,
+* if a new ML instance is created, it will be submitted to the VPU that will try to match it against a channel invocation.
+
+The VPU is also responsible for persisting its internal state. So when an execution stops (for example our process has reach a receive) the VPU state is serialized and saved for later reuse. This logic can be seen in [RuntimeContextImpl](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/RuntimeContextImpl).execute().
+
+There's one more thing that should be mentioned here. Continuations (and hence JacobRunnables) don't "stay" in the VPU queues. They just get popped, executed and that's it. So if an abstraction must last more than one execution, it should simply fork itself. This explains why in our Sequence example already pasted above we see the line:
+
+ :::java
+ instance(new SequenceChildRunner(currentChild+1));
+
+This simple adds a new !ChildRunner that will monitor the next child completion. If you browse ODE's activities code you will even find things like instance(this) which directly enqueues a new instance of the same JaCOb abstraction.
+
+<a name="Jacob-Walkingthroughexamples"></a>
+## Walking through examples
+
+<a name="Jacob-While"></a>
+### While
+
+ :::xml
+ <process name="while1"
+ targetNamespace="http://ode/bpel/unit-test"
+ xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
+ xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
+ xmlns:tns="http://ode/bpel/unit-test"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:test="http://ode/bpel/unit-test.wsdl"
+ suppressJoinFailure="yes">
+ <partnerLinks>
+ <partnerLink name="testPartnerLink"
+ partnerLinkType="test:TestPartnerLinkType"
+ myRole="me" />
+ </partnerLinks>
+
+ <variables>
+ <variable name="var1" messageType="test:TestMessage2"/>
+ </variables>
+
+ <sequence>
+ <receive
+ createInstance="yes"
+ name="startReceive"
+ partnerLink="testPartnerLink"
+ portType="test:TestPortType"
+ operation="testOperation"
+ variable="var1"/>
+ <while condition="bpws:getVariableData('var1', 'TestPart') < 10">
+ <assign>
+ <copy>
+ <from expression="bpws:getVariableData('var1', 'TestPart') + 1"/>
+ <to variable="var1" part="TestPart"/>
+ </copy>
+ </assign>
+ </while>
+ <reply name="endReply"
+ operation="testOperation"
+ partnerLink="testPartnerLink"
+ portType="test:TestPortType"
+ variable="var1"/>
+ </sequence>
+ </process>
+
+Everything starts with a receive. So our entry point here in our JaCOb-focused discussion is going to be [BpelProcess](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/BpelProcess.java).PartnerLinkMyRoleImpl.inputMsgRcvd(). The code that matters to us now is the following (executed when a message is targeted at a createInstance receive):
+
+ :::java
+ BpelRuntimeContextImpl instance = createRuntimeContext(newInstance, new PROCESS(_oprocess), messageExchange);
+ ...
+ // run the vpu
+ instance.execute();
+
+
+If you check the code executed by !BpelRuntimeContextImpl constructor you'll see among other things the following:
+
+ :::java
+ if (PROCESS != null) {
+ vpu.inject(PROCESS);
+ }
+
+
+The process itself get injected. When executed, [PROCESS](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/PROCESS.java) just instantiates a scope to control the execution of its child activity and starts listening on compensation and completion channel. From the process we go to a scope, then our main sequence and finally our receive.
+
+Receives are just mapped to a pick onMessage so its JaCOb implementation should be looked for in [PICK](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/PICK.java). The [PICK](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/PICK.java) is just about isolating the right correlations and selecting a message for it, then waiting for the message. In our createInstance case we'll be more interested in the following code, located in [BpelRuntimeContextImpl](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/BpelRuntimeContextImpl.java).select() (and called by PICK):
+
+ :::java
+ if (_instantiatingMessageExchange != null && _dao.getState() == ProcessState.STATE_READY) {
+ for (int i = 0 ; i < correlators.size(); ++i) {
+ CorrelatorDAO ci = correlators.get(i);
+ if (ci.equals(_dao.getInstantiatingCorrelator())) {
+ inputMsgMatch(pickResponseChannelStr, i, _instantiatingMessageExchange);
+ return;
+ }
+ }
+ }
+
+Which just happens to call something like:
+
+ :::java
+ vpu.inject(new JacobRunnable() {
+ public void run() {
+ PickResponseChannel responseChannel = importChannel(responsechannel, PickResponseChannel.class);
+ responseChannel.onRequestRcvd(idx, mex);
+ }
+ });
+
+
+That's where things really start. When injected, this abstraction just calls the response channel for our receive. The other side of this channel is implemented as a ML in the [PICK](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/PICK.java):
+
+ :::java
+ object(false, new PickResponseML(_pickResponseChannel) {
+ public void onRequestRcvd(int selectorIdx, Object msgex) {
+ ...
+ ActivityInfo child = new ActivityInfo(genMonotonic(), onMessage.activity, _self.self, _self.parent);
+ instance(createChild(child,_scopeFrame,_linkFrame));
+ }
+ });
+
+This method just does what a receive needs to do (like variable and correlation initialization) and creates a new child. When dealing with a real pick, this child would be the onMessage activity, however in the case of a receive, this is an empty activity. So when does our receive completes? Well, when the child completes. As you can see on the child constructor, we're passing the same ParentScopeML that we've been provided. So when the child completes, the receive's parent is notified which means to our receive doesn't need to do it itself. And an empty immediately completes:
+
+ :::java
+ _self.parent.completed(null, CompensationHandler.emptySet());
+
+The parent sequence gets notified almost immediately after the onRequestRcvd() methods finishes.
+
+Now how does our sequence gets the control back? Well, once again, let's look at the ML, the other side of the channel. As one of the most important job of the VPU is matching channels invocations and MLs, we'll get to the [sequence](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/SEQUENCE.java) by its ParentScopeML implementation:
+
+ :::java
+ class SEQUENCE extends ACTIVITY {
+ ...
+ private class ACTIVE extends BpelJacobRunnable {
+ ....
+ public void run() {
+ ...
+ object(new ParentScopeML(_child.parent) {
+ public void compensate(OScope scope, SynchChannel ret) {
+ _self.parent.compensate(scope,ret);
+ instance(ACTIVE.this);
+ }
+
+ public void completed(FaultData faultData, Set<CompensationHandler> compensations) {
+ HashSet<CompensationHandler> comps = new HashSet<CompensationHandler>(_compensations);
+ comps.addAll(compensations);
+ if (faultData != null || _terminateRequested || _remaining.size() <= 1) {
+ _self.parent.completed(faultData, comps);
+ } else /* !fault && ! terminateRequested && !remaining.isEmpty */ {
+ ArrayList<OActivity> remaining = new ArrayList<OActivity>(_remaining);
+ remaining.remove(0);
+ instance(new SEQUENCE(_self, _scopeFrame, _linkFrame, remaining, comps));
+ }
+ }
+ }));
+ }
+ }
+ ...
+ }
+
+The method that will get executed is of course the completed() method. It simply completes if a fault has been thrown, a termination has been requested and if no child activities remain. Being of an optimistic nature, we'll check what happens when everything goes just fine. In this second case a remaining activity is removed and the [SEQUENCE](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/SEQUENCE.java) abstraction itself is reinstantiated. Which leads us to what the [SEQUENCE](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/SEQUENCE.java) does:
+
+ :::java
+ public void run() {
+ final ActivityInfo child = new ActivityInfo(genMonotonic(),
+ _remaining.get(0),
+ newChannel(TerminationChannel.class), newChannel(ParentScopeChannel.class));
+ instance(createChild(child, _scopeFrame, _linkFrame));
+ instance(new ACTIVE(child));
+ }
+
+
+As you can see, it just instantiates the next child abstraction and also another abstraction named ACTIVE. So what's this ACTIVE that we've already seen a bit before? Well, it's just the abstraction that keeps on following child activities when they execute. It's more like a convention on all containment-based activity in ODE (while, sequence, pick, ...) that the main activity abstraction just kicks off the processing. Then an ACTIVE (also sometimes called WAITER) abstraction takes care of following the children.
+
+Continuing to the next step, we've just instantiated an abstraction for the [while](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/WHILE.java) in our example process, as it's the next child of the sequence. So what happens there?
+
+ :::java
+ public void run() {
+ boolean condResult = false;
+ try {
+ condResult = checkCondition();
+ } catch (FaultException fe) {
+ _self.parent.completed(createFault(fe.getQName(), _self.o),_compHandlers);
+ return;
+ }
+ if (condResult) {
+ ActivityInfo child = new ActivityInfo(genMonotonic(),
+ getOWhile().activity,
+ newChannel(TerminationChannel.class), newChannel(ParentScopeChannel.class));
+ instance(createChild(child, _scopeFrame, _linkFrame));
+ instance(new WAITER(child));
+ } else /* stop. */ {
+ _self.parent.completed(null, _compHandlers);
+ }
+ }
+
+
+Now you should be getting more familiar with that sort of code. First step is evaluating the [while](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/WHILE.java) condition. If it turns out it's true, then a child abstraction gets created as well as a WAITER to follow its execution. The WAITER implementation is again pretty straightforward:
+
+ :::java
+ private class WAITER extends BpelJacobRunnable {
+ private ActivityInfo _child;
+ private boolean _terminated;
+
+ WAITER(ActivityInfo child) {
+ _child = child;
+ }
+
+ public void run() {
+ object(false, new TerminationML(_self.self) {
+ public void terminate() {
+ _terminated = true;
+ _child.self.terminate();
+ instance(WAITER.this);
+ }
+ }.or(new ParentScopeML(_child.parent) {
+ public void compensate(OScope scope, SynchChannel ret) {
+ _self.parent.compensate(scope,ret);
+ instance(WAITER.this);
+ }
+ public void completed(FaultData faultData, Set<CompensationHandler> compensations) {
+ _compHandlers.addAll(compensations);
+ if (_terminated || faultData != null)
+ _self.parent.completed(faultData, compensations);
+ else
+ instance(WHILE.this);
+ }
+ }));
+ }
+ }
+
+
+Termination and compensation aren't doing anything really interesting. Completion, just like for the sequence, re-instantiates the [WHILE](http://svn.apache.org/repos/asf/ode/trunk/bpel-runtime/src/main/java/org/apache/ode/bpel/runtime/WHILE.java) abstraction. And that's how we get our loop, by re-instantiating the main WHILE abstraction (again evaluating the condition and creating a child if it's true).
+
+Finally, when the while condition becomes false, it notifies its parent channel. The sequence then goes to our last activity: reply. As expected, the reply replies, just sending the variable content and notifying its parent for completion. The sequence has no more children to execute so it also notifies its own parent, which is the process. We then just declare the process to be completed and that's it! We're done!
Added: ode/site/trunk/content/developerguide/release-guidelines.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/release-guidelines.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/release-guidelines.mdtext (added)
+++ ode/site/trunk/content/developerguide/release-guidelines.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,47 @@
+Title: Release Guidelines
+Category: documentation
+
+<a name="ReleaseGuidelines-CheckList"></a>
+## Check List
+
+These guidelines are extracted from the [incubator release guidelines](http://incubator.apache.org/guides/releasemanagement.html#rules) and other projects (like [Avalon](http://wiki.apache.org/avalon/AvalonReleaseManagerHowto)) guidelines and are meant to be used as a reference for coming releases. It's not really a todo list for the next release (that will be handled in JIRA) but a general list of things to have right and the places they're best described.
+
+* Analyze the list of bugs left for this specific release. Assess whether they're critical for the release or can be postponed to a subsequent release.
+* The released archives should have "apache" and "ode" in their naming.
+* A release should include both a source and a binary package.
+* The source distro should include a BUILDING document.
+* make sure the RELEASE_NOTES are up to date (version number, list of issues, links to JIRA, etc)
+* Both distros should include a RELEASE_NOTES, the LICENSE
+* Different distribution types should unpack to directories with different names (say apache-ode-x.x and apache-ode-src-x.x).
+* Our releases don't include general documentation (only Javadoc) but a link to our website main documentation pages in the README.
+* All our jars must include in the META-INF the LICENSE, the NOTICE, a [valid](http://jakarta.apache.org/commons/releases/prepare.html#checkjarmanifest) MANIFEST.
+* The NOTICE file must include: the standard Apache attribution and copyright notice, inherited copyright and attributions notices, all attribution and copyright notices required by licenses for third party documents.
+* Releases should be built from tagged versions named APACHE_ODE_X_X (roughly same as the release itself but in capital to mark it different from other tags).
+* All our source files should include the legal Apache header.
+* The Java version should be clearly indicated either in README or RELEASE_NOTES (in addition to the MANIFEST).
+
+
+<a name="ReleaseGuidelines-Verifyingtherelease"></a>
+## Verifying the release
+
+A complete [check list](http://incubator.apache.org/guides/releasemanagement.html#check-list).
+
+<a name="ReleaseGuidelines-ReleaseProcess"></a>
+## Release Process
+
+Before the release is finalized, successive releases can be made release candidates. It is traditional that release managers use their Apache home space to make available release candidates. Release [signatures](http://www.apache.org/dev/release-signing.html) should be included.
+
+Once the release has been cut, a vote should be done by the PPMC to validate the release. Once approved by the PPMC another vote must be done by the Incubator PMC for release final approval. This should be done on the incubator general mailing list and include a link to the release artifacts, a link to the PPMC release vote thread and a link to the tag from which the release has been cut. 3 binding +1s are required by members of the Incubator PMC.
+
+<a name="ReleaseGuidelines-AnnouncingTheRelease"></a>
+## Announcing The Release
+
+1. Perform a release in JIRA and create a new release version in JIRA
+1. Update the download page for the release on the Website
+1. Mail the dev & user lists, and announce@apache.org
+1. Post a news entry on the Website
+1. Have a beer!
+
+Announcements should be signed by the release manager with the key used to sign the release. Note that this may mean creating a plain text signature on the machine used to sign the release and then transferring this.
+
+Announcements should be posted from the release manager's apache.org address.
\ No newline at end of file
Added: ode/site/trunk/content/developerguide/stateful-exchange-protocol.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/developerguide/stateful-exchange-protocol.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/developerguide/stateful-exchange-protocol.mdtext (added)
+++ ode/site/trunk/content/developerguide/stateful-exchange-protocol.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,114 @@
+Title: Stateful Exchange Protocol
+Category: documentation
+
+<a name="StatefulExchangeProtocol-1.General"></a>
+## 1. General
+
+\[TBD: Insert overview of the world before and after automagic correlation\]
+
+<a name="StatefulExchangeProtocol-2.StateIdentifiers"></a>
+## 2. State Identifiers
+
+A common use case consists of a client that needs to invoke multiple operations against the same service. Each operation depends on the state resulting from the completion of the previous operation. The service needs to associate these invocations with states it maintains internally. That's the basis for the State Exchange protocol.
+
+In the initial invocation, the client sends a request to the service. The service returns a response that includes a *state identifier*. The state identifier is opaque to the client, however, the client knows to use that state identifier in subsequent invocations that depend on the state of the pervious invocation.
+
+In a subsequent invocation, the client sends a request to the service and includes the state identifier. The service is able to associate this request with thwe state reached by the previous request.
+
+The exact mechanism for carrying the state identifier depends on the underlying transport protocol and the message wire format. This specification provides bindings for SOAP and HTTP.
+
+The protocol requires an initial two-way operation, followed by any combination of two-way and one-way operations.
+
+The service can decide how long to keep an association between the state identifier and any internal state, and how to deal with failure conditions that may result in loss of state. A service should express its ability to maintain state association through its policy.
+
+The service responds with an error if it expects to receive a state identifier and does not find one in the message, or if it cannot associate the state identifier with any known state.
+
+Unless specified otherwise, the client expects to receive the same state identifier in subsequent invocations of the service. The client may detect an error condition if it sends one state identifier and receives another. Unless specified otherwise, the client may conclude that the state identifier is no longer associated with any state if it receives a response that does not include a state identifier.
+
+Although the state identifier is opaque to the client, the client can compare state identifiers for equivalence. Two state identifiers are equivalent if they contain the same set of characters.
+
+Services are encouraged to create unique identifiers for each internal state using globally unique identifiers. In doing so, they prevent accidental association of two unrelated states.
+
+<a name="StatefulExchangeProtocol-3.StatefulEPRs"></a>
+## 3. Stateful EPRs
+
+Some interactions involve more than one client or more than one service. These interactions require the clients and services to communicate stateful EPRs.
+
+A *stateful EPR* is an EPR that contains all the information necessary to invoke a service in association with a particular state. A stateful EPR is essentially an EPR that incorporates a state identifier. For example, when using WS-Addressing, the stateful EPR will include the state identifier as a reference property.
+
+The client obtains the stateful EPR in one of three ways:
+* By composition.
+* From a header or the body of the message.
+* From the state callback header.
+
+When using WS-Addressing, the client can compose the stateful EPR by combining the service EPR and the state identifier, using the state identifier as a reference property.
+
+All addressing mechanisms support stateful EPRs. However, not all addressing mechanisms allow the client to compose stateful EPRs. For example, when using the HTTP protocol bindings, only the service can construct stateful EPRs.
+
+The service may also send a stateful EPR in a header or the body of the message. The service may send its own stateful EPR, or the stateful EPR of a different service (see _Shared States_). The state callback header is a special case of that (see _State Callback_).
+
+<a name="StatefulExchangeProtocol-4.SharedStates"></a>
+## 4. Shared States
+
+There are cases where two or more services share a common state. This non-normative part of the specification provides guidelines for implementing such scenarios.
+
+For example, a process may implement two services that both affect the same process instance (internal state). The client invokes operations on the first service against the same process instance by using one state identifier. The client then needs to invoke operations on the second service against the same process instanace.
+
+The two services use different EPRs, and the client may not be able to deduct one stateful EPR from the other. In fact, it is highly recommended that the two stateful EPRs use different state identifiers. Instead, the first service obtains the stateful EPR of the second service and sends it to the client.
+
+In this case, the first service obtains the stateful EPR of the second service and sends it to the client.
+
+For example, a BPEL process may receive a request on one partnerLink, assign the myRole EPR of another partnerLink to a message and reply with that message. After extracting the EPR from the message, the client is able to invoke the same process instance using the second partnerLink.
+
+To support this pattern we recommend that a BPEL implementation construct a stateful EPR for a partnerLink myRole on or before first use. First use occurs when that partnerLink myRole is assigned to a variable, or communicated in the header of a message by a process instance. Once set, the stateful EPR remains the same until discarded by the process instance.
+
+<a name="StatefulExchangeProtocol-5.StateCallback"></a>
+## 5. State Callback
+
+There are may ways in which services can be combined using stateful message exchanges. A common pattern consists of a two-way exchange between two services acting as peers invoke each other. This pattern is common enough that the State Exchange protocol introduces a specific header to cater for it.
+
+The State Exchange protocol supports this pattern using *state callback headers*. State callback headers are sent in addition to state identifiers to provide a callback address. They are used to associate two states with each other.
+
+In the initial invocation, the first service constructs a stateful EPR and sends it as a state callback header. The second service returns a response with a state identifier. In a subsequent invocation, the first service uses that state identifier to invoke the second service.
+
+The second service may also follow up with an invocation of the first service using the stateful EPR provided in the state callback header. In this manner, both services can invoke each other within the same interaction.
+
+Both services maintain their own internal states and use separate state identifiers. The state association results from invocations that, regardless of direction, refer to both internal states.
+
+In order to support addressing schemes that do not allow the client to compose a stateful EPR, a service may return a callback state header in lieu of, or in addition to the state identifier. The client may then choose whether to use the state identifier or stateful EPR for subsequent invocations of that service.
+
+<a name="StatefulExchangeProtocol-6.Fail-fastMechanism"></a>
+## 6. Fail-fast Mechanism
+
+TBD: Cleanup
+
+An important characteristic of the State Exchange protocol is that clients and servers must be aware whether the interaction is in fact stateful. Reaching that decision is not always possible, but for the benefit of protocols that allow it, we introduce a fail-fast mechanism.
+
+When the client sends a message to the service that does not require the state identifier or state callback header, it may use the *state use* header instead. This header informs the service that the client supports state exchange. The client may also force the service to process the header (e.g. using the SOAP _mustUnderstand_ attribute) to guarantee that the service supports state exchange.
+
+<a name="StatefulExchangeProtocol-7.SOAPBindings"></a>
+## 7. SOAP Bindings
+
+When using SOAP, the state identifier is sent in the header `state:identifier` and the callback EPR is sent in the header `state:callback`. If the message does not contain either header, it may use the `state:use` header to indicate support for the State Exchange protocol.
+
+The `state:identifier` header is an element of type xsd:string that contains an opaque identifier.
+
+The `state:callback` header is an element of type `wsa:EndpointReference` that contains a WS-Addressing EPR. It must contain the reference property state:identifier.
+
+The `state:use` header is an element of type `xsd:boolean` that must contain the value true.
+
+The `state:identifier` header must be present in any response message, as long as the service can maintain an association for that state identifier. A response message that does not include the state:identifier header signals to the client that the service no longer accepts that state identifier.
+
+A client can compose the stateful EPR of a service by combining the service EPR with the `state:identifier` header, using it as a reference property. When it sends a message to the service, it uses the service EPR and copies the state:identifier element to the header of the SOAP message. In doing so, it fulfills the requirements of both WS-Addressing and State Exchange protocol.
+
+To fail fast is the protocol is not supported, clients are encouraged to use the mustUnderstand attribute to force the service to process state headers. Services are encourage to look for the existence of a state header to determine if the client supports the State Exchange protocol. Additional checking can be done on response messages.
+
+The following table summarizes SOAP faults used by the State Exchange protocol:
+<table class="table table-bordered">
+ <tbody>
+ <tr><td>`state:missingIdentifier`</td><td>The service expects to receive a state identifier and did not find one in the message.</td></tr>
+ <tr><td>`state:noSuchState`</td><td>The state identifier is not associated with any internal state maintained by the service.</td></tr>
+ <tr><td>`state:missingHeader`</td><td>The service expects a state exchange and the client did not provide any state header.</td></tr>
+ <tr><td>`state:invalidCallback`</td><td>The `state:callback` header cannot be used as an endpoint reference.</td></tr>
+ </tbody>
+</table>
\ No newline at end of file
Added: ode/site/trunk/content/userguide/index.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/userguide/index.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/userguide/index.mdtext (added)
+++ ode/site/trunk/content/userguide/index.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,50 @@
+Title: User Guide
+
+<a name="UserGuide-GettingStarted"></a>
+## Getting Started
+
+First of all, getting familiar with the [WS-BPEL 2.0](../ws-bpel-20.html) standard is a very good idea. To use ODE, you will need to write processes using the BPEL language. There are several examples in our [distributions](../getting-ode.html) that you can use to get started, but a decent understanding of the spec is assumed.
+
+Then, you can optionally check out [ODE Schema](../ode-schema.html) page in order to install schema for your database. Please note that schemas from distribution sometimes contain errors, because of poor quality of ORM schema generators.
+
+ODE can be deployed in three different environments:
+
+* As a simple Web Service in Axis 2, ODE is bundled in a WAR than can be deployed in any application server and is invoked using plain SOAP/HTTP.
+* As a JBI service assembly, ODE is bundled in a ZIP that can be deployed in any JBI container and is invoked using the NMR.
+* SMX4 OSGi bundle
+
+<a name="UserGuide-Installation"></a>
+## Installation
+1. [WAR Deployment](war-deployment.html)
+1. [JBI Deployment](jbi-deployment.html)
+1. [SMX4 OSGi Deployment](smx4-osgi-deployment.html)
+1. [Upgrading ODE](upgrading-ode.html)
+
+<a name="UserGuide-UsingOde"></a>
+## Using ODE
+1. [Creating a Process](creating-a-process.html)
+1. [Process Versioning](process-versioning.html)
+1. [Management API](management-api.html)
+1. [Instance Replayer](instance-replayer.html)
+1. [ODE Execution Events](ode-execution-events.html)
+1. [Endpoint References](endpoint-references.html)
+1. [WSDL 1.1 HTTP Binding Support](wsdl-1.1-http-binding-support.html)
+1. [WSDL 1.1 Extensions for REST](wsdl-1.1-extensions-for-rest.html)
+1. [BPEL Extensions](bpel-extensions.html)
+1. [Instance Data Cleanup](instance-data-cleanup.html)
+1. [Direct Process-to-Process Communication](direct-process-to-process-communication.html)
+1. [Stateful Exchange Protocol](stateful-exchange-protocol.html)
+1. [Activity Failure and Recovery](activity-failure-and-recovery.html)
+1. [XQuery Extensions](xquery-extensions.html)
+1. [Atomic Scopes Extension for BPEL](atomic-scopes-extension-for-bpel.html)
+
+<a name="UserGuide-HowTo"></a>
+## How To
+1. [ODE Jbi and Axis2 properties overview](ode-jbi-and-axis2-properties-overview.html)
+1. [Controlling ODE's Memory Footprint](controlling-ode's-memory-footprint.html)
+1. [Endpoint Configuration](endpoint-configuration.html)
+1. [HTTP Authentication](http-authentication.html)
+1. [Using a JNDI DataSource under ServiceMix JBI](using-a-jndi-datasource-under-servicemix-jbi.html)
+1. [Writing BPEL Test Cases](writing-bpel-test-cases.html)
+1. [WS-Security in ODE](ws-security-in-ode.html)
+1. [Use Assign to build messages](use-assign-to-build-messages.html)
Added: ode/site/trunk/content/userguide/jbi-deployment.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/userguide/jbi-deployment.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/userguide/jbi-deployment.mdtext (added)
+++ ode/site/trunk/content/userguide/jbi-deployment.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,123 @@
+Title: JBI Deployment
+
+## Overview
+Here's a quick overview to deploy PXE/ODE on a JBI container (e.g. [ServiceMix](http://servicemix.apache.org))
+
+<a name="JBIDeployment-1)DownloadtheJBIdistribution"></a>
+## 1) Download the JBI distribution
+
+Check our [download page](getting-ode.html) and get the latest JBI-based distribution. Unzip it in a directory of your choice. We'll now refer to this directory as ODE_HOME.
+
+<a name="JBIDeployment-2)InstallonJBIcontainer"></a>
+## 2) Install on JBI container
+
+For example, with ServiceMix you can use file-system deployment:
+
+ :::text
+ (from ode/jbi directory)
+ cp ODE_HOME/ode-jbi-1.1.zip SERVICEMIX_DIR/install
+
+The above will result in ODE being installed with the default settings. You may wish to first modify the `ode-jbi.properties` file found in the root of the installer ZIP.
+
+<a name="JBIDeployment-3)DeployingProcesses"></a>
+### 3) Deploying Processes
+
+We are assuming that the reader is familiar with JBI deployment concepts. Deploying a process consists of the following steps:
+
+1. Create a temporary _service unit_ directory for the BPEL processes
+1. Place the relevant `.bpel`, `.wsdl` and `.xsd` files into the temporary directory
+1. Create an ODE deployment descriptor (`[deploy.xml](deploy.xml.html)`) and place it in the temporary directory
+1. (Optional) Compile the the BPEL processes using the `[bpelc](bpelc.html)` command.
+1. Zip up the contents of the temporary directory into a service unit archive
+1. Create a temporary _service assembly_ directory
+1. Place the service unit archive in a temporary _service assembly_ directory
+1. Update the service assembly's `jbi.xml` descriptor
+1. Zip up the contents of the service assembly directory into a service assembly archive
+1. Copy the service assembly archive into the appropriate _deploy_ directory
+
+<a name="JBIDeployment-Examples"></a>
+## Examples
+
+Some JBI examples are available under the _examples_ directory of the ODE distro:
+
+* HelloWorld2
+* PingPong
+* Async2
+
+Extract the distro-jbi-2.0-SNAPSHOT.zip created in the build instructions above.
+
+To compile the examples, you may wish to define the ODE_HOME environment variable. The build script does a good job of figuring this out without ODE_HOME set, however.
+
+ :::text
+ # On Linux/Unix
+ export ODE_HOME=/path/to/ode/distribution
+
+ # On Windows
+ set ODE_HOME=C:\Path\To\ODE\Distribution
+
+and run Ant in the example's directory:
+
+ ::text
+ cd %ODE_HOME%/examples/PingPong
+ ant
+
+This will create a JBI service assembly in the "build" subdirectory. With ServiceMix you can simply copy it to the file-system hot deployment directory:
+
+ :::text
+ (from PingPong directory)
+ cp build/PingPing-sa.zip SERVICEMIX_DIR/deploy
+
+Finally, you can test the example by typing:
+
+ :::text
+ (from PingPong directory)
+ ant test
+
+
+<a name="JBIDeployment-JBIEndpoints"></a>
+## JBI Endpoints
+
+ODE now relies strictly on abstract web service definitions (i.e., without binding/service/port definitions), meaning that you only need abstract WSDLs when compiling processes. Since JBI uses normalized messages (in theory, at least), there is no need to define bindings for the BPEL service engine.
+
+In deploy.xml, you simply define the JBI internal endpoints invoked or provided by your partnerLinks,
+
+ :::xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
+ xmlns:process="urn:/Ping.bpel"
+ xmlns:ping="urn:/Ping.wsdl"
+ xmlns:pong="urn:/Pong.wsdl">
+
+ <process name="process:Ping">
+ <active>true</active>
+ <provide partnerLink="PingPartnerLink">
+ <service name="ping:PingService" port="PingPort"/>
+ </provide>
+ <invoke partnerLink="PongPartnerLink">
+ <service name="pong:PongService" port="PongPort"/>
+ </invoke>
+ </process>
+
+ </deploy>
+
+
+One may use JBI binding components to make services externally available and therefore providing concrete bindings to those binding components. An example of exposing process services via SOAP/HTTP can be found in the PingPong [ping-http service unit](http://svn.apache.org/repos/asf/ode/branches/APACHE_ODE_1.X/distro/src/examples-jbi/PingPong/ping-http/).
+
+<a name="JBIDeployment-Database"></a>
+## Database
+
+The generated installer will use an internally-managed embedded Derby database. No configuration is required. To use an external database one needs to modify `ode-jbi.properties` found in the component installer zip.
+
+<a name="JBIDeployment-CompatibilityCaveat"></a>
+## Compatibility Caveat
+
+Many binding components are not very good about delivering messages in the correct format for WSDL11 services.
+
+<a name="JBIDeployment-KnownIssueswithServiceMix"></a>
+### Known Issues with ServiceMix
+
+ServiceMix' so-called _lightweight components_ make it difficult to properly expose process services since they do not fully implement the JBI contract and do not allow the process engine to enquire about its external endpoints.
+* SoapHelper needs to properly resolve the WSDL operation name (patch available)
+[https://issues.apache.org/activemq/browse/SM-488](https://issues.apache.org/activemq/browse/SM-488)
+
+* The servicemix-http binding component does not normalize messages
Added: ode/site/trunk/content/userguide/smx4-osgi-deployment.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/userguide/smx4-osgi-deployment.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/userguide/smx4-osgi-deployment.mdtext (added)
+++ ode/site/trunk/content/userguide/smx4-osgi-deployment.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,89 @@
+Title: SMX4 OSGi Deployment
+<a name="SMX4OSGiDeployment-DeployApacheODEOSGibundleandexampleprocess(PingPong)"></a>
+## Deploy Apache ODE OSGi bundle and example process (Ping Pong)
+
+Enter smx4 console and run following commands:
+
+ :::text
+ features:addUrl mvn:org.apache.ode/ode-jbi-karaf/1.3.5-SNAPSHOT/xml/features
+ features:install ode
+ features:install examples-ode-ping-pong
+
+
+This will install ODE with default settings (OpenJPA DAO, embedded Derby database)
+
+<a name="SMX4OSGiDeployment-Configuringdatabase"></a>
+## Configuring database
+
+Create `SMX4/etc/org.apache.ode.jbi.cfg` file with following contents:
+
+ :::text
+ ode-jbi.pidNamespace=urn:ode-jbi
+ ode-jbi.allowIncompleteDeployment=false
+ ode-jbi.messageMapper=org.apache.ode.jbi.msgmap.ServiceMixMapper
+ ode-jbi.event.listeners=org.apache.ode.bpel.common.evt.DebugBpelEventListener
+
+ #For MySQL
+ #ode-jbi.db.int.mcf=org.tranql.connector.mysql.XAMCF
+ #ode-jbi.db.int.mcf.databaseName=ODE
+ #ode-jbi.db.int.mcf.userName=root
+ #ode-jbi.db.int.mcf.password=root
+ #ode-jbi.db.int.mcf.serverName=localhost
+
+ #For Postgres
+ #ode-jbi.db.int.mcf=org.tranql.connector.postgresql.PGXAMCF
+ #ode-jbi.db.int.mcf.databaseName=ODE
+ #ode-jbi.db.int.mcf.userName=postgres
+ #ode-jbi.db.int.mcf.password=postgres
+ #ode-jbi.db.int.mcf.serverName=localhost
+
+ #For SQLServer
+ #ode-jbi.db.int.mcf=org.tranql.connector.sqlserver.XAMCF
+ #ode-jbi.db.int.mcf.databaseName=ODE
+ #ode-jbi.db.int.mcf.userName=sa
+ #ode-jbi.db.int.mcf.password=sa
+ #ode-jbi.db.int.mcf.portNumber=1433
+ #ode-jbi.db.int.mcf.serverName=localhost
+
+ #For Oracle
+ ode-jbi.db.int.mcf=org.tranql.connector.oracle.LocalMCF
+ ode-jbi.db.int.mcf.databaseName=XE
+ ode-jbi.db.int.mcf.userName=ODE
+ ode-jbi.db.int.mcf.password=ode
+ ode-jbi.db.int.mcf.portNumber=1521
+ ode-jbi.db.int.mcf.serverName=localhost
+ ode-jbi.db.int.mcf.driverType=thin
+
+
+ # Uncomment the following to enable hibernate (this is recommended for production use):
+ #ode-jbi.dao.factory=org.apache.ode.daohib.bpel.BpelDAOConnectionFactoryImpl
+
+
+Please note that EXTERNAL database is currently not available in ServiceMix4, because it requires JNDI, which SMX4 doesn't support.
+
+After choosing a particular database, we need to start ODE with required dependencies. There are 2 example features prepared in ode-jbi-karaf features (ode-hib-oracle and ode-hib-sqlserver).
+So you need to run following command from Karaf console:
+
+ :::text
+ features:install ode-hib-oracle
+
+Please note that `etc/org.apache.ode.jbi.cfg` must be set to the same database (in this case oracle) to load required dependencies properly.
+
+<a name="SMX4OSGiDeployment-Tips"></a>
+## Tips
+
+<a name="SMX4OSGiDeployment-HowtomakePMAPIwork?"></a>
+### How to make PMAPI work?
+
+You can grab pmapi SA from here [http://markmail.org/message/ghigpzcpt2j3qnoo](http://markmail.org/message/ghigpzcpt2j3qnoo).
+Then edit SMX4 `etc/config.properties` and change from:
+
+ :::text
+ org.osgi.framework.bootdelegation=sun.*,com.sun*,javax.transaction,javax.transaction.*
+
+to:
+
+ :::text
+ org.osgi.framework.bootdelegation=sun.*,com.sun*,javax.transaction,javax.transaction.*,javax.xml.stream,javax.xml.stream.*
+
+
Added: ode/site/trunk/content/userguide/upgrading-ode.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/userguide/upgrading-ode.mdtext?rev=1420130&view=auto
==============================================================================
--- ode/site/trunk/content/userguide/upgrading-ode.mdtext (added)
+++ ode/site/trunk/content/userguide/upgrading-ode.mdtext Tue Dec 11 12:47:58 2012
@@ -0,0 +1,79 @@
+Title: Upgrading ODE
+<div class="alert alert-note"><h4 class="alert-heading">You shall backup</h4></div>
+
+ODE upgrade procedures usually consist in:
+
+* backing up your database
+* checking your backup
+* double-checking your backup
+* running the required SQL upgrade script
+* deploying your new ODE war.
+* copying all the previous configuration and deployed processes (with the corresponding markers).
+
+## From 1.3.3 to 1.3.4
+
+First, apply SQLs to denormalize LARGE_DATA table from here: [https://issues.apache.org/jira/browse/ODE-694]
+
+Then, please apply following updates:
+
+ :::sql
+ alter table BPEL_XML_DATA add SIMPLE_VALUE varchar2(255);
+
+ create table ODE_JOB_BAK as select * from ODE_JOB;
+ alter table ODE_JOB add instanceId number(37);
+ alter table ODE_JOB add mexId varchar(255);
+ alter table ODE_JOB add processId varchar(255);
+ alter table ODE_JOB add type varchar(255);
+ alter table ODE_JOB add channel varchar(255);
+ alter table ODE_JOB add correlatorId varchar(255);
+ alter table ODE_JOB add correlationKeySet varchar(255);
+ alter table ODE_JOB add retryCount int;
+ alter table ODE_JOB add inMem int;
+ alter table ODE_JOB add priority int;
+ alter table ODE_JOB add detailsExt blob;
+ update ODE_JOB oj set detailsExt = (select details from ODE_JOB where jobid = oj.jobid);
+ alter table ODE_JOB drop column details;
+
+## From 1.3.2 to 1.3.3
+
+None
+
+
+## From 1.2 to 1.3.2
+
+If you're currently using ODE *1.2* and are upgrading to 1.3.2, please run the following queries.
+
+### For OpenJPA database schema
+
+ :::sql
+ create table ODE_SCHEMA_VERSION (VERSION integer);
+ insert into ODE_SCHEMA_VERSION values (5);
+
+ alter table ODE_MESSAGE_EXCHANGE add column (SUBSCRIBER_COUNT integer);
+ alter table ODE_MESSAGE_ROUTE add column (ROUTE_POLICY character varying(255));
+
+### For Hibernate database schema
+
+(Mind the table names)
+
+ :::sql
+ create table ODE_SCHEMA_VERSION(VERSION integer);
+ insert into ODE_SCHEMA_VERSION values (5);
+
+ alter table BPEL_MESSAGE_EXCHANGE add column (SUBSCRIBER_COUNT integer);
+ alter table BPEL_SELECTORS add column (ROUTE_POLICY character varying(255));
+
+## From 1.1 to 1.2
+
+The upgrade path from 1.1 to 1.2 is relatively simple as there haven't any major change in the database or runtime models. Still, if you use the Hibernate database schema, one column has been added so you will need to execute the following upgrade script (make sure to *backup before* to prevent any data loss):
+
+ :::sql
+ alter table BPEL_SELECTORS add column (PROC_TYPE varchar(255));
+ update BPEL_PROCESS p, BPEL_CORRELATOR c, BPEL_SELECTORS s set s.PROC_TYPE = ('{' + p.type_ns + '}' + p.type_name) where s.CORRELATOR = c.CID and c.PROCESS_ID = p.PROCID;
+
+The update statement is only necessary if you have currently running instances. Note that if you're using the default OpenJPA database schema, no database modifications are necessary. Once this is done, it's fairly simple:
+
+* Redeploy your new ODE 1.2 WAR.
+* Copy all the previous configuration and deployed processes (with the corresponding markers).
+
+That's it\!