<commit_before>= Poll Enrich EIP
:doctitle: Poll Enrich
:shortname: pollEnrich
:description: Enriches messages with data polled from a secondary resource
:since: 
:supportlevel: Stable

Camel supports the
http://www.enterpriseintegrationpatterns.com/DataEnricher.html[Content
Enricher] from the xref:enterprise-integration-patterns.adoc[EIP
patterns].

image::eip/DataEnricher.gif[image]

In Camel the Content Enricher can be done in several ways:

* Using xref:enrich-eip.adoc[Enrich] EIP or xref:pollEnrich-eip.adoc[Poll Enrich] EIP
* Using a xref:message-translator.adoc[Message Translator]
* Using a xref:manual::processor.adoc[Processor] with the enrichment programmed in Java
* Using a xref:bean-eip.adoc[Bean] EIP with the enrichment programmed in Java

The most natural Camel approach is using xref:enrich-eip.adoc[Enrich] EIP,
which comes as two kinds:

* xref:enrich-eip.adoc[Enrich] EIP - This is the most common content enricher that uses a `Producer` to obtain the data.
It is usually used for xref:requestReply-eip.adoc[Request Reply] messaging, for instance to invoke an external web service.

* xref:pollEnrich-eip.adoc[Poll Enrich] EIP - Uses a xref:polling-consumer.adoc[Polling
Consumer] to obtain the additional data. It is usually used for
xref:event-message.adoc[Event Message] messaging, for instance to read a
file or download a xref:ROOT:ftp-component.adoc[FTP] file.

NOTE: This page documents the Poll Enrich EIP.

== Options

// eip options: START
include::partial$eip-options.adoc[]
// eip options: END

== Content enrichment using Poll Enrich EIP

`pollEnrich` uses a xref:polling-consumer.adoc[Polling Consumer] to obtain the additional data.
It is usually used for xref:event-message.adoc[Event Message] messaging, for instance to read a file or download a FTP file.

The `pollEnrich` works just the same as `enrich`,
however as it uses a xref:polling-consumer.adoc[Polling Consumer] we have three methods when polling:

* `receive` - Waits until a message is available and then returns it. *Warning* that this method could block indefinitely if no messages are available.
* `receiveNoWait` - Attempts to receive a message exchange immediately without waiting and returning `null` if a message exchange is not available yet.
* `receive(timeout)` - Attempts to receive a message exchange, waiting up to the given timeout to expire if a message is not yet available. Returns the message or `null` if the timeout expired.

=== Poll Enrich with timeout

It is good practice to use timeout value.

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.

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.

=== Using Poll Enrich

The content enricher (`pollEnrich`) retrieves additional data from a _resource endpoint_ in order to enrich an incoming message (contained in the _original exchange_).

An `AggregationStrategy` is used to combine the original exchange and the _resource exchange_. The first parameter of the `AggregationStrategy.aggregate(Exchange, Exchange)` method corresponds to the original exchange, the second parameter the resource exchange.

Here's an example for implementing an `AggregationStrategy`, which merges the two data together
as a `String` with colon separator:

[source,java]
----
public class ExampleAggregationStrategy implements AggregationStrategy {

    public Exchange aggregate(Exchange original, Exchange resource) {
        // this is just an example, for real-world use-cases the
        // aggregation strategy would be specific to the use-case

        if (newExchange == null) {
            return oldExchange;
        }
        Object oldBody = oldExchange.getIn().getBody();
        Object newBody = newExchange.getIn().getBody();
        oldExchange.getIn().setBody(oldBody + ":" + newBody);
        return oldExchange;
    }

}
----

You then use the `AggregationStrategy` with the `pollEnrich` in the Java DSL as shown:

[source,java]
----
AggregationStrategy aggregationStrategy = ...

from("direct:start")
  .pollEnrich("file:inbox?fileName=data.txt", 10000, aggregationStrategy)
  .to("mock:result");
----

In the example Camel will poll a file (timeout 10 seconds).
The `AggregationStrategy` is then used to merge the file with the existing `Exchange`.

In XML DSL you use `pollEnrich` as follows:

[source,xml]
----
<bean id="myStrategy" class="com.foo.ExampleAggregationStrategy"/>

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <pollEnrich timeout="10000" strategyRef="myStrategy">
      <constant>"file:inbox?fileName=data.txt"</constant>
    </pollEnrich>
    <to uri="mock:result"/>
  </route>
</camelContext>
----

=== Using Poll Enrich with Rest DSL

You can also use `pollEnrich` with xref:manual::rest-dsl.adoc[Rest DSL] to
for example download a file from xref:ROOT:aws2-s3-component.adoc[AWS S3] as the response of an API call.

[source,xml]
----
<rest path="/report">
    <description>Report REST API</description>
    <get uri="/{id}/payload">
        <route id="report-payload-download">
            <pollEnrich id="pollEnrich">
                <simple>aws-s3:xavier-dev?amazonS3Client=#s3client&amp;deleteAfterRead=false&amp;fileName=report-file.pdf</simple>
            </pollEnrich>
        </route>
    </get>
</rest>
----

=== Poll Enrich with Dynamic Endpoints

Both `enrich` and `pollEnrich` supports using dynamic uris computed based on information from the current `Exchange`.

For example to `pollEnrich` from an endpoint that uses a header to indicate a SEDA queue name:

[source,java]
----
from("direct:start")
  .pollEnrich().simple("seda:${header.queueName}")
  .to("direct:result");
----

And in XML DSL:

[source,xml]
----
<route>
  <from uri="direct:start"/>
  <pollEnrich>
    <simple>seda:${header.queueName}</simple>
  </pollEnrich>
  <to uri="direct:result"/>
</route>
----

TIP: See the `cacheSize` option for more details on _how much cache_ to use depending on how many or few unique endpoints are used.

== See More
<commit_msg>Polished docs<commit_after>= Poll Enrich EIP
:doctitle: Poll Enrich
:shortname: pollEnrich
:description: Enriches messages with data polled from a secondary resource
:since: 
:supportlevel: Stable

Camel supports the
http://www.enterpriseintegrationpatterns.com/DataEnricher.html[Content
Enricher] from the xref:enterprise-integration-patterns.adoc[EIP
patterns].

image::eip/DataEnricher.gif[image]

In Camel the Content Enricher can be done in several ways:

* Using xref:enrich-eip.adoc[Enrich] EIP or xref:pollEnrich-eip.adoc[Poll Enrich] EIP
* Using a xref:message-translator.adoc[Message Translator]
* Using a xref:manual::processor.adoc[Processor] with the enrichment programmed in Java
* Using a xref:bean-eip.adoc[Bean] EIP with the enrichment programmed in Java

The most natural Camel approach is using xref:enrich-eip.adoc[Enrich] EIP,
which comes as two kinds:

* xref:enrich-eip.adoc[Enrich] EIP - This is the most common content enricher that uses a `Producer` to obtain the data.
It is usually used for xref:requestReply-eip.adoc[Request Reply] messaging, for instance to invoke an external web service.

* xref:pollEnrich-eip.adoc[Poll Enrich] EIP - Uses a xref:polling-consumer.adoc[Polling
Consumer] to obtain the additional data. It is usually used for
xref:event-message.adoc[Event Message] messaging, for instance to read a
file or download a xref:ROOT:ftp-component.adoc[FTP] file.

NOTE: This page documents the Poll Enrich EIP.

== Options

// eip options: START
include::partial$eip-options.adoc[]
// eip options: END

== Content enrichment using Poll Enrich EIP

`pollEnrich` uses a xref:polling-consumer.adoc[Polling Consumer] to obtain the additional data.
It is usually used for xref:event-message.adoc[Event Message] messaging, for instance to read a file or download a FTP file.

The `pollEnrich` works just the same as `enrich`,
however as it uses a xref:polling-consumer.adoc[Polling Consumer] we have three methods when polling:

* `receive` - Waits until a message is available and then returns it. *Warning* that this method could block indefinitely if no messages are available.
* `receiveNoWait` - Attempts to receive a message exchange immediately without waiting and returning `null` if a message exchange is not available yet.
* `receive(timeout)` - Attempts to receive a message exchange, waiting up to the given timeout to expire if a message is not yet available. Returns the message or `null` if the timeout expired.

=== Poll Enrich with timeout

It is good practice to use timeout value.

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.

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.

=== Using Poll Enrich

The content enricher (`pollEnrich`) retrieves additional data from a _resource endpoint_ in order to enrich an incoming message (contained in the _original exchange_).

An `AggregationStrategy` is used to combine the original exchange and the _resource exchange_. The first parameter of the `AggregationStrategy.aggregate(Exchange, Exchange)` method corresponds to the original exchange, the second parameter the resource exchange.

Here's an example for implementing an `AggregationStrategy`, which merges the two data together
as a `String` with colon separator:

[source,java]
----
public class ExampleAggregationStrategy implements AggregationStrategy {

    public Exchange aggregate(Exchange original, Exchange resource) {
        // this is just an example, for real-world use-cases the
        // aggregation strategy would be specific to the use-case

        if (newExchange == null) {
            return oldExchange;
        }
        Object oldBody = oldExchange.getIn().getBody();
        Object newBody = newExchange.getIn().getBody();
        oldExchange.getIn().setBody(oldBody + ":" + newBody);
        return oldExchange;
    }

}
----

You then use the `AggregationStrategy` with the `pollEnrich` in the Java DSL as shown:

[source,java]
----
AggregationStrategy aggregationStrategy = ...

from("direct:start")
  .pollEnrich("file:inbox?fileName=data.txt", 10000, aggregationStrategy)
  .to("mock:result");
----

In the example Camel will poll a file (timeout 10 seconds).
The `AggregationStrategy` is then used to merge the file with the existing `Exchange`.

In XML DSL you use `pollEnrich` as follows:

[source,xml]
----
<bean id="myStrategy" class="com.foo.ExampleAggregationStrategy"/>

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <pollEnrich timeout="10000" strategyRef="myStrategy">
      <constant>"file:inbox?fileName=data.txt"</constant>
    </pollEnrich>
    <to uri="mock:result"/>
  </route>
</camelContext>
----

=== Using Poll Enrich with Rest DSL

You can also use `pollEnrich` with xref:manual::rest-dsl.adoc[Rest DSL] to
for example download a file from xref:ROOT:aws2-s3-component.adoc[AWS S3] as the response of an API call.

[source,xml]
----
<rest path="/report">
    <description>Report REST API</description>
    <get uri="/{id}/payload">
        <route id="report-payload-download">
            <pollEnrich>
                <constant>aws-s3:xavier-dev?amazonS3Client=#s3client&amp;deleteAfterRead=false&amp;fileName=report-file.pdf</constant>
            </pollEnrich>
        </route>
    </get>
</rest>
----

Notice that the enriched endpoint is a constant, however Camel also supports dynamic endpoints which is covered next.

=== Poll Enrich with Dynamic Endpoints

Both `enrich` and `pollEnrich` supports using dynamic uris computed based on information from the current `Exchange`.

For example to `pollEnrich` from an endpoint that uses a header to indicate a SEDA queue name:

[source,java]
----
from("direct:start")
  .pollEnrich().simple("seda:${header.queueName}")
  .to("direct:result");
----

And in XML DSL:

[source,xml]
----
<route>
  <from uri="direct:start"/>
  <pollEnrich>
    <simple>seda:${header.queueName}</simple>
  </pollEnrich>
  <to uri="direct:result"/>
</route>
----

TIP: See the `cacheSize` option for more details on _how much cache_ to use depending on how many or few unique endpoints are used.

== See More

{'fraction_non_alphanumeric': 0.09847963939185575, 'fraction_numerical': 0.003056001222400489, 'mean_word_length': 4.323302155347703, 'pattern_counts': {'":': 2, '<': 65, '<?xml version=': 0, '>': 65, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1567742', 'n_tokens_mistral': 3950, 'n_tokens_neox': 3732, 'n_words': 1476}