servicemix-eip

The servicemix-eip component is a routing container where different routing patterns can be deployed as service unit.
This component is based on the great Enterprise Integration Patterns book.

Supported patterns:

• Content-Based Router
• Message Filter
• Pipeline
• Static Recipient List
• Static Routing Slip
• Wire Tap
• XPath Splitter
• Aggregator
• Content Enricher

In addition, this component can use all ServiceMix flows (including clustered and transactional flows), can be configured to be resilient to crashes and supports full fail-over to another node when clustered.

Using servicemix-eip as a standard JBI component

Installation

Installing the servicemix-eip component can be done in several ways:

• drop the installer zip in an hotdeploy directory monitored by ServiceMix
• using ant tasks

Note that when using ant tasks, the component is not started, you will have to start it manually using ant tasks or a console.

Configuration

TODO: configure a persistent / clustered store

Service Unit packaging

Content of xbean.xml file to be packaged as a SU

<beans xmlns:eip="http://servicemix.apache.org/eip/1.0">

  ... add eip patterns here ...

</beans>

Using servicemix-eip in a ServiceMix xml configuration file

<beans xmlns:sm="http://servicemix.apache.org/config/1.0"
       xmlns:eip="http://servicemix.apache.org/eip/1.0">

  <sm:container ...>
    <sm:activationSpecs>
      <sm:activationSpec>
        <sm:component>
          <eip:component>
            <eip:endpoints>

              ... add eip patterns here ...

            </eip:endpoints>
          </eip:component>
        </sm:component>
      </sm:activationSpec>
      ...
    </sm:activationSpecs>
  </sm:container>
  ...

</beans>

Patterns

Content-Based router

ContentBasedRouter can be used for all kind of content-based routing.
This pattern implements the Content-Based Router pattern.

<eip:content-based-router service="test:router" endpoint="endpoint">
  <eip:rules>
    <eip:routing-rule>
      <eip:predicate>
        <eip:xpath-predicate xpath="count(/test:echo) = 1" namespaceContext="#nsContext" />
      </eip:predicate>
      <eip:target>
        <eip:exchange-target uri="endpoint:http://test/pipeline/endpoint" />
      </eip:target>
    </eip:routing-rule>
    <eip:routing-rule>
      <!-- there is no predicate, so this is the default destination -->
      <eip:target>
        <eip:exchange-target service="test:recipients" />
      </eip:target>
    </eip:routing-rule>
  </eip:rules>
</eip:content-based-router>

Message Filter

MessageFilter allows filtering incoming JBI exchanges. As it drops unwanted messages and in an InOut exchange a response is required, MessageFilter and InOut MEPs cannot be used together.
This pattern implements the Message Filter pattern.

<eip:message-filter service="test:messageFilter" endpoint="endpoint">
  <eip:target>
    <eip:exchange-target service="test:trace3" />
  </eip:target>
  <eip:filter>
    <eip:xpath-predicate xpath="count(/test:world) = 1" namespaceContext="#nsContext"/>
  </eip:filter>
</eip:message-filter>

Pipeline

The Pipeline component is a bridge between an In-Only (or Robust-In-Only) MEP and an In-Out MEP. When the Pipeline receives an In-Only MEP, it will send the input in an In-Out MEP to the tranformer destination and forward the response in an In-Only MEP to the target destination.

The old org.apache.servicemix.components.util.PipelineComponent will be deprecated. This one offers the same feature but can be safely clustered and use in a transactional enviromnent.

<eip:pipeline service="test:pipeline" endpoint="endpoint">
  <eip:transformer>
    <eip:exchange-target service="test:routingSlip" />
  </eip:transformer>
  <eip:target>
    <eip:exchange-target service="test:trace2" />
  </eip:target>
</eip:pipeline>

Static Recipient List

The StaticRecipientList component will forward an input In-Only or Robust-In-Only exchange to a list of known recipients.
This component implements the Recipient List pattern, with the limitation that the recipient list is static.

<eip:static-recipient-list service="test:recipients" endpoint="endpoint">
  <eip:recipients>
    <eip:exchange-target service="test:messageFilter" />
    <eip:exchange-target service="test:trace4" />
  </eip:recipients>
</eip:static-recipient-list>

Static Routing Slip

A RoutingSlip component can be used to route an incoming In-Out exchange through a series of target services.
This component implements the Routing Slip pattern, with the limitation that the routing table is static.
This component only uses In-Out MEPs and errors or faults sent by targets are reported back to the consumer, thus interrupting the routing process.

<eip:static-routing-slip service="test:routingSlip" endpoint="endpoint">
  <eip:targets>
    <eip:exchange-target service="test:echo" />
    <eip:exchange-target service="test:echo" />
  </eip:targets>
</eip:static-routing-slip>

Wire Tap

A WireTap component can be used to forward a copy of the input message to a listener in a proxy fashion.
This component implements the WireTap pattern.
It can handle all four standard MEPs, but will only send an In-Only MEP to the listener.
The originating service must be configured to send messages to the WireTap directly.
In the case of an In-Out MEP, this means that the WireTap needs to be configured to send the exchange along to the destination service.

<eip:wire-tap service="test:wireTap" endpoint="endpoint">
  <eip:target>
    <eip:exchange-target service="test:xpathSplitter" />
  </eip:target>
  <eip:inListener>
    <eip:exchange-target service="test:trace1" />
  </eip:inListener>
</eip:wire-tap>

XPath Splitter

The XPathSplitter component implements the Splitter pattern using an xpath expression to split the incoming xml.

<eip:xpath-splitter service="test:xpathSplitter" endpoint="endpoint" 
                    xpath="/*/*" namespaceContext="#nsContext">
  <eip:target>
    <eip:exchange-target uri="service:http://test/router" />
  </eip:target>
</eip:xpath-splitter>

SplitAggregator

The SplitAggregator is an aggregator mainly usefull to collect messages that have been created using a splitter.
It relies on several properties that should be set on the exchanges (count, index, correlationId).

<eip:split-aggregator service="test:aggregator" endpoint="endpoint">
  <eip:target>
    <eip:exchange-target service="test:trace5" />
  </eip:target>
</eip:split-aggregator>

Content Enricher

With a Content Enricher you can extract additional information from a source and add this information to your message. This is useful if the calling service for example extracts a 'userID' and your target system is only aware of a 'userName'. By using the Content-Enricher you could extract this information from a source system and add this additional information ('userName') to your message.

<eip:content-enricher service="test:contentEnricher" endpoint="endpoint">
  <eip:enricherTarget>
    <eip:exchange-target service="test:additionalInformationExtracter" />
  </eip:enricherTarget>
  <eip:target>
    <eip:exchange-target service="test:myTarget" />
  </eip:target>
</eip:content-enricher>

Tips

ExchangeTarget

All patterns use the <exchange-target /> tag to specify the target of a JBI exchange.
This element has the following attributes:

If you want to target a given interface, just set the interface attribute. Else you have to set the service attribute, and optionally the endpoint attribute if you want to specify the JBI endpoint instead of a service name.

NamespaceContext

Some patterns use XPath expression. To use such expressions on an xml with namespaces, you need to define a NamespaceContext.

<eip:namespace-context id="nsContext">
  <eip:namespaces>
    <eip:namespace prefix="test">http://test</eip:namespace>
  </eip:namespaces>
</eip:namespace-context>

This NamespaceContext can be referenced by a namespaceContext attribute as shown in the XPathSplitter or MessageFilter examples.

Predicates

Some patterns uses predicates to test a given JBI exchange. The only predicate currently implemented is the XPathPredicate, but you can implement your own and deploy it with the service unit.

TODO: link to a page documenting the classpath / location elements for deploying code inside xbean SU

Creating your own patterns

Some classes have been designed to be extensible, this includes:

• org.apache.servicemix.eip.support.AbstractAggregator
• org.apache.servicemix.eip.support.AbstractSplitter