docs/components/modules/ROOT/pages/google-pubsub-component.adoc

[[google-pubsub-component]]
= Google Pubsub Component
//THIS FILE IS COPIED: EDIT THE SOURCE FILE:
:page-source: components/camel-google-pubsub/src/main/docs/google-pubsub-component.adoc
:docTitle: Google Pubsub
:artifactId: camel-google-pubsub
:description: Send and receive messages to/from Google Cloud Platform PubSub Service.
:since: 2.19
:supportLevel: Stable
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:group: Google

*Since Camel {since}*

*{component-header}*

The Google Pubsub component provides access
to https://cloud.google.com/pubsub/[Cloud Pub/Sub Infrastructure] via
the https://github.com/googleapis/java-pubsub[Google Cloud Java Client for Google Cloud Pub/Sub].

Maven users will need to add the following dependency to their pom.xml
for this component:

------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-google-pubsub</artifactId>
    <!-- use the same version as your Camel core version -->
    <version>x.x.x</version>
</dependency>

------------------------------------------------------

== URI Format

The Google Pubsub Component uses the following URI format:

----
google-pubsub://project-id:destinationName?[options]
----

Destination Name can be either a topic or a subscription name.

== Options

// component options: START
The Google Pubsub component supports 7 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *endpoint* (common) | Endpoint to use with local Pub/Sub emulator. |  | String
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *publisherCacheSize* (producer) | Maximum number of producers to cache. This could be increased if you have producers for lots of different topics. |  | int
| *publisherCacheTimeout* (producer) | How many milliseconds should each producer stay alive in the cache. |  | int
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *publisherTerminationTimeout* (advanced) | How many milliseconds should a producer be allowed to terminate. |  | int
|===
// component options: END

// endpoint options: START
The Google Pubsub endpoint is configured using URI syntax:

----
google-pubsub:projectId:destinationName
----

with the following path and query parameters:

=== Path Parameters (2 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *projectId* | *Required* Project Id |  | String
| *destinationName* | *Required* Destination Name |  | String
|===


=== Query Parameters (11 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *ackMode* (common) | AUTO = exchange gets ack'ed/nack'ed on completion. NONE = downstream process has to ack/nack explicitly. The value can be one of: AUTO, NONE | AUTO | AckMode
| *concurrentConsumers* (common) | The number of parallel streams consuming from the subscription | 1 | Integer
| *loggerId* (common) | Logger ID to use when a match to the parent route required |  | String
| *maxMessagesPerPoll* (common) | The max number of messages to receive from the server in a single API call | 1 | Integer
| *synchronousPull* (common) | Synchronously pull batches of messages | false | boolean
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. The value can be one of: InOnly, InOut, InOptionalOut |  | ExchangePattern
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
|===
// endpoint options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-google-pubsub-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 8 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.google-pubsub.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean
| *camel.component.google-pubsub.bridge-error-handler* | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | Boolean
| *camel.component.google-pubsub.enabled* | Whether to enable auto configuration of the google-pubsub component. This is enabled by default. |  | Boolean
|===
// spring-boot-auto-configure options: END


== Producer Endpoints

Producer endpoints can accept and deliver to PubSub individual and grouped
exchanges alike. Grouped exchanges have `Exchange.GROUPED_EXCHANGE` property set.

Google PubSub expects the payload to be byte[] array, Producer endpoints will send:

* String body as byte[] encoded as UTF-8
* byte[] body as is
* Everything else will be serialised into byte[] array

A Map set as message header `GooglePubsubConstants.ATTRIBUTES` will be sent as PubSub attributes.
Once exchange has been delivered to PubSub the PubSub Message ID will be assigned to
the header `GooglePubsubConstants.MESSAGE_ID`.

== Consumer Endpoints
Google PubSub will redeliver the message if it has not been acknowledged within the time period set
as a configuration option on the subscription.

The component will acknowledge the message once exchange processing has been completed.

If the route throws an exception, the exchange is marked as failed and the component will NACK the message -
it will be redelivered immediately.

To ack/nack the message the component uses Acknowledgement ID stored as header `GooglePubsubConstants.ACK_ID`.
If the header is removed or tampered with, the ack will fail and the message will be redelivered
again after the ack deadline.

== Message Headers
Headers set by the consumer endpoints:

* GooglePubsubConstants.MESSAGE_ID
* GooglePubsubConstants.ATTRIBUTES
* GooglePubsubConstants.PUBLISH_TIME

== Message Body

The consumer endpoint returns the content of the message as byte[] - exactly as the underlying system sends it.
It is up for the route to convert/unmarshall the contents.

== Authentication Configuration

The location of the default credentials file is configurable - via GOOGLE_APPLICATION_CREDENTIALS environment variable.

== Rollback and Redelivery

The rollback for Google PubSub relies on the idea of the Acknowledgement Deadline - the time period where Google PubSub expects to receive the acknowledgement.
If the acknowledgement has not been received, the message is redelivered.

Google provides an API to extend the deadline for a message.

More information in https://cloud.google.com/pubsub/docs/subscriber#ack_deadline[Google PubSub Documentation]

So, rollback is effectively a deadline extension API call with zero value - i.e. deadline is reached now and message can
be redelivered to the next consumer.

It is possible to delay the message redelivery by setting the acknowledgement deadline explicitly for the rollback by
setting the message header `GooglePubsubConstants.ACK_DEADLINE` to the value in seconds.

include::camel-spring-boot::page$google-pubsub-starter.adoc[]