Content Enricher - 6.3

Talend ESB Mediation Developer Guide

EnrichVersion
6.3
EnrichProdName
Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
task
Design and Development
EnrichPlatform
Talend ESB

Camel supports the Content Enricher from the EIP patterns using a Message Translator, an arbitrary Processor in the routing logic, or using the enrich DSL element to enrich the message.

Content enrichment using a Message Translator or a Processor

Using the Fluent Builders

You can use Templating to consume a message from one destination, transform it with something like Camel Component: Velocity or XQuery, and then send it on to another destination. For example using InOnly (one way messaging)

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm").
  to("activemq:Another.Queue");

If you want to use InOut (request-reply) semantics to process requests on the My.Queue queue on Camel Component: ActiveMQ with a template generated response, then sending responses back to the JMSReplyTo Destination you could use this:

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm");

We can also use Bean Integration to use any Java method on any bean to act as the transformer

from("activemq:My.Queue").
  beanRef("myBeanName", "myMethodName").
  to("activemq:Another.Queue");

For further examples of this pattern in use you could look at one of the JUnit tests

Using Spring XML

<route>
  <from uri="activemq:Input"/>
  <bean ref="myBeanName" method="doTransform"/>
  <to uri="activemq:Output"/>
</route>

Content enrichment using the enrich DSL element

Camel comes with two flavors of content enricher in the DSL

  • enrich

  • pollEnrich

enrich uses a Producer to obtain the additional data. It is usually used for Request Reply messaging, for instance to invoke an external web service. pollEnrich on the other hand uses a Polling Consumer to obtain the additional data. It is usually used for Event Message messaging, for instance to read a file.

Warning

pollEnrich does not access any data from the current Exchange which means when polling it cannot use any of the existing headers you may have set on the Exchange. For example you cannot set a filename in the Exchange.FILE_NAME header and use pollEnrich to consume only that file. For that you must set the filename in the endpoint URI.

Instead of using enrich you can use Recipient List and have dynamic endpoints and define an AggregationStrategy on the Recipient List which then would work as a enrich would do.

Enrich Options

Name

Default Value

Description

uri The endpoint uri for the external service to enrich from. You must use either uri or ref.
ref Refers to the endpoint for the external service to enrich from. You must use either uri or ref.
strategyRef Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing message. By default Camel will use the reply from the external service as outgoing message. From Camel 2.12 onwards you can also use a POJO as the AggregationStrategy, see the Aggregate page for more details.
strategyMethodName 

Camel 2.12: This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy. See the Aggregate page for more details.

strategyMethodAllowNullfalse

Camel 2.12: If this option is false then the aggregate method is not used if there was no data to enrich. If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy. See the Aggregate page for more details.

Using the Fluent Builders

AggregationStrategy aggregationStrategy = ...

from("direct:start")
.enrich("direct:resource", aggregationStrategy)
.to("direct:result");

from("direct:resource")
...

The content enricher ( enrich ) retrieves additional data from a resource endpoint in order to enrich an incoming message (contained in the original exchange ). An aggregation strategy is used to combine the original exchange and the resource exchange. The first parameter of the AggregationStrategy.aggregate(Exchange, Exchange) method corresponds to the the original exchange, the second parameter the resource exchange. The results from the resource endpoint are stored in the resource exchange's out-message. Here's an example template for implementing an aggregation strategy.

public class ExampleAggregationStrategy implements AggregationStrategy {

    public Exchange aggregate(Exchange original, Exchange resource) {
        Object originalBody = original.getIn().getBody();
        Object resourceResponse = resource.getIn().getBody();
        // combine original body and resourceResponse
        Object mergeResult = ... 
        if (original.getPattern().isOutCapable()) {
            original.getOut().setBody(mergeResult);
        } else {
            original.getIn().setBody(mergeResult);
        }
        return original;
    }
}

Using this template the original exchange can be of any pattern. The resource exchange created by the enricher is always an in-out exchange.

Using Spring XML

The same example in the Spring DSL

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <enrich uri="direct:resource" strategyRef="aggregationStrategy"/>
    <to uri="direct:result"/>
  </route>
  <route>
    <from uri="direct:resource"/>
    ...
  </route>
</camelContext>

<bean id="aggregationStrategy" class="..." />

Aggregation strategy is optional

The aggregation strategy is optional. If you do not provide it Camel will by default just use the body obtained from the resource.

from("direct:start")
  .enrich("direct:resource")
  .to("direct:result");

In the route above the message send to the direct:result endpoint will contain the output from the direct:resource as we do not use any custom aggregation.

And in Spring DSL just omit the strategyRef attribute:

<route>
    <from uri="direct:start"/>
    <enrich uri="direct:resource"/>
    <to uri="direct:result"/>
</route>

Content enrichment using pollEnrich

The pollEnrich works just as the enrich option however as it uses a Polling Consumer we have 3 methods when polling

  • receive

  • receiveNoWait

  • receive(timeout)

PollEnrich Options

Name

Default Value

Description

uri 

The endpoint uri for the external service to enrich from. You must use either uri or ref.

ref 

Refers to the endpoint for the external service to enrich from. You must use either uri or ref.

strategyRef 

Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing message. By default Camel will use the reply from the external service as outgoing message. From Camel 2.12 onwards you can also use a POJO as the AggregationStrategy, see the Aggregate page for more details.

strategyMethodName 

Camel 2.12: This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy. See the Aggregate page for more details.

strategyMethodAllowNullfalse

Camel 2.12: If this option is false then the aggregate method is not used if there was no data to enrich. If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy. See the Aggregate page for more details.

timeout-1

Timeout in millis when polling from the external service. See below for important details about the timeout.

Warning

By default Camel will use the receive. Which may block until there is a message available. It is therefore recommended to always provide a timeout value, to make this clear that we may wait for a message, until the timeout is hit.

If there is no data then the newExchange in the aggregation strategy is null.

You can pass in a timeout value that determines which method to use:

  • if timeout is -1 or other negative number then receive is selected (Important: the receive method may block if there is no message)

  • if timeout is 0 then receiveNoWait is selected

  • otherwise receive(timeout) is selected

The timeout values is in millis.

Warning

pollEnrich does not access any data from the current Exchange which means when polling it cannot use any of the existing headers you may have set on the Exchange. For example you cannot set a filename in the Exchange.FILE_NAME header and use pollEnrich to consume only that file. For that you must set the filename in the endpoint URI.

In this example we enrich the message by loading the content from the file named inbox/data.txt.

from("direct:start")
   .pollEnrich("file:inbox?fileName=data.txt")
   .to("direct:result");

And in XML DSL you do:

<route>
   <from uri="direct:start"/>
   <pollEnrich uri="file:inbox?fileName=data.txt"/>
   <to uri="direct:result"/>
</route>

If there is no file then the message is empty. We can use a timeout to either wait (potentially forever) until a file exists, or use a timeout to wait a certain period. For example to wait up to 5 seconds you can do:

<route>
   <from uri="direct:start"/>
   <pollEnrich uri="file:inbox?fileName=data.txt" timeout="5000"/>
   <to uri="direct:result"/>
</route>