{section}
{column}

h1. Features

\\
This component implements some Enterprise Integration Patterns, as described in [http://www.enterpriseintegrationpatterns.com|http://www.enterpriseintegrationpatterns.com].

The services provided by the EIP components are integration logic functionalities.

The component acts as a proxy, as it receives one or more messages from consumers, and forward them to other services, depending on the integration pattern rule used.

The provided integration patterns are :

* Aggregator
* Bridge
* Dispatcher
* Router
* DynamicRouter
* RoutingSlip
* ScatterGather
* WireTap
* Splitter
{column}
{column:width=350px}
{panel}{toc}{panel}
{column}
{section}






h1. Component Configuration

The component can be extended to provide more integration patterns.

To add a new pattern, provide a Java class implementing {{org.ow2.petals.se.eip.patterns.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 help you processing your orchestration :
{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 pattern :

{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<jbi version="1.0"
xmlns="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">
<component type="service-engine" component-class-loader-delegation="parent-first">
<identification>
<name>petals-se-eip</name>
<description>EIP Service engine</description>
</identification>
<component-class-name>org.ow2.petals.se.eip.EIPComponent</component-class-name>
<component-class-path>
<path-element />
</component-class-path>
<bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</bootstrap-class-name>
<bootstrap-class-path>
<path-element></path-element>
</bootstrap-class-path>
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>NOTHING_IGNORED</petalsCDK:ignored-status>
<petalsCDK:notifications>false</petalsCDK:notifications>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.eip.listener.JBIListener</petalsCDK:jbilistener-class-name>
<petalsCDK:properties-file />

<!-- Declaring the supported patterns -->
<eip:aggregator>org.ow2.petals.se.eip.patterns.Aggregator</eip:aggregator>
<eip:router>org.ow2.petals.se.eip.patterns.Router</eip:router>
<eip:dynamic-router>org.ow2.petals.se.eip.patterns.DynamicRouter</eip:dynamic-router>
<eip:dispatcher>org.ow2.petals.se.eip.patterns.Dispatcher</eip:dispatcher>
<eip:routing-slip>org.ow2.petals.se.eip.patterns.RoutingSlip</eip:routing-slip>
<eip:bridge>org.ow2.petals.se.eip.patterns.Bridge</eip:bridge>
<eip:wire-tap>org.ow2.petals.se.eip.patterns.WireTap</eip:wire-tap>
<eip:scatter-gather>org.ow2.petals.se.eip.patterns.ScatterGather</eip:scatter-gather>
<eip:splitter>org.ow2.petals.se.eip.patterns.Splitter</eip:splitter>
</component>
</jbi>
{code}

{include:0 CDK Component Configuration Table}
\\
*Configuration of the component (EIP)*
{table-plus}
|| Parameter || Description || Default || Required ||
| your-pattern-name | Name of the java class implementing your pattern. The name of the pattern at runtime will be the one you give as parameter name | \- | No |
{table-plus}





h1. Service Configuration

h2. Service Unit descriptor

{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">
<!-- The Provides -->
<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>
<!-- The first Consumes -->
<jbi:consumes interface-name="sample:calledInterface1" service-name="sample:calledService1"
endpoint-name="calledEndpoint1">
<petalsCDK:mep xsi:nil="true" />
</jbi:consumes>
<!-- 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}
\\
{include:0 CDK Description of provide}&nbsp;
\\
{include:0 CDK Description of consume}
\\
{include:0 CDK SU Provide Configuration}

h2. Processing a pattern

A Service Unit contains one and only one {{Provides}} section, which describes the pattern that will be processed when a&nbsp;message is received.

The Service Unit contains also one or more consumes sections, which reference services to call during the pattern&nbsp;execution. The order of the {{consumes}} sections is important, as it is the one which is used by the pattern during its execution.

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

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

If an invoked service returns a {{Fault}} or an {{Error}} status, the process ends or no, and the Fault or the Error is sent back&nbsp;to the consumer or no, according to the pattern feature.

An operation must be specified in the {{consumes}} sections. This operation is used to invoke the bound service.

h3. Aggregator Pattern

*Enterprise Integration Pattern*
!aggregator.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{table-plus}
|| Parameter || Description || Default || Required by pattern ||
| eip | The name of the pattern to execute : {{aggregator}} | \- | All |
| test | XPath condition applied on the message to complete or not the sequence by the invocation of the targeted service | \- | aggregator \\
splitter \\
router \\
dynamic-router |
| aggregator-correlation | XPath condition that is applied on the incoming message to correlate them together | \- | aggregator |
{table-plus}

The EIP Component receives source exchanges and correlates it to a SU deployed. The correlation is retrieved from an XPath expression specified in the SU parameter 'aggregator-correlation'. If the source exchange is {{InOut}} or {{InOptionalOut}}, a standard response is sent :

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

Once a source exchange matches the test, the target exchange, with a single, aggregated, content, is sent. The propagable source exchange properties are copied into the target exchange. The test is retrieved from an XPath expression specified in the SU parameter 'test'. The aggregated content is the result of a concatenation :

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

The result of the target service is reported to the consumer of the source exchange matching the test.

An example of service unit configuration :

{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<!-- JBI descriptor for the PEtALS component "EIP"-->
<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|1-1]
{note}

{note:title=Caution}
All the Message Exchange Pattern are accepted for the source exchanges
{note}

h3. Scatter-Gather Pattern

*Enterprise Integration Pattern*
!scattergather.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{table-plus}
|| Parameter || Description || Default || Required by pattern ||
| eip | The name of the pattern to execute : {{scatter-gather}} | \- | All |
| fault-robust | If true, a fault thrown by a target exchange don't stop the process and don't change the original status to {{FAULT}} | false | scatter-gather\\
splitter |
| aggregator-correlation | If true, an exception thrown by a targer exchange don't stop the process and don't change the original exchange status to {{ERROR}}. | false | scatter-gather\\
spliter |

{table-plus}


The EIP Component forwards the message to all the services referenced in the consumes sections. The EIP component waits for all the responses from these services, and aggregates them. The aggregation is returned to the original consumer :

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

An example of service unit configuration :

{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<!-- JBI descriptor for the PEtALS component "EIP"-->
<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|1-n]
{note}

{note:title=Caution}
message exchange pattern of the incoming exchange is {{InOut}}.
{note}

{note:title=Caution}
By default, the process stops when a Fault is returned by the provider. To continue the process even if a fault is thrown, 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 the provider. To continue the process even if an exception is thrown, set the exception-robust to {{TRUE}}. The exception is concatenate with the others results.
{note}

h3. Routing-Slip Pattern

*Enterprise Integration Pattern*
!routingslip.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{table-plus}
|| Parameter || Description \\ || Default \\ || Required by pattern \\ ||
| eip | The name of the pattern to execute : {{routing-slip}}. \\ | \- | all |
| fault-to-exception \\ | If true, a fault received from the target service is transformed to an exception into the source exchange. \\ | false | bridge \\
router \\
dynamicrouter \\
routing-slip \\
dispatcher |
{table-plus}

The EIP Component chains invocation of the referenced services in the {{consumes}} sections, in the order that they are declared. The IN message of the incoming exchange is sent to the first service; the OUT response of this service is sent to the second service as an IN message, and so on. The last target exchange is matched with the source exchange as better as possible. So :&nbsp;
* If the source exchange needs a response (InOut or InOptionalOut patterns) and no response are received (InOnly, RobustInOnly or InOptionalOut 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 source exchange doesn't accept a response (InOnly or RobustInOnly patterns) and a response is received (InOut or InOptionalOut patterns), the response is ignored.
* If the source exchange doesn't 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 :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>

<!-- JBI descriptor for the PEtALS component "EIP"-->
<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|1-n]{note}
\\
{note:title=Caution}by default, the {{process}} stops when a Fault is returned by the provider if it doesn't use the InOnly Message Exchange Pattern{note}
\\
{note:title=Caution}by default, the process stops when an Exception is returned by the provider{note}
\\
{note:title=Caution}message exchange pattern of all the target exchanges, except the last, is {{InOut{}}}{note}
\\
{note:title=Caution}all the Message Exchange Pattern are accepted for the source exchange{note}


h3. Wire-Tap Pattern

*Enterprise Integration Pattern*
!wiretap.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{table-plus}
|| Parameter || Description \\ || Default \\ || Required by pattern \\ ||
| eip | The name of the pattern to execute :&nbsp;{{wire-tap}} \\ | \- | All |
| wiretap-way | Exchange way on which the message should be copied and sent to the monitoring service. \\
Values are request (copy IN), response (copy OUT/Fault),&nbsp;{{request-response}}&nbsp;(copy IN and OUT/Fault),&nbsp;{{request-on-response}}&nbsp;(copy IN after OUT is received; not copied if Fault or Error) \\ | \- | wire-tap |
{table-plus}
\\
The EIP Component copy the IN or OUT/Fault message of the exchange between the consumer and the provider of the functional service to a 'monitoring' service. The SU parameter wiretap-way determines which way of the invocation is relayed to the 'monitoring' service. At each way correspond a message of the exchange to copy. The copied message is sent to the 'monitoring' service as an IN message using the InOnly exchange pattern. The first consumes section references the provider, the second one references the 'monitoring' service.

An example of service unit configuration :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>

<!-- JBI descriptor for the PEtALS component "EIP" -->
<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:aggregateProvider"
service-name="test:aggregateProviderService1"
endpoint-name="aggregateProviderService1Endpoint">
<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:aggregateProvider"
service-name="test:aggregateProviderService2"
endpoint-name="aggregateProviderService2Endpoint">
<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 2.
{note}

{note:title=Caution}
message exchange pattern of the second target exchange, the "monitoring" exchange, is {{InOnly}}
{note}

{note:title=Caution}
all the Message Exchange Pattern are accepted for the source exchange
{note}


h3. Splitter Pattern

*Enterprise Integration Pattern*
!splitter.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{table-plus}
|| Parameter \\ || Description \\ || Default \\ || ||
| eip \\ | The name of the pattern to execute : {{splitter}} \\ | \- | All |
| test \\ | XPath condition applied on the message to split the source exchange \\ | \- | aggregator\\
splitter\\
router\\
dynamic-router\\
aggregator \\
splitter \\
router \\
dynamic-router |
| attachment \\ | true to split the source exchange on the attachments, false to split it on the IN content | false | splitter |
| fault-robust \\ | If true, a fault thrown by a target exchange don't stop the process and don't change the original exchange status to FAULT | false | scatter-gather \\
splitter |

*Enterprise Integration Pattern*
!bridge.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{loremipsum:5}

h3. Router Pattern

*Enterprise Integration Pattern*
!router.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{loremipsum:5}

h3. Dynamic Router Pattern

*Enterprise Integration Pattern*
!dynamicrouter.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{loremipsum:5}

h3. Dispatcher Pattern

*Enterprise Integration Pattern*
!dispatcher.gif!

*Configuration of a Service Unit to provide a service (EIP)*
{loremipsum:5}