Petals Documentation > Petals ESB > Petals Components > Components User Guide > Petals-SE-EIP > Petals-SE-EIP 2.8.x

Petals-SE-EIP 2.8.x

Integration Pattern supported

  • Aggregator
  • Bridge
  • Dispatcher
  • Router
  • DynamicRouter
  • RoutingSlip
  • ScatterGather
  • WireTap
  • Splitter
Table of contents
Contributors
No contributors found for: authors on selected page(s)

Service Configuration

Service Unit descriptor

<?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>
Configuration of a Service Unit to provide a service (JBI)

Parameter Description
Default
Required
provides Describe the JBI service that will be exposed into the JBI bus. Interface (QName), Service (QName) and Endpoint (String) attributes are required. - Yes

Configuration of a Service Unit to provide a service (CDK)

Parameter Description
 Default
 Required
timeout Timeout in milliseconds of a synchronous send. This parameter is used by the method sendSync (Exchange exchange) proposes by the CDK Listeners classes.
Set it to 0 for an infinite timeout. 		30000 No
exchange-properties This sections defines the list of properties to set to the JBI exchange when processing a service. - No
message-properties This sections defines the list of properties to set to the JBI message when processing a service. - No
validate-wsdl Activate the validation of the WSDL when deploying a service unit. true No
wsdl
Path to the WSDL document describing services and operations exposed by the provided JBI endpoints defined in the SU.
The value of this parameter is :
  • an URL
  • a file relative to the root of the SU package
    If not specified, a basic WSDL description is automaticaly provided by the CDK.
- No
forward-attachments
Defines if attachment will be forwarded from IN message to OUT message.
false No
forward-message-properties
Defines if the message properties will be forwarded from IN message to OUT message. false No
forward-security-subject
Defines if the security subject will be forwarded from IN message to OUT message. false No


Configuration of a Service Unit to consume a service (JBI)

Parameter Description Default Required
consumes Refer JBI service to invoke into the JBI bus.
You can define an explicit endpoint: interface (QName) / Service (QName) / Endpoint (String) attributes
Or define implicit endpoint, to let the container routing according to QOS configurations (HA...):
-by Interface attribute (QName);
-by Service attribute (QName). 		- Yes


Interceptor

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--...-->
<petalsCDK:su-interceptors>
  <petalsCDK:send>
    <petalsCDK:interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
      <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
    </petalsCDK:interceptor>
  </petalsCDK:send>
  <petalsCDK:accept>
    <petalsCDK:interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:interceptor>
  </petalsCDK:accept>
  <petalsCDK:send-response>
    <petalsCDK:Interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:Interceptor>
  </petalsCDK:send-response>
  <petalsCDK:accept-response>
    <petalsCDK:Interceptor name="myInterceptorName">
      <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    </petalsCDK:Interceptor>
  </petalsCDK:accept-response>
</petalsCDK:su-interceptors>
<!--...-->

Interceptors configuration for SU (CDK)

Parameter Description Default Required
send Interceptor dedicated to send phase, for an exchange sent by a consumer - No
accept Interceptor dedicated to receive phase, for an exchange received by a provider - No
send-response Interceptor dedicated to send phase, for an exchange (a response) received by a consumer - No
accept-response Interceptor dedicated to receive phase, for an exchange sent (a response) by a provider - No
interceptor - name Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. - Yes
param[] - name The name of the parameter to use for the interceptor for this SU - No
param[] The value of the parameter to use for the interceptor for this SU - No

Processing an integration pattern

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.

The Service Unit contains also 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
Caution
The MEP is mandatory for each consumes sections.
Caution
Either an operation must be specified in the consumes sections or the 'original' operation is used for 'sub-service' requests.

Aggregator Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Aggregator)

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

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 :

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

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 :

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

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 :

<?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>
Caution
Message order is kept from incoming sequence to the outgoing message.
Caution
Consumes sections cardinality is [1-1].
Caution
All MEPs are accepted for the 'original' consumer and the 'sub-service'

Scatter-Gather Pattern

Enterprise Integration Pattern


Configuration of a Service Unit to provide a service (Scatter-Gather)

Parameter Description Default
eip The name of the pattern to execute : scatter-gather
-
fault-robust If true, a fault returned by a 'sub-service' exchange do not interrupt the process of the pattern
false
exception-robust If true, an exception thrown by a 'sub-service' exchange do not interrupt the process of the pattern
false

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 :

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

An example of Service Unit configuration for the scatter-gather pattern :

<?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>
Caution
Consumes sections cardinality is [1-n].
Caution
Message exchange pattern accepted from the 'original' consumer is InOut.
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.
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.

Routing-Slip Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Routing Slip)

Parameter Description Default
eip The name of the pattern to execute : routing-slip.
-
fault-to-exception If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange.
false

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 : 
    <result xmlns="http://petals.ow2.org/petals-se-eip/bridge">
    Bridge: no content into the final target exchange
</result>
  • 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:

<?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>


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

Wire-Tap Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Wire-Tap)

Parameter Description Default
eip The name of the pattern to execute wire-tap
-
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)
-

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 :

<?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: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>
Caution
Consumes sections cardinality is 2.
Caution
MEP of the observer 'sub-service' is InOnly.
Caution
All the MEP are accepted from the 'original' consumer and the target 'sub-service'.

Splitter Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Splitter)

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

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 :

<result xmlns="http://petals.ow2.org/petals-se-eip/splitter">
  ...
</result>

An example of Service Unit configuration for the Splitter pattern :

<?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: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>
Caution
consumes sections cardinality is 1.
Caution
MEP accepted from the 'original' consumer is InOut.
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.
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.

Bridge Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Bridge)

Parameter Description Default
eip The name of the pattern to execute bridge
-
fault-to-exception If true, a fault received from a 'sub-service' service is transformed to an exception into the 'original' exchange.
false

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: 
    <result xmlns="http://petals.ow2.org/petals-se-eip/bridge">
  Bridge: no response from the last 'sub-service'
</result>
  • 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 :

<?xml version="1.0"?>

<!-- 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: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>
Caution
Consumes sections cardinality is 1.

Router Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Router)

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

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 :

<?xml version="1.0"?>

<!-- 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: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>
Caution
Consumes sections cardinality is the number of defined conditions plus 1.
Caution
The last Consumes section is the default service to invoke if no condition has been matched.

Dynamic Router Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Dynamic-Router)

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

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 :

<?xml version="1.0"?>

<!-- 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: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>
Caution
Consumes sections cardinality is the number of conditions plus 2.
Caution
The first Consumes section is the 'sub-service' to invoke to get the message to evaluate. Its pattern is InOut.
Caution
The last consumes section is the default service to invoke if no condition has been matched.

Dispatcher Pattern

Enterprise Integration Pattern

Configuration of a Service Unit to provide a service (Dispatcher)

Parameter Description Default
eip The name of the pattern to execute : dispatcher.
-

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 :

<?xml version="1.0"?>

<!-- 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: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>
Caution
Consumes sections cardinality is [1-n].
Caution
MEP of the 'original' exchange and the 'sub-services' must be InOnly.

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 :

/**
 * 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();
}


Use the ExchangeContext to interact with the container, during your pattern processing :

/**
 * 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();
}


Extends the JBI.xml file of the component to reference your new pattern.

Component Configuration

<?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>
Configuration of the component, CDK part

Parameter Description Default Required Scope
acceptor-pool-size The size of the thread pool used to accept Message Exchanges from the NMR. Once a message is accepted, its processing is delegated to the processor pool thread.
3
Yes
Runtime
acceptor-retry-number Number of tries to submit a message exchange to a processor for processing before to declare that it cannot be processed.
40
No
Installation
acceptor-retry-wait Base duration, in milliseconds, to wait between two processing submission tries. At each try, the new duration is the previous one added by this base duration multiplied by the try number plus a random value between 0 and 10.
250
No
Installation
acceptor-stop-max-wait The max duration (in milliseconds) of the stop of an acceptor before to force it to stop.
500
No
Runtime
message-processor-max-pool-size Max size of the object pool containing message exchange processors.
processor-max-pool-size
No
Runtime
processor-pool-size The size of the thread pool used to process Message Exchanges. Once a message is accepted, its processing is delegated to one of the thread of this pool.
10
Yes
Runtime
processor-max-pool-size The maximum size of the thread pool used to process Message Exchanges. The difference between this size and the processor-pool-size represents the dynamic threads that can be created and destroyed during overhead processing time.
50
No
Runtime
processor-keep-alive-time When the number of processors is greater than the core, this is the maximum time that excess idle processors will wait for new tasks before terminating, in seconds.
300
No
Runtime
processor-stop-max-wait The max duration (in milliseconds) of message exchange processing on stop phase.
15000
No
Runtime
time-beetween-async-cleaner-runs The time (in milliseconds) between two runs of the asynchronous message exchange cleaner.
2000
No
Installation
properties-file Name of the file containing properties used as reference by other parameters. Parameters reference the property name in the following pattern ${myPropertyName}. At runtime, the expression is replaced by the value of the property.

The value of this parameter is :
  • an URL
  • a file relative to the PEtALS installation path
  • an empty value to stipulate a non-using file
-
No
Installation
monitoring-sampling-period Period, in seconds, of a sample used by response time probes of the monitoring feature.
300
No
Installation

Definition of CDK parameter scope :

  • Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
  • Runtime: The paramater can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.


Configuration of the component (EIP)

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

Interceptor

Interceptors can be defined to inject some post or pre processing in the component during service processing.

Using interceptor is very sensitive and must be manipulate only by power users. An non properly coded interceptor engaged in a component can lead to uncontrolled behaviors, out of the standard process.

Example of an interceptor configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--...-->
<petalsCDK:component-interceptors>
  <petalsCDK:interceptor active="true" class="org.ow2.petals.myInterceptor" name="myInterceptorName">
    <petalsCDK:param name="myParamName">myParamValue</petalsCDK:param>
    <petalsCDK:param name="myParamName2">myParamValue2</petalsCDK:param>
  </petalsCDK:interceptor>
</petalsCDK:component-interceptors>
<!--...-->

Interceptors configuration for Component (CDK)

Parameter Description Default Required
interceptor - class Name of the interceptor class to implement. This class must extend the abstract class org.ow2.petals.component.common.interceptor.Interceptor. This class must be loadable from the component classloader, or in a dependent Shared Library classloader. - Yes
interceptor - name Logical name of the interceptor instance. It can be referenced to add extended parameters by a SU Interceptor configuration. - Yes
interceptor - active If true, the Interceptor instance is activated for every SU deployed on the component.
If false, the Interceptor can be activated:
-by the InterceptorManager Mbean at runtime, to activate the interceptor for every deployed SU.
-by a SU configuration 		- Yes
param[] - name The name of the parameter to use for the interceptor. - No
param[] The value of the parameter to use for the interceptor. - No

Monitoring the component

In this documentation, the term "Allocated threads" must be understood as "Active threads", see PETALSDISTRIB-37. This naming error will be fixed in the next version.

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.

Common metrics

The following metrics are provided through the Petals CDK, and are common to all components:

Metrics, as MBean attribute Description Detail of the value Configurable
MessageExchangeAcceptorThreadPoolMaxSize The maximum number of threads of the message exchange acceptor thread pool integer value, since the last startup of the component yes, through acceptor-pool-size
MessageExchangeAcceptorThreadPoolCurrentSize The current number of threads of the message exchange acceptor thread pool. Should be always equals to MessageExchangeAcceptorThreadPoolMaxSize. instant integer value no
MessageExchangeProcessorObjectPoolBorrowedObjectsCurrent The current number of borrowed object of the message exchange processor object pool instant integer value no
MessageExchangeProcessorObjectPoolBorrowedObjectsMax The maximum number of object of the message exchange processor object pool that was borrowed integer value, since the last startup of the component no
MessageExchangeProcessorObjectPoolIdleObjectsCurrent The current number of idel object of the message exchange processor object pool instant integer value no
MessageExchangeProcessorObjectPoolIdleObjectsMax The maximum number of object of the message exchange processor object pool that was idle integer value, since the last startup of the component no
MessageExchangeProcessorObjectPoolMaxSize The maximum size, in objects, of the message exchange processor object pool instant integer value yes, through processor-max-pool-size
MessageExchangeProcessorObjectPoolMinIdleSize The minimum size, in objects (in state idle), of the message exchange processor object pool instant integer value yes, through processor-pool-size
MessageExchangeProcessorObjectPoolExhaustion The number of message exchange processor object pool exhaustions integer counter value, since the last startup of the component no
MessageExchangeProcessorThreadPoolAllocatedThreadsCurrent The current number of allocated threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolAllocatedThreadsMax The maximum number of threads of the message exchange processor thread pool that was allocated integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolIdleThreadsCurrent The current number of idle threads of the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolIdleThreadsMax The maximum number of threads of the message exchange processor thread pool that was idle integer value, since the last startup of the component no
MessageExchangeProcessorThreadPoolMaxSize The maximum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-max
MessageExchangeProcessorThreadPoolMinSize The minimum size, in threads, of the message exchange processor thread pool instant integer value yes, through http-thread-pool-size-min
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent The current number of enqueued requests waiting to be processed by the message exchange processor thread pool instant integer value no
MessageExchangeProcessorThreadPoolQueuedRequestsMax The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool that was allocated since the last startup of the component instant integer value no
ServiceProviderInvokations The number of service provider invokations grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
 integer counter value since the last startup of the component no
ServiceProviderInvokationsResponseTimeAbs The aggregated response times of the service provider invokations since the last startup of the component grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
 n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time.
 no
ServiceProviderInvokationsResponseTimeRel The aggregated response times of the service provider invokations on the last sample, grouped by:
  • interface name, as QName, the invoked service provider,
  • service name, as QName, the invoked service provider,
  • invoked operation, as QName,
  • message exchange pattern,
  • and execution status (PENDING, ERROR, FAULT, SUCCEEDED).
 n-tuple value containing, in millisecond:
  • the maximum response time,
  • the average response time,
  • the minimum response time,
  • the 10-percentile response time (10% of the response times are lesser than this value),
  • the 50-percentile response time (50% of the response times are lesser than this value),
  • the 90-percentile response time (90% of the response times are upper than this value).
 no

Dedicated metrics

No dedicated metric is available.

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.

To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios.

Common alerts

Defect JMX Notification
A message exchange acceptor thread is dead
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.thread.dead
  • no user data
No more thread is available in the message exchange acceptor thread pool
  • type: org.ow2.petals.component.framework.process.message.acceptor.pool.exhausted
  • no user data
No more message exchange processor is available in the message exchange processor pool
  • type: org.ow2.petals.component.framework.process.message.processor.object.pool.exhausted
  • no user data
No more thread is available to run a message exchange processor
  • type: org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted
  • no user data

Dedicated alerts

No dedicated alert is available.

Labels

components-se-family components-se-family Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.