<commit_before>= Polling Consumer

Camel supports implementing the
http://www.enterpriseintegrationpatterns.com/PollingConsumer.html[Polling
Consumer] from the xref:enterprise-integration-patterns.adoc[EIP
patterns].

An application needs to consume Messages, but it wants to control when it consumes each message.

How can an application consume a message when the application is ready?

image::eip/PollingConsumerSolution.gif[image]

The application should use a Polling Consumer, one that explicitly makes a call when it wants to receive a message.

In Camel the `PollingConsumer` is represented by the
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer]
interface.

You can get hold of a `PollingConsumer` in several ways in Camel:

- Use xref:pollEnrich-eip.adoc[Poll Enrich] EIP

- Create a `PollingConsumer` instance via the
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/Endpoint.java[Endpoint.createPollingConsumer()]
method.

- Use the xref:latest@manual:ROOT:consumertemplate.adoc[ConsumerTemplate] to poll on demand.

== Using Polling Consumer

If you need to use Polling Consumer from within a route, then the xref:pollEnrich-eip.adoc[Poll Enrich] EIP can be used.

On the other hand if you need to use Polling Consumer programmatically,
then using xref:latest@manual:ROOT:consumertemplate.adoc[ConsumerTemplate] is a good choice.

And if you want to use the lower level Camel APIs then you can create the `PollingConsumer` instance to be used.

=== Using Polling Consumer from Java

You can programmatically create an instance of `PollingConsumer` from any endpoint as shown below:

[source,java]
----
Endpoint endpoint = context.getEndpoint("activemq:my.queue");
PollingConsumer consumer = endpoint.createPollingConsumer();
Exchange exchange = consumer.receive();
----

=== PollingConsumer API

There are three main polling methods on
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer]:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Method name |Description
|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receive()]
|Waits until a message is available and then returns it; potentially blocking forever

|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receive(long)]
|Attempts to receive a message exchange, waiting up to the given timeout and returning null if no message exchange could be received within the time available

|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receiveNoWait()]
|Attempts to receive a message exchange immediately without waiting and returning null if a message exchange is not available yet
|=======================================================================

=== Two kinds of Polling Consumer implementations

In Camel there are two kinds of `PollingConsumer` implementations:

- _Custom_ - Some components have their own custom implementation of `PollingConsumer` which is optimized for the given component.
- _Default_ - `EventDrivePollingConsumer` is the default implementation otherwise.


The `EventDrivePollingConsumer` supports the following options:

[width="100%",cols="34%,33%,33%",options="header",]
|=======================================================================
|Option |Default |Description
|`pollingConsumerQueueSize` |`1000` | The queue size for the internal hand-off queue between the polling consumer,
and producers sending data into the queue.

|`pollingConsumerBlockWhenFull` |`true` | Whether to block any producer if the internal queue is full.

|`pollingConsumerBlockTimeout` |0 | To use a timeout (in milliseconds) when the producer is blocked
if the internal queue is full. If the value is `0` or negative then no timeout is in use. If a
timeout is triggered then a `ExchangeTimedOutException` is thrown.
|=======================================================================

You can configure these options in endpoints xref:latest@manual:ROOT:uris.adoc[URIs], such
as shown below:

[source,java]
----<commit_msg>[CAMEL-17076] Fix typo in polling consumer docs (#6269)<commit_after>= Polling Consumer

Camel supports implementing the
http://www.enterpriseintegrationpatterns.com/PollingConsumer.html[Polling
Consumer] from the xref:enterprise-integration-patterns.adoc[EIP
patterns].

An application needs to consume Messages, but it wants to control when it consumes each message.

How can an application consume a message when the application is ready?

image::eip/PollingConsumerSolution.gif[image]

The application should use a Polling Consumer, one that explicitly makes a call when it wants to receive a message.

In Camel the `PollingConsumer` is represented by the
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer]
interface.

You can get hold of a `PollingConsumer` in several ways in Camel:

- Use xref:pollEnrich-eip.adoc[Poll Enrich] EIP

- Create a `PollingConsumer` instance via the
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/Endpoint.java[Endpoint.createPollingConsumer()]
method.

- Use the xref:latest@manual:ROOT:consumertemplate.adoc[ConsumerTemplate] to poll on demand.

== Using Polling Consumer

If you need to use Polling Consumer from within a route, then the xref:pollEnrich-eip.adoc[Poll Enrich] EIP can be used.

On the other hand if you need to use Polling Consumer programmatically,
then using xref:latest@manual:ROOT:consumertemplate.adoc[ConsumerTemplate] is a good choice.

And if you want to use the lower level Camel APIs then you can create the `PollingConsumer` instance to be used.

=== Using Polling Consumer from Java

You can programmatically create an instance of `PollingConsumer` from any endpoint as shown below:

[source,java]
----
Endpoint endpoint = context.getEndpoint("activemq:my.queue");
PollingConsumer consumer = endpoint.createPollingConsumer();
Exchange exchange = consumer.receive();
----

=== PollingConsumer API

There are three main polling methods on
https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer]:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Method name |Description
|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receive()]
|Waits until a message is available and then returns it; potentially blocking forever

|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receive(long)]
|Attempts to receive a message exchange, waiting up to the given timeout and returning null if no message exchange could be received within the time available

|https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java[PollingConsumer.receiveNoWait()]
|Attempts to receive a message exchange immediately without waiting and returning null if a message exchange is not available yet
|=======================================================================

=== Two kinds of Polling Consumer implementations

In Camel there are two kinds of `PollingConsumer` implementations:

- _Custom_ - Some components have their own custom implementation of `PollingConsumer` which is optimized for the given component.
- _Default_ - `EventDrivenPollingConsumer` is the default implementation otherwise.


The `EventDrivenPollingConsumer` supports the following options:

[width="100%",cols="34%,33%,33%",options="header",]
|=======================================================================
|Option |Default |Description
|`pollingConsumerQueueSize` |`1000` | The queue size for the internal hand-off queue between the polling consumer,
and producers sending data into the queue.

|`pollingConsumerBlockWhenFull` |`true` | Whether to block any producer if the internal queue is full.

|`pollingConsumerBlockTimeout` |0 | To use a timeout (in milliseconds) when the producer is blocked
if the internal queue is full. If the value is `0` or negative then no timeout is in use. If a
timeout is triggered then a `ExchangeTimedOutException` is thrown.
|=======================================================================

You can configure these options in endpoints xref:latest@manual:ROOT:uris.adoc[URIs], such
as shown below:

[source,java]
----
{'fraction_non_alphanumeric': 0.1500225937641211, 'fraction_numerical': 0.005987347492092183, 'mean_word_length': 5.943529411764706, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6274968', 'n_tokens_mistral': 2527, 'n_tokens_neox': 2343, 'n_words': 823}