CAMEL-13841: Allow manual Pulsar message acknowledgments

[masahoriyama-toast]

Addresses CAMEL-13841

Motivation

Pulsar messages are currently acknowledged immediately upon consumption. This could lead to lost messages if the application crashes or does not finish its unit of work. In such situations, it may be desirable to leave these messages unacknowledged so that they can be redelivered to another consumer. [Correction March 3, 2020 -- This is not correct. Pulsar messages are acknowledged after successful processing of the route, not immediately after consumption from the topic. Exceptions or errors on the route will correctly cause the message to remain unacknowledged.]

Allow manual control of Pulsar message acknowledgement related routines. The end user can decide when to acknowledge, or negative acknowledge a Pulsar message within the route. This will become a necessity when support for asynchronous processing of Pulsar messages is added.

Modifications

Changed the PulsarMessageListener's received method to not acknowledge the message if allowManualAcknowledgement is true. Instead, we add an instance of PulsarMessageReceipt as a header on the Exchange so that the user can manually acknowledge the message at the appropriate time.

Added allowManualAcknowledgement, ackTimeoutMillis, and ackGroupTimeMillis as URI parameters. The latter two are Pulsar consumer configurations to allow for finer control over acknowledgements.

Added allowManualAcknowledgement also as a component option so that it can default to true if absent in the Pulsar endpoint URI.
Added the pulsarMessageReceiptFactory component option for providing an alternate implementation of MessageReceipt.

Followed the same approach as camel-kafka:
CAMEL-11933

Verifying this change

Added the following test classes:

PulsarConsumerAcknowledgementTest
PulsarConsumerNoAcknowledgementTest
PulsarCustomMessageReceiptTest
PulsarNegativeAcknowledgementTest

And added to:
PulsarComponentTest

Documentation

Added to pulsar-component.adoc

[davsclaus]

Can you add javadoc to this interface and its methods

[masahoriyama-toast]

I have added Javadocs to PulsarMessageReceipt and PulsarMessageReceiptFactory. Please let me know what you think. Thank-you.

[davsclaus]

Looks really good just would be nice with javadoc on that interface that some end users may implement for custom behaviour