{section}
{column}

{multi-excerpt-include:Petals-SE-Camel\|name=features\|nopanel=true}
{column}

{column:width=40%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name\|mode=list\|showAnonymous=true\|showCount=true\|showLastTime=true}{panel}
{column}
{section}

h1. Introduction

This implementation of the SE Camel uses Camel version 2.15.0.

Routes can be defined using any of the JVM based DSL, as well as using the XML notation.
A Camel route always starts with a *from* declaration, a consumer, and often ends with one or many *to* declaration, producers.
Consumers and producers refers to service external to Camel using an URI: Petals services have their own URI scheme identified with *petals*.

For each *provides* section, exactly one route must be present and will be activated when a message is received.
Each route can call any service declared in a *consumes* section.

*Consumes* corresponds to an operation of a service and have a MEP defined.
*Provides* corresponds to a service defined with WSDL and for which every operation has one corresponding route.

{tip}
The terminology used by Camel is apparently counter-intuitive to the one used in JBI terminology: a camel route consumes a service while an SU provides this same service.
This is because from the route point of view, messages arriving to the provided service are then consumed by the rule.
{tip}

{tip}
The SOA terminology is sometimes confusing: in the following we will use the general term *service* and operation interchangeably.
{tip}

We show in the next section a general overview of a typical Camel Service Unit.

h1. Overview of a Camel Service Unit at Runtime

Each SU has its own Camel context: the Camel context is the runtime entity responsible of executing the routes.
Routes in the same context can refer to each others when needed (see the section [Camel Routes|#camel-routes] below).

When a JBI exchange arrives on for a provided service (an operation), it is transformed to a Camel exchange and dispatched to the route with a petals consumer (in the Camel terminology, i.e. with a *from* declaration using the *petals* URI scheme) the service.

When a Camel exchange is dispatched in a route to a petals producer (in the Camel terminology, i.e. with a *to* declaration using the *petals* URI scheme), it is transformed to a Petals exchange and sent to the corresponding consumes service.

For details on the transformation, see the section [Petals to Camel to Petals|#transformations] below.

h1. Overview of a Camel Service Unit at Implementation Time

h2. Maven Project

<!-- We are producing a service unit -->
<groupId>my.group</groupId>
<artifactId>my-service-unit</artifactId>
<version>1.0.0</version>
<packaging>jbi-service-unit</packaging>

<!-- ... -->

<dependencies>
<!-- First a jbi-component dependency to the component (note that it won't provide anything in the classpath!) -->
<dependency>
<groupId>org.ow2.petals</groupId>
<artifactId>petals-se-camel</artifactId>
<version>1.0.0-SNAPSHOT</version>
<type>jbi-component</type>
</dependency>
<!-- Then a dependency to camel, only if you plan to implement routes in Java -->
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-core</artifactId>
<version>2.15.0</version>
<scope>provided</scope>
</dependency>
<!-- Maybe other dependencies if you relies on other camel extensions (for xml and java routes) -->
</dependencies>

<!-- ... -->

<build>
<!-- Finally the petals maven plugins to generate JBI zip files -->
<plugins>
<plugin>
<groupId>org.ow2.petals</groupId>
<artifactId>maven-petals-plugin</artifactId>
</plugin>
</plugins>
</build>

<!-- ... -->
{code}

The project structure will follow typical maven projects :
{noformat}
my-service-unit/
+ pom.xml
+ src/
+ main/
+ jbi/

On top of the typical pom.xml, there must be at least one route implementation per operation of the provides, in a jar file or an xml file, a WSDL description for every provides service of the JBI descriptor and of course a JBI descriptor.

h2. Service Unit Content

A Camel SU generated from the previous Maven projects, named my-service-unit-1.0.0.zip will contains the following elements:

{noformat}
my-service-unit-1.0.0.zip
+ META-INF/
+ jbi.xml
+ service.wsdl (none, one or several)
+ my-service-unit-1.0.0.jar
{noformat}

Note that the jar is the generated Jar Maven artefact, and it is included in the generated Zip artefact by the petals maven plugin.

h2. A Camel Route

Here is an example of a Camel route defined in XML:

{code:lang=xml}
<!-- we must use the http://camel.apache.org/schema/spring namespace so Camel can load the routes
but Spring JARs are not required -->
<routes xmlns="http://camel.apache.org/schema/spring">
<route>
<from uri="petals:incomingOrders" />
<convertBodyTo type="java.lang.String" />
<choice>
<when>
<simple>${body} contains '?xml'</simple>
<unmarshal>
<jaxb contextPath="org.fusesource.camel" />
</unmarshal>
<to uri="petals:orders" />
</when>
<otherwise>
<unmarshal>
<bindy packages="org.fusesource.camel" type="Csv" />
</unmarshal>
<to uri="petals:orders2" />
</otherwise>
</choice>
</route>
<routes>
{code}

{color:red}{*}TODO. make that a real example...*{color}

The only specificity for Petals of this route are the URIs used to identify the services consumed by the route (*from* element) and to which messages are then sent (*to* element).
The scheme reserved to petals is *petals*: it is followed by *:* and then the unique id identifying a service's operation.

The rest is typical Camel but some Camel processors are particularly useful to handle Petals exchange from within Camel, such as the jaxb marshaller/unmarshaller or the body conversion.
See the section [Camel Routes|#camel-routes] below for details.

h2. JBI Descriptor and WSDL definition

The JBI descriptor contains:
* The services that are provided by this SU for which routes will handle messages, and
* The services consumed by this SU that will be callable from the route.

In order to identify a service's operation, each of the operation, provided or consumed, must have a unique id.
Of course, a provided service will be only usable by *from* elements and consumed services by *to* elements.

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5" xmlns:petals-se-camel="http://petals.ow2.org/components/petals-se-camel/jbi/version-1.0"
xmlns:hello="http://petals.ow2.org">

<jbi:services binding-component="false">

<jbi:provides interface-name="hello:HelloInterface" service-name="hello:HelloService" endpoint-name="autogenerate">
<petalsCDK:wsdl>service.wsdl</petalsCDK:wsdl>
</jbi:provides>

<jbi:consumes interface-name="hello:HelloInterface" service-name="hello:HelloService">

<!-- Mandatory CDK specific elements -->
<petalsCDK:operation>hello:sayHello</petalsCDK:operation>
<petalsCDK:mep>InOut</petalsCDK:mep>

<!-- Mandatory Component specific elements -->
<petals-se-camel:service-id>theConsumesId</petals-se-camel:service-id>

<petals-se-camel:java-class>org.test.ASimpleRoute</petals-se-camel:java-class>
</petals-se-camel:routes>

</jbi:services>
</jbi:jbi>
{code}

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://petals.ow2.org" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://petals.ow2.org" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:petals-camel-wsdl="http://petals.ow2.org/components/petals-se-camel/wsdl/version-1.0">
<wsdl:types>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://petals.ow2.org"
elementFormDefault="unqualified" targetNamespace="http://petals.ow2.org" version="1.0">
<xs:element name="sayHello" type="tns:sayHello" />
<xs:element name="sayHelloResponse" type="tns:sayHelloResponse" />
<xs:complexType name="sayHello">
<xs:sequence>
<xs:element minOccurs="0" name="arg0" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="sayHelloResponse">
<xs:sequence>
<xs:element minOccurs="0" name="return" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>
</wsdl:types>
<wsdl:message name="sayHelloResponse">
<wsdl:part name="parameters" element="tns:sayHelloResponse" />
</wsdl:message>
<wsdl:message name="sayHello">
<wsdl:part name="parameters" element="tns:sayHello" />
</wsdl:message>
<wsdl:portType name="HelloInterface">
<wsdl:operation name="sayHello">
<wsdl:input name="sayHello" message="tns:sayHello" />
<wsdl:output name="sayHelloResponse" message="tns:sayHelloResponse" />
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="HelloServiceBinding" type="tns:HelloInterface">
<wsdl:operation name="sayHello">
<petals-camel-wsdl:operation service-id="theProvidesId" />
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="HelloService">
<wsdl:port name="autogenerate" binding="tns:HelloServiceBinding" />
</wsdl:service>
</wsdl:definitions>
{code}

Two types of route definitions can be used: java classes and XML files.
Java classes refer to classes that extends the Camel RouteBuilder abstract class, i.e. routes written with any of the JVM-based DSLs: [Camel DSL Page|http://camel.apache.org/dsl.html].
XML files refer to routes defined used the XML DSL from Camel: [Camel XML Examples|http://camel.apache.org/walk-through-another-example.html].

h1. Semantics of the Send operation (synchronicity, timeouts, etc)

By default, the execution is asynchronous: it means that if one of the processor or producer on the route needs to do blocking operations, the processing won't keep the CDK thread that received the message busy and it will continue execution when it is time to depending on the blocked processor.
This has no impact on how the routes are implemented, but in term of execution, it means that threads are not blocked and resources are often freed as soon as possible.
See [Camel Asynchronous Routing Engine|http://camel.apache.org/asynchronous-routing-engine.html] and [Camel Asynchronous Processing|http://camel.apache.org/asynchronous-processing.html] for technical details.

{anchor:camel-routes}

h1. Camel Routes

{color:red}{*}TODO. Add some explanation on how to use direct: and seda: URIs from Camel to call local routes, how to marshal and unmarshal, how to convert bodies, etc{*}{color}

{anchor:transformations}

h1. Petals to Camel to Petals

{color:red}{*}TODO. Explains how Petals and Camel exchanges are transformed to each others{*}{color}
{color:red}{*}TODO. Explains problem with InOptionalOut{*}{color}