{section}
{column}

{info}The Petals SE EIP is deprecated since Petals v5.0.0. We recommend to use the Petals SE Camel for the EIP needs.{info}
{warning}This version must be installed on [Petals ESB 5.3.0|petalsesb530:Petals ESB 5.3.0]+{warning}

h1. Integration Pattern supported

* Aggregator
* Bridge
* Dispatcher
* Router
* DynamicRouter
* RoutingSlip
* ScatterGather
* WireTap
* Splitter

{column}
{column:width=350px}
{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. Service Configuration

The EIP used as service provider implementation is defined and configured in the service unit descriptor.

h2. Service unit descriptor

Processing a pattern is providing a service that invokes 'sub-services', this service is called the 'original' service and its caller the 'original' consumer.

A Service unit contains:
* one and only one {{Provides}} section, which describes the pattern that will be processed when a request message is received,
* one or more {{Consumes}} sections, which reference services to invoke during the pattern processing. The order of the {{consumes}} sections is important, as it is the order taken account when a pattern need 'sub-service' coordination.

The number of {{consumes}} sections depends on the pattern implemented.

If the MEP {{InOut}} or {{InOptionalOut}} are supported by a pattern, the component returns to the original consumer an {{OUT}} or {{FAULT}} response built according to the pattern feature.

If an invoked service returns a {{Fault}} or an {{Error}} status, the behavior of process can be configured:
* The process can terminate and the {{Fault}} or the {{Error}} is sent back to the 'original' consumer
* The process can continue, ignoring the {{Fault}} or the {{Error}} received

{note:title=Caution}The MEP is mandatory for each consumes sections.{note}
{note:title=Caution}Either an operation must be specified in the consumes sections or the 'original' operation is used for 'sub-service' requests.{note}

The {{Provides}} section is configured through parameters divided in following groups:
* *JBI parameters* that defines the service provider identification,
* *CDK parameters* that are parameters driving the service provider implementation at CDK layer,
* *CDK interceptor parameters* that are parameters driving interceptors at CDK layer,

* *CDK interceptor parameters* that are parameters driving interceptors at CDK layer.

h3. CDK parameters defining service provider implementation
The following parameters correspond to the CDK configuration of the service provider implementation.

{include:0 CDK SU SE Consume Configuration 5.8.0}

h3. CDK parameters driving interceptors
The following parameters drive interceptors at CDK layer.

{include:0 CDK SU Interceptor configuration 5.8.0}

h3. Service provider dedicated configuration
{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the EIP pattern to execute. See nested paragraph to get the values for each EIP patterns. | {center}\-{center} | {center}Yes{center} |
{table-plus}

Other dedicated parameters can exist according to the EIP pattern used. See nested paragraphs to get more information on each EIP patterns.

h4. Aggregator Pattern

{center}!aggregator.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{aggregator}} | {center}\-{center} | {center}Yes{center} |
| test | XPath condition applied on the message to complete or not the sequence and invoke the 'sub-service' | {center}\-{center} | {center}Yes{center} |
| aggregator-correlation | XPath condition that is applied on the incoming message to correlate them together | {center}\-{center} | {center}Yes{center} |
{table-plus}

The EIP Component receives 'original' exchanges and correlates their content amongst the aggregation configurations. The correlation is identified from the XPath expression specified in the SU parameter {{aggregator-correlation}}. If an 'original' exchange is on a {{InOut}} or {{InOptionalOut}} MEP, a standard response is sent back to the 'original' consumer :

{code:xml}
<result xmlns="http://petals.ow2.org/petals-se-eip/aggregator">
Aggregator: the content is buffered by the pattern
</result>
{code}

The exchange messages matching an {{aggregator-correlation}} condition are stored in memory.
Once an 'original' exchange message matches the XPath expression specified in the SU parameter {{test}}, the message and the previous stored messages on the condition {{aggregator-correlation}} are aggregated and send to the target 'sub-service'.
The current 'original' exchange properties are copied into the target exchange.
The aggregated content is the result of a concatenation of the messages in the following form :

{code:xml}
<result xmlns="http://petals.ow2.org/petals-se-eip/aggregator">
...
</result>
{code}

The result of the 'sub-service' is sent back to the 'original' consumer of the last aggregated exchange.

An example of Service Unit configuration for the *aggregator* pattern :
{code: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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:aggregator"
service-name="test:aggregatorService1"
endpoint-name="aggregatorService1Endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>aggregator</eip:eip>
<eip:aggregator-correlation>/*[local-name()='helloworld']/text()</eip:aggregator-correlation>
<eip:test>
boolean(/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test3'])
</eip:test>
</jbi:provides>

<jbi:consumes interface-name="test:aggregateProvider"
service-name="test:aggregateProviderService1"
endpoint-name="aggregateProviderService1Endpoint">
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
<petalsCDK:mep>InOnly</petalsCDK:mep>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}Message order is kept from incoming sequence to the outgoing message.{note}
{note:title=Caution}{{{}Consumes}} sections cardinality is \[1-1\].{note}
{note:title=Caution}All MEPs are accepted for the 'original' consumer and the 'sub-service'{note}

h4. Scatter-Gather Pattern

{center}!scattergather.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{scatter-gather}} | {center}\-{center} | {center}Yes{center} |
| fault-robust | If true, a fault returned by a 'sub-service' exchange do not interrupt the process of the pattern | {center}false{center} | {center}No{center} |
| exception-robust | If true, an exception thrown by a 'sub-service' exchange do not interrupt the process of the pattern | {center}false{center} | {center}No{center} |
{table-plus}

The EIP Component forwards the message to all the configured 'sub-service(s)'. The component waits for all the responses from these services, and aggregates them.
The aggregation is returned to the 'original' consumer in the following form :

{code:xml}
<result xmlns="http://petals.ow2.org/petals-se-eip/scatter-gather">
...
</result>
{code}

An example of Service Unit configuration for the *scatter-gather* pattern :
{code: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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:scatterGather"
service-name="test:scatterGatherService1"
endpoint-name="scatterGatherService1Endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>scatter-gather</eip:eip>
</jbi:provides>

<jbi:consumes interface-name="test:scatterGatherProvider"
service-name="test:scatterGatherProviderService1"
endpoint-name="scatterGatherProviderService1Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes interface-name="test:scatterGatherProvider"
service-name="test:scatterGatherProviderService2"
endpoint-name="scatterGatherProviderService2Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is \[1-n\].{note}
{note:title=Caution}Message exchange pattern accepted from the 'original' consumer is {{InOut}}.{note}
{note:title=Caution}By default, the process stops when a Fault is returned by a 'sub-service'. To continue the process even if a fault is returned, set the {{fault-robust}} parameter to {{TRUE}}. The fault is concatenated with the others results.{note}
{note:title=Caution}By default, the process stops when an Exception is returned by a 'sub-service'. To continue the process even if an exception is thrown, set the {{exception-robust}} to {{TRUE}}. The exception is concatenated with the others results.{note}

h4. Routing-Slip Pattern

{center}!routingslip.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{routing-slip}}. | {center}\-{center} | {center}Yes{center} |
| fault-to-exception | If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange. | {center}false{center} | {center}No{center} |
{table-plus}

The EIP Component chains invocation of the 'sub-services', in the order that they are declared. The {{IN}} message of the incoming exchange is sent to the first 'sub-service', the {{OUT}} response of this service is sent to the second 'sub-service' as a {{IN}} message, and so on. The last exchange is matched with the 'original' exchange as better as possible:
* If the source exchange needs a response ({{InOut}} patterns) and no response are received ({{InOnly}}, {{RobustInOnly}} patterns), a default response is returned :
{code:lang=xml}<result xmlns="http://petals.ow2.org/petals-se-eip/bridge">
Bridge: no content into the final target exchange
</result>{code}
* If the 'original' exchange do not accept a response ({{InOnly}} or {{RobustInOnly}} patterns) and a response is received ({{InOut}} or {{InOptionalOut}} patterns), the response is ignored.
* If the 'original' exchange do not accept a fault ({{InOnly}} pattern) and a fault is received ({{RobustInOnly}}, {{InOut}} or {{InOptionalOut}} patterns), the fault is ignored.

An example of Service Unit configuration for the *Routing-Slip* pattern:
{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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:routingSlip"
service-name="test:routingSlipService1"
endpoint-name="routingSlipService1Endpoint">

<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>routing-slip</eip:eip>
<eip:fault-to-exception>false</eip:fault-to-exception>
</jbi:provides>

<jbi:consumes interface-name="test:routingSlipProvider"
service-name="test:routingSlipProviderService1"
endpoint-name="routingSlipProviderService1Endpoint">

<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes interface-name="test:routingSlipProvider"
service-name="test:routingSlipProviderService2"
endpoint-name="routingSlipProviderService2Endpoint">

<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is \[1-n\].{note}
{note:title=Caution}By default, the process stops when a Fault is returned or an exception is raised by a 'sub-service'.{note}
{note:title=Caution}MEP of all the 'sub-services' must be set to {{InOut}}, except the last one which can be accorded to the 'original' MEP.{note}
{note:title=Caution}All the MEP are accepted from the 'original' consumer.{note}

h4. Wire-Tap Pattern

{center}!wiretap.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute {{wire-tap}} | {center}\-{center} | {center}Yes{center} |
| wiretap-way | Specify the step of a MEP on which the message should be copied and sent to the 'sub-service'. \\
Values can be {{request}} (copy {{IN}}), {{response}} (copy {{OUT}}/{{FAULT}}), {{request-response}} (copy {{IN}} and {{OUT}}/{{FAULT}}), {{request-on-response}} (copy {{IN}} after {{OUT}} is received; no copy if {{FAULT}} received) | {center}\-{center} | {center}Yes{center} |
{table-plus}

The EIP component acts a proxy to a target 'sub-service'. It intercepts the {{IN}} or {{OUT/FAULT}} messages during the exchange and relays it to a observer 'sub-service'.
The SU parameter {{wiretap-way}} determines at which step of the MEP and which message is relayed to the observer 'sub-service'.
The copied message is sent to the 'observer' service as an {{IN}} message using the {{InOnly}} exchange pattern.
The first {{Consumes}} section refers the target 'sub-service', the second one refers the observer 'sub-service'.

An example of Service Unit configuration to provide the *Wire-Tap* pattern :
{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:eip="http://petals.ow2.org/components/eip/version-2"
    xmlns:test="http://petals.ow2.org/test">    
    <jbi:services binding-component="false">        
        <jbi:provides         
            interface-name="test:wireTap"
            service-name="test:wireTapService1"
            endpoint-name="wireTapService1Endpoint">            
            <petalsCDK:wsdl xsi:nil="true" />            
            <eip:eip>wire-tap</eip:eip>
            <eip:wiretap-way>request</eip:wiretap-way>
        </jbi:provides>
        <jbi:consumes interface-name="test:wireTapProvider"
                      service-name="test:wireTapProviderService1"
                      endpoint-name="wireTapProviderService1Endpoint">
            <petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
            <petalsCDK:mep>InOut</petalsCDK:mep>
        </jbi:consumes>
        <!-- monitoring -->
        <jbi:consumes interface-name="test:wireTapProvider"
                      service-name="test:wireTapProviderService2"
                      endpoint-name="wireTapProviderService2Endpoint">
            <petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
            <petalsCDK:mep>InOnly</petalsCDK:mep>
        </jbi:consumes>
    </jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is 2.{note}
{note:title=Caution}MEP of the observer 'sub-service' is {{InOnly}}.{note}
{note:title=Caution}All the MEP are accepted from the 'original' consumer and the target 'sub-service'.{note}

h4. Splitter Pattern

{center}!splitter.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{splitter}} | {center}\-{center} | {center}Yes{center} |
| test | XPath condition applied on the message to split from the 'original' exchange | {center}\-{center} | {center}Yes{center} |
| attachment | true to split the attachments of the incoming 'original' exchange, false to split against the {{test}} XPath expression on the In 'original' message | {center}false{center} | {center}No{center} |
| fault-robust | If true, a fault returned by a 'sub-service' exchange do not interrupt the process of the pattern | {center}false{center} | {center}No{center} |
| exception-robust | If true, an exception thrown by a 'sub-service' exchange do not interrupt the process of the pattern | {center}false{center} | {center}No{center} |
{table-plus}

For this pattern, the EIP Component splits the incoming 'original' message to multiple messages, then send them to the configured 'sub-service'.
If {{attachment}} parameter is not set, the {{IN}} message of the exchange is split against the Xpath expression specified in the parameter {{test}}.
If {{attachment}} parameter is set to true, The attachments contained in the 'original' exchange is split, element by element, to new messages.
Each message split is sent to the configured 'sub-service'.

The aggregation of the responses is returned to the 'original' consumer, in the following form :
{code:lang=xml}
<result xmlns="http://petals.ow2.org/petals-se-eip/splitter">
...
</result>
{code}

An example of Service Unit configuration for the *Splitter* pattern :
{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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:splitter"
service-name="test:splitterService1"
endpoint-name="splitterService1Endpoint">

<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>splitter</eip:eip>
<eip:test>
/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test']/*[local-name()='split']
</eip:test>
<eip:fault-robust>false</eip:fault-robust>
<eip:exception-robust>false</eip:exception-robust>
<eip:attachment-mode>false</eip:attachment-mode>
</jbi:provides>

<jbi:consumes interface-name="test:splitterProvider"
service-name="test:splitterProviderService1"
endpoint-name="splitterProviderService1Endpoint">
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
<petalsCDK:mep>InOut</petalsCDK:mep>
</jbi:consumes>
</jbi:services>
</jbi:jbi>{code}

{note:title=Caution}{{{}consumes}} sections cardinality is 1.{note}
{note:title=Caution}MEP accepted from the 'original' consumer is {{InOut}}.{note}
{note:title=Caution}By default, the process stops when a Fault is returned by a 'sub-service'. To continue the process even if a fault is returned, set the {{fault-robust}} parameter to {{TRUE}}. The fault is concatenated with the others results.{note}
{note:title=Caution}By default, the process stops when an Exception is returned by a 'sub-service'. To continue the process even if an exception is thrown, set the {{exception-robust}} to {{TRUE}}. The exception is concatenated with the others results.{note}

h4. Bridge Pattern

{center}!bridge.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute {{bridge}} | {center}\-{center} | {center}Yes{center} |
| fault-to-exception | If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange. | {center}false{center} | {center}No{center} |
{table-plus}

The EIP Component acts as exchange MEP bridge. For instance, it transforms an {{InOnly}} invocation into an {{InOut}} one. It is useful to correlate incompatible MEPs services.
Define in the {{Consumes}} section the 'sub-service' to invoke with its MEP, and the EIP component will match the incoming 'original' exchange against the outgoing exchange patterns as best as possible :
* If the 'original' exchange demands a response ({{InOut}} patterns) and no response are received ({{InOnly}},
{{RobustInOnly}} or {{InOptionalOut}} patterns), a default response is returned in the following form:
{code:lang=xml}<result xmlns="http://petals.ow2.org/petals-se-eip/bridge">
Bridge: no response from the last 'sub-service'
</result>{code}
* If the 'original' exchange do not expect a response ({{InOnly}} or {{RobustInOnly}} patterns) and a response is received ({{InOut}} or {{InOptionalOut}} patterns), the response is ignored.
* If the 'original' exchange do not expect a fault ({{InOnly}} pattern) and a fault is received ({{RobustInOnly}}, {{InOut}} or {{InOptionalOut}} patterns), the fault is ignored.

An example of Service Unit configuration for the *bridge* pattern :
{code:lang=xml}
<?xml version="1.0"?>
<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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
  interface-name="test:splitter"
  service-name="test:splitterService1"
  endpoint-name="splitterService1Endpoint">


<petalsCDK:wsdl xsi:nil="true" />
  <eip:eip>splitter</eip:eip>
  <eip:fault-to-exception>false</eip:fault-to-exception>
  <eip:test>
/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test']/*[local-name()='split']
</eip:test>
  <eip:fault-robust>false</eip:fault-robust>
  <eip:exception-robust>false</eip:exception-robust>
  <eip:attachment-mode>false</eip:attachment-mode>
</jbi:provides>

<jbi:consumes interface-name="test:splitterProvider"
  service-name="test:splitterProviderService1"
  endpoint-name="splitterProviderService1Endpoint">
  <petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
  <petalsCDK:mep>InOut</petalsCDK:mep>
 </jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is 1.{note}

h4. Router Pattern

{center}!router.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{router}} | {center}\-{center} | {center}Yes{center} |
| test\[\] | XPath condition(s) applied on the message to select the 'sub-service' | {center}\-{center} | {center}Yes{center} |
| test-operation\[\] | Operation condition(s) applied on the message to select the 'sub-service' | {center}\-{center} | {center}Yes{center} |
| fault-to-exception | If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange. | {center}false{center} | {center}No{center} |
{table-plus}

The EIP Component evaluates the list of conditions against the 'original' exchange.
Once a condition is matched, the message is forwarded to the 'sub-service' configured in the {{Consumes}} section at the same position than the condition.
The kind of condition can be either a XPath expression processed against the content of the 'original' {{IN}} message (parameter {{test}}), or a qualified operation processed against the 'original' exchange operation (parameter {{test-operation}}).
If none of the conditions are matched, the exchange is forwarded to the default 'sub-service', referenced in the last {{Consumes}} section.

An example of Service Unit configuration for the *Router* pattern :
{code:lang=xml}
<?xml version="1.0"?>
<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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:router"
service-name="test:routerService1"
endpoint-name="routerService1Endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>router</eip:eip>
<eip:test>
boolean(/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test1'])
</eip:test>
<eip:test>
boolean(/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test2'])
</eip:test>
<eip:fault-to-exception>false</eip:fault-to-exception>
</jbi:provides>

<jbi:consumes interface-name="test:routerProvider"
service-name="test:routerProviderService1"
endpoint-name="routerProviderService1Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes interface-name="test:routerProvider"
service-name="test:routerProviderService2"
endpoint-name="routerProviderService2Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<!-- default -->
<jbi:consumes interface-name="test:routerProvider"
service-name="test:routerProviderService3"
endpoint-name="routerProviderService3Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is the number of defined conditions plus 1.{note}
{note:title=Caution}The last {{Consumes}} section is the default service to invoke if no condition has been matched.{note}

h4. Dynamic Router Pattern

{center}!dynamicrouter.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{dynamic-router}} | {center}\-{center} | {center}Yes{center} |
| test\[\] | XPath condition(s) applied on the message to select the 'sub-service' | {center}\-{center} | {center}Yes{center} |
| fault-to-exception | If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange. | {center}false{center} | {center}No{center} |
{table-plus}

This pattern is similar than the Router pattern but do not process the conditions evaluations on the 'original' exchange, but on a response of a conditioning 'sub-service'.
So, first at all, the {{IN}} message of the 'original' consumer is sent to the conditioning 'sub-service', which is the first {{Consumes}} section defined.
Then the component evaluates the list of conditions against the {{OUT}} response message.
The kind of condition is a XPath expression contained in parameter(s) {{test}}.
Once a condition is matched, the message is forwarded to the 'sub-service' configured in the {{Consumes}} section at the same position than the condition plus 1.
If none of the conditions are matched, the exchange is forwarded to the default 'sub-service', referenced in the last {{Consumes}} section.

An example of Service Unit configuration for the *dynamic-router* pattern :
{code:lang=xml}
<?xml version="1.0"?>
<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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">
<jbi:services binding-component="false">
<jbi:provides
interface-name="test:dynamicRouter"
service-name="test:dynamicRouterService1"
endpoint-name="dynamicRouterService1Endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>dynamic-router</eip:eip>
<eip:test>
boolean(/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test2'])
</eip:test>
<eip:test>
boolean(/*[local-name()='helloworld' and namespace-uri()='http://petals.ow2.org/test3'])
</eip:test>
<eip:fault-to-exception>false</eip:fault-to-exception>
</jbi:provides>

<!-- router -->
<jbi:consumes interface-name="test:dynamicRouterProvider"
service-name="test:dynamicRouterProviderService1"
endpoint-name="dynamicRouterProviderService1Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes interface-name="test:dynamicRouterProvider"
service-name="test:dynamicRouterProviderService2"
endpoint-name="dynamicRouterProviderService2Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes interface-name="test:dynamicRouterProvider"
service-name="test:dynamicRouterProviderService3"
endpoint-name="dynamicRouterProviderService3Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<!-- default -->
<jbi:consumes interface-name="test:dynamicRouterProvider"
service-name="test:dynamicRouterProviderService4"
endpoint-name="dynamicRouterProviderService4Endpoint">
<petalsCDK:mep>InOut</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>
</jbi:services>
</jbi:jbi>{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is the number of conditions plus 2.{note}
{note:title=Caution}The first {{Consumes}} section is the 'sub-service' to invoke to get the message to evaluate. Its pattern is {{InOut}}.{note}
{note:title=Caution}The last {{consumes}} section is the default service to invoke if no condition has been matched.{note}

h4. Dispatcher Pattern

{center}!dispatcher.gif!{center}

{table-plus}
|| Parameter || Description || Default || Required ||
| eip | The name of the pattern to execute : {{dispatcher}}. | {center}\-{center} | {center}Yes{center} |
{table-plus}

The EIP Component dispatches the incoming {{IN}} message toward the configured 'sub-services' in {{Consumes}} sections. No response message is expected.

An example of Service Unit configuration for the *Dispatcher* pattern :
{code:lang=xml}
<?xml version="1.0"?>
<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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:test="http://petals.ow2.org/test">

<jbi:services binding-component="false">
<jbi:provides
interface-name="test:dispatcher"
service-name="test:dispatcherService1"
endpoint-name="dispatcherService1Endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>dispatcher</eip:eip>
</jbi:provides>

<jbi:consumes
interface-name="test:dispatcherProvider"
service-name="test:dispatcherProviderService1"
endpoint-name="dispatcherProviderService1Endpoint">
<petalsCDK:mep>InOnly</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>

<jbi:consumes
interface-name="test:dispatcherProvider"
service-name="test:dispatcherProviderService2"
endpoint-name="dispatcherProviderService2Endpoint">
<petalsCDK:mep>InOnly</petalsCDK:mep>
<petalsCDK:operation xmlns:petals="http://org.ow2.petals">petals:operation</petalsCDK:operation>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

{note:title=Caution}{{{}Consumes}} sections cardinality is \[1-n\].{note}
{note:title=Caution}MEP of the 'original' exchange and the 'sub-services' must be {{InOnly}}.{note}

h3. Service unit content

The service unit has to contain the following elements, packaged in the archive:
* the META-INF/jbi.xml descriptor file as described above,
* it is also highly recommended to provide a WSDL description for service provider embedded in the service-unit.

{code}
service-unit.zip
+ META-INF
- jbi.xml (as defined above)
- service.wsdl (recommended)
{code}

h3. Example

An example of a Service Unit descriptor to provide an EIP service:
{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:eip="http://petals.ow2.org/components/eip/version-2"
xmlns:sample="http://petals.ow2.org/sample">
<jbi:services binding-component="false">

<!-- Service provider -->
<jbi:provides interface-name="sample:interface" service-name="sample:service"
endpoint-name="endpoint">
<petalsCDK:wsdl xsi:nil="true" />
<eip:eip>pattern</eip:eip>
</jbi:provides>

<!-- Service consumers -->
<jbi:consumes interface-name="sample:calledInterface1" service-name="sample:calledService1"
endpoint-name="calledEndpoint1">
<petalsCDK:mep xsi:nil="true" />
<!-- The second Consumes -->
<jbi:consumes interface-name="sample:calledInterface2" service-name="sample:calledService2"
endpoint-name="calledEndpoint2">
<petalsCDK:mep xsi:nil="true" />
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}

h1. Component Extension

The component can be extended by any contributor to provide the support of new EIP pattern.

To add a new pattern, provide a Java class implementing the interface {{Pattern}} :

{code}
/**
* The pattern interface
*
* @author Adrien Louis
* @author Christophe Hamerling
* @author Frederic Gardes
*/
public interface Pattern {

/**
* Initialize the pattern
*
*/
void init();

/**
* Process the Pattern.
*
* @param exchange
* The exchange to process
* @param context
* The context of the exchange
*/
boolean processPattern(Exchange exchange, ExchangeContext context);

/**
* Process an exchange for an asynchronous pattern.
*
* @param exchange
* The exchange to process
* @param context
* The context of the exchange
* @param asyncContext
* The EIP asynchronous context
* @param expired
* true if the asynchronous exchange is expired, false else
*/
boolean processAsyncPattern(Exchange exchange, ExchangeContext context,
EIPAsyncContext asyncContext, boolean expired);

/**
* Get the pattern name.
*
* @return The name
*/
String getName();
}
{code}
\\
Use the {{ExchangeContext}} to interact with the container, during your pattern processing :
{code}
/**
* The exchange context.
*
* @author Adrien Louis
* @author Frederic Gardes
*/
public interface ExchangeContext {

/**
* Get the logger
*
* @return the logger
*/
public Logger getLogger();

/**
* get the Consumes for an endpoint
*
* @param endpoint
* The endpoint
* @return The Consumes of the endpoint
*/
public List<Consumes> getSUConsumes(ServiceEndpoint endpoint);

/**
* Send synchronously an exchange. The response will be provided into the
* same exchange
*
* @param exchange
* The exchange to send
* @return true if the exchange was sent, false else (reached timeout,
* technical error,...)
* @throws MessagingException
*/
public boolean sendSync(final Exchange exchange) throws MessagingException;

/**
* Send asynchronously an exchange. The response will be provided as an
* asynchronous exchange
*
* @param exchange
* The exchange to send
* @param asyncContext
* The asynchronous context, provided on the response
* @throws MessagingException
*/
public void sendAsync(final Exchange exchange, AsyncContext asyncContext) throws MessagingException;

/**
* Send asynchronously an exchange. The response will be provided as a
* synchronous exchange
*
* @param exchange
* The exchange to send
* @throws MessagingException
*/
public void send(final Exchange exchange) throws MessagingException;

/**
* Create an exchange from a Consumes
*
* @param consumes
* The Consumes used as JBI Consumer of the exchange
* @return The exchange created
* @throws MessagingException
* @throws PEtALSCDKException
*/
public Exchange createConsumeExchange(Consumes consumes) throws MessagingException, PEtALSCDKException;

/**
* Get the extensions
*
* @return The extensions
*/
public ConfigurationExtensions getExtensions();
}
{code}
\\
Extends the JBI.xml file of the component to reference your new pattern.

h1. Configuring the component

The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
* *JBI parameters* that have not to be changed otherwise the component will not work,
* *CDK parameters* that are parameters driving the processing of the CDK layer,
* *Dedicated parameters* that are parameters specific to this component.

h2. CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.

{include:0 CDK Component Configuration Table 5.8.0}

h2. Interception configuration
{include:0 CDK Component Interceptor configuration 5.8.0}

h2. Dedicated configuration

No dedicated configuration parameter is available.

h1. Monitoring the component

h2. Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

h3. Common metrics

{include:0 CDK Component Monitoring Metrics 5.8.0}

h3. Dedicated metrics

No dedicated metric is available.

h2. Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}

h3. Common alerts

{include:0 CDK Component Monitoring Alerts 5.6.0}

h3. Dedicated alerts

No dedicated alert is available.

h1. Business monitoring

h2. MONIT traces

{include:0 CDK SE Business Monitoring Traces 5.8.0}

h2. Flow tracing activation

{include:0 CDK SE Business Monitoring Flow Tracing Activation 5.8.0}

h2. Flow tracing propagation

{include:0 CDK SE Business Monitoring Flow Tracing Propagation 5.8.0}

With the pattern '{{Aggregator}}', the flow tracing propagation occurs *only* on the last aggregation request, the one that fires the sub-service provider invocation. The flow tracing propagation is driven according to this last request.