svn commit: r1420144 - in /ode/site/trunk/content: faq.mdtext userguide/index.mdtext

[va...@apache.org]

Author: vanto
Date: Tue Dec 11 13:24:03 2012
New Revision: 1420144

URL: http://svn.apache.org/viewvc?rev=1420144&view=rev
Log:
fix formatting.

Modified:
    ode/site/trunk/content/faq.mdtext
    ode/site/trunk/content/userguide/index.mdtext

Modified: ode/site/trunk/content/faq.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/faq.mdtext?rev=1420144&r1=1420143&r2=1420144&view=diff
==============================================================================
--- ode/site/trunk/content/faq.mdtext (original)
+++ ode/site/trunk/content/faq.mdtext Tue Dec 11 13:24:03 2012
@@ -1,4 +1,155 @@
-Title: FAQ
+Title: Frequently Asked Questions
+Category: documentation
 
+## FAQ
+This section collections frequently asked questions about ODE, BPEL, and related topics.
 
-{include:Frequently Asked Questions}
+## General
+
+__Q.__ _What is ODE?_
+__A.__ ODE is a system for executing reliable long-running process described using the WS-BPEL 2.0 standard and the BPEL4WS 1.1 vendor specification.
+
+__Q.__ _What is the architecture of ODE?_
+__A.__ The architecture of ODE is described in the ODE [Architectural Overview]
+
+
+__Q.__ _In what language is ODE written?_
+__A.__ ODE is written in Java and relies on JDK v5.0 features.
+
+__Q.__ _How does ODE ensure reliable process execution?_
+__A.__ ODE relies on a relational database to provide persistent storage.
+
+## Language-Related BPEL Questions
+
+This section covers frequently-asked questions about ODE's support for the OASIS WS-BPEL language.
+
+__Q.__ _Which version or versions of BPEL does ODE currently support?_
+__A.__ ODE aims to provide full compliance to the OASIS [WS-BPEL 2.0](ws-bpel-20.html) standard as well as backward compatibility for BPEL4WS 1.1 processes. At present, ODE (mostly) supports the syntax of the final [WS-BPEL 2.0](ws-bpel-20.html) draft; limitations are described in the [WS-BPEL 2.0 Specification Compliance](ws-bpel-20-specification-compliance.html) page.
+
+__Q.__ _Is the entire_ _[WS-BPEL 2.0](ws-bpel-20.html)_ _specification supported?_
+__A.__ Most WS-BPEL 2.0 language features (and all important features) are supported. For specifics see the [WS-BPEL 2.0 Specification Compliance](ws-bpel-20-specification-compliance.html) page.
+
+__Q.__ _Does ODE use native Java language constructs to execute BPEL, e.g., multiple threads for a_ _```<bpel:flow>```_ _or a_ ```while (...) {...}``` _for a_ ```<bpel:while>```?
+__A.__ No. ODE's BPEL implementation does not map the BPEL process into Java. Instead, it relies on a transactional concurrency framework [JaCOb](/developerguide/jacob.html) similar to the theoretical concurrency model known as ACTORS [Agha86].
+
+__Q.__ _Does ODE support BPEL processes developed in third-party tools?_
+__A.__ Yes. Well-formed BPEL from any source should work.
+
+__Q.__ _Can ODE support extensions or alternatives to standard BPEL syntax and semantics?_
+__A.__ Yes. ODE's BPEL compiler can be customized to support non-standard BPEL syntax and semantics.
+
+__Q.__ _Does ODE support custom XPath extension functions in a BPEL process?_ What are the limitations?
+__A.__ Yes. XPath extension functions are supported; however, to ensure correct process execution in the presence of system failures, extension functions must be side-effect free.
+
+__Q.__ _Does ODE support custom expression / query languages?_
+__A.__ Yes. The expression / query language is fully pluggable.
+
+__Q.__ _Does ODE support BPELJ or JSR-207?_
+__A.__ No.
+
+__Q.__ _Can multiple BPEL activities be grouped into a single transaction?_
+__A.__ No.
+
+__Q.__ _My process fails with a_ ```selectionFailure```; What can I do?_
+__A.__ BPEL expects a *single* element to be selected when evaluating ```<to>``` and ```<from>``` expressions, and a ```selectionFailure``` fault is thrown if zero or more than one element are selected.
+
+If you get zero element, double-check your namespace prefix and bindings.   Also, remember that you must initialize your variables (most often with ```<literal>```'s) before assigning into them, unless your are reassigning the whole variable (e.g. directly into ```$variable```, or ```$variable.part```).  To debug assignments, you can set the "org.apache.ode" logging category to DEBUG in order to see the content of variables as the process executes.
+
+## BPEL Process Management
+
+This section covers frequently-asked questions about the runtime management of the engine and process instances.
+
+__Q.__ _Does ODE support process versioning?_
+__A.__ Yes, our versioning approach is described [here](process-versioning.html) in detail. The ability to modify the definition of an existing process instance may be available in future versions.
+
+__Q.__ _Does ODE provide debugging facilities?_
+__A.__ Yes, BPEL processes can be debugged "in-container" using the [Management API](management-api.html).
+
+__Q.__ _What kind of eventing or audit information is available from ODE's BPEL engine?_
+__A.__ ODE includes a rich eventing API that exposes information about the start and completion time of activities and scopes, variable manipulations, and other information. Event listeners can extract as much or as little of this information as desired.
+
+## Runtime Environments and Requirements
+
+This section covers frequently-asked questions about the runtime requirements for ODE and supported thirdparty products.
+
+__Q.__ _Which Java virtual machines and runtime environments does ODE support?_
+__A.__ [Building ODE](building-ode.html) and executing ODE requires JDK 5.0.
+
+__Q.__ _Which operating systems does ODE support?_
+__A.__ ODE is written entirely in Java and can run on any operating system supporting the required Java environment. ODE has been tested and is known to run on Windows 2000, Windows XP, Linux, MacOS X, Solaris, and AIX.
+
+__Q.__ _Does ODE require a database? Which databases and versions does ODE support?_
+__A.__ ODE does not depend directly on any specific database or persistence mechanism. Instead, ODE relies on a set of data access object ("DAO") interfaces that encapsulate the behaviors of a persistence layer. The ODE distribution includes a DAO implementation for JDBC databases built using [OpenJPA|http://openjpa.apache.org]. This DAO implementation can support most common relational databases. Schemas suitable for [MySQL|http://www.mysql.com] and [Derby|http://db.apache.org/derby/] are provided. Relational databases lacking transaction or binary large object ("BLOB") capabilities are not supported. The DAO interfaces can readily be implemented to support alternative persistence mechanisms (e.g. JDO), XML datastores, or direct filesystem-based persistence.
+
+__Q.__ _Does ODE require a J2EE application server?_
+__A.__ The core ODE components do not require a J2EE application server. ODE relies on a [Integration API|http://svn.apache.org/repos/asf/ode/trunk/bpel-api/src/main/java/org/apache/ode/bpel/iapi/] that allows ODE to be embedded in most any environment that can supply the required facilities. An [AXIS2 Integration] is provided that permits ODE to be installed on a J2EE application server, or in a "dumb" Servlet container via a WAR file. A [JBI Integration] integration is also provided that permits ODE to be installed in a JBI container.
+
+__Q.__ _Is there a stand-alone ODE integration?_
+__A.__ No, the standard ODE distributions require either an application server, Servlet container, or JBI container.
+
+__Q.__ _Can ODE be deployed within an application server or web container?_
+__A.__ Yes, ODE can be deployed into most common application servers. However, it is important to note that ODE is not an _enterprise application_ in the J2EE sense: ODE manages its own transactions and threads.
+
+__Q.__ _Does ODE require JMS?_
+__A.__ No, however future versions of ODE will require a transactional transport to support clustering.
+
+__Q.__ _Is ODE internationalized? If so, which languages are supported?_
+__A.__ ODE messages intended for user consumption are internationalized using the Java resource bundle mechanism. American english messages are provided.
+
+__Q.__ _I'm getting data truncation errors, what does that mean?_
+__A.__ We try to use sensible sizes for the database columns that contain messages and variables in ODE. However if you're manipulating large quantities of data that may not e enough. The solution in that case is to alter the column that's too short to reserve enough database space for your needs.
+
+## Integration with Third-Party Products
+
+This section covers frequently asked questions related to integrating ODE into third-party products or integrating third-party products into ODE.
+
+__Q.__ _Can ODE interact directly (i.e., not over the network) with native Java services?_
+__A.__ This is currently supported in the [JBI Integration] via standard JBI mechanisms. It is currently not supported in the [AXIS2 Integration] but will be in the future.
+
+__Q.__ _Can ODE integrate with Middleware X? Can ODE integrate with Legacy system Y? Can ODE integrate with Enterprise Application Z? How is this accomplished?_
+__A.__ The generic answer is "Yes," although it requires some work on the part of the integrator. The primary extension point for integrating with external systems is the [Integration API|http://ode.apache.org/javadoc/org/apache/ode/bpel/pmapi/ProcessManagement.html], which can be used to embed ODE in most any environment.
+
+__Q.__ _Does ODE rely on any third-party or open source libraries?_
+__A.__ ODE uses a number of liberally-licensed (i.e., non-GPL) open source libraries, some integral and some not. These are enumerated in the [reference|Required Third-Party Libraries].
+
+## ODE and Web Services
+
+This section covers frequently asked questions about how ODE related to various web services specifications and initiatives.
+
+__Q.__ _Does ODE supply a SOAP stack?_
+__A.__ Not directly. ODE relies on the [Integration Layer|Architectural Overview#ODEIntegrationLayers] to supply the "physical" communication mechanisms. The [AXIS2 Integration Layer|Architectural Overview#ODEIntegrationLayers] that is part of the ODE distribution uses the AXIS2 SOAP stack. The [JBI Integration Layer|Architectural Overview#ODEIntegrationLayers] relies on external HTTP/SOAP components (e.g. ServiceMix's {{servicemix-http}} component).
+
+__Q.__ _Can ODE be integrated with third-party web services products such as Apache AXIS, Systinet WASP, or JAXRPC?_
+__A.__ Yes, ODE can be integrated into most any stack via the [Integration API|http://incubator.apache.org/ode/javadoc/bpel-api/index.html]
+
+
+
+__Q.__ _Does ODE support web services transaction specifications, e.g., WS-Transaction, WS-Coordination, WS-Business Activity, OASIS BTP, or Composite Application Framework (WS-CAF)?_
+__A.__ No, not at present.
+
+__Q.__ _Does ODE support WS-Addressing?_
+__A.__ ODE does not directly support WS-Addressing. However, the BPEL implementation and the core ODE infrastructure provides support for opaque end-point references. This allows ODE to be integrated with arbitrary addressing standards. The [AXIS2 Integration Layer] for ODE employs this mechanism to support WS-Addressing.
+
+## Reliability
+
+This section covers frequently asked questions about the reliability of ODE.
+
+__Q.__ _Can ODE recover in the event of system failure?_
+__A.__ Yes, ODE uses  transaction management and relies on transactional data stores to ensure data consistency in the event of failure.
+
+__Q.__ _How does ODE's BPEL Engine recover in the event of system failure?_
+__A.__ todo: describe recovery mechanism
+
+__Q.__ _What happens to outbound invocations bound to transaction protocols (such as SOAP-over-JMS) in the event of system failure?_
+__A.__ todo: describe
+
+
+__Q.__ _What happens to outbound invocations bound to non-transactional protocols (such as HTTP) in the event of system failure?_
+__A.__ todo: describe
+
+## Clustering
+
+This section covers frequently asked questions about ODE's clustering support.
+
+__Q.__ _Can ODE be deployed in clustered or other configurations intended to provide fault tolerance and increased performance?_
+__A.__ Clustering support is currently under development. Clustering support will require a transaction inter-node transport (such as JMS) as well as a transactional data store that can be accessed concurrently by all nodes in the cluster (i.e. a modern RDBMS).

Modified: ode/site/trunk/content/userguide/index.mdtext
URL: http://svn.apache.org/viewvc/ode/site/trunk/content/userguide/index.mdtext?rev=1420144&r1=1420143&r2=1420144&view=diff
==============================================================================
--- ode/site/trunk/content/userguide/index.mdtext (original)
+++ ode/site/trunk/content/userguide/index.mdtext Tue Dec 11 13:24:03 2012
@@ -1,4 +1,5 @@
 Title: User Guide
+Category: documentation
 
 <a name="UserGuide-GettingStarted"></a>
 ## Getting Started