Spring Cloud GCP provides an abstraction layer to publish to and subscribe from Google Cloud Pub/Sub topics and to create, list or delete Google Cloud Pub/Sub topics and subscriptions.
A Spring Boot starter is provided to auto-configure the various required Pub/Sub components.
Maven coordinates, using Spring Cloud GCP BOM:
<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-gcp-starter-pubsub</artifactId> </dependency>
Gradle coordinates:
dependencies { compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-starter-pubsub' }
PubSubOperations
is an abstraction that allows Spring users to use Google Cloud Pub/Sub without
depending on any Google Cloud Pub/Sub API semantics.
It provides the common set of operations needed to interact with Google Cloud Pub/Sub.
PubSubTemplate
is the default implementation of PubSubOperations
and it uses the
Google Cloud Java Client for Pub/Sub
to interact with Google Cloud Pub/Sub.
PubSubTemplate
depends on a PublisherFactory
, which is a functional interface to provide a
Google Cloud Java Client for Pub/Sub Publisher
.
The Spring Boot starter for GCP Pub/Sub auto-configures a PublisherFactory
with default settings
and uses the GcpProjectIdProvider
and CredentialsProvider
auto-configured by the Spring Boot GCP
starter.
The PublisherFactory
implementation provided by Spring Cloud GCP Pub/Sub,
DefaultPublisherFactory
, caches Publisher
instances by topic name, in order to optimize resource
utilization.
PubSubTemplate
provides asynchronous methods to publish messages to a Google Cloud Pub/Sub topic.
It supports different types of payloads, including Strings
with different encodings, byte[]
,
ByteString
and PubsubMessage
.
public ListenableFuture<String> publish(String topic, String payload, Map<String, String> headers) public ListenableFuture<String> publish(String topic, String payload, Map<String, String> headers, Charset charset) public ListenableFuture<String> publish(String topic, byte[] payload, Map<String, String> headers) public ListenableFuture<String> publish(String topic, ByteString payload, Map<String, String> headers) public ListenableFuture<String> publish(String topic, PubsubMessage pubsubMessage)
Here is an example of how to publish a message to a Google Cloud Pub/Sub topic:
public void publishMessage() { this.pubSubTemplate.publish("topic", "your message payload", ImmutableMap.of("key1", "val1")); }
Google Cloud Pub/Sub allows many subscriptions to be associated to the same topic.
PubSubTemplate
allows you to subscribe to subscriptions via the subscribe()
method.
It relies on a SubscriberFactory
object, whose only task is to generate Google Cloud Pub/Sub
Subscriber
objects.
When subscribing to a subscription, messages will be pulled from Google Cloud Pub/Sub
asynchronously, on a certain interval.
The Spring Boot starter for Google Cloud Pub/Sub auto-configures a SubscriberFactory
.
Google Cloud Pub/Sub supports the synchronous pulling of messages from a subscription. This is different from subscribing to a subscription, in the sense that subscribing is an asynchronous task which polls the subscription on a set interval.
The pullNext()
method allows for a single message to be pulled from a subscription.
The pull()
method pulls a number of messages from a subscription, allowing for the retry settings
to be configured.
PubSubTemplate
uses a special subscriber generated by its SubscriberFactory
to pull messages.
PubSubAdmin
is the abstraction provided by Spring Cloud GCP to manage Google Cloud Pub/Sub
resources.
It allows for the creation, deletion and listing of topics and subscriptions.
PubSubAdmin
depends on GcpProjectIdProvider
and either a CredentialsProvider
or a
TopicAdminClient
and a SubscriptionAdminClient
.
If given a CredentialsProvider
, it creates a TopicAdminClient
and a SubscriptionAdminClient
with the Google Cloud Java Library for Pub/Sub default settings.
The Spring Boot starter for GCP Pub/Sub auto-configures a PubSubAdmin
object using the
GcpProjectIdProvider
and the CredentialsProvider
auto-configured by the Spring Boot GCP Core
starter.
PubSubAdmin
implements a method to create topics:
public Topic createTopic(String topicName)
Here is an example of how to create a Google Cloud Pub/Sub topic:
public void newTopic() { pubSubAdmin.createTopic("topicName"); }
PubSubAdmin
implements a method to delete topics:
public void deleteTopic(String topicName)
Here is an example of how to delete a Google Cloud Pub/Sub topic:
public void deleteTopic() { pubSubAdmin.deleteTopic("topicName"); }
PubSubAdmin
implements a method to list topics:
public List<Topic> listTopics
Here is an example of how to list every Google Cloud Pub/Sub topic name in a project:
public List<String> listTopics() { return pubSubAdmin .listTopics() .stream() .map(Topic::getNameAsTopicName) .map(TopicName::getTopic) .collect(Collectors.toList()); }
PubSubAdmin
implements a method to create subscriptions to existing topics:
public Subscription createSubscription(String subscriptionName, String topicName, Integer ackDeadline, String pushEndpoint)
Here is an example of how to create a Google Cloud Pub/Sub subscription:
public void newSubscription() { pubSubAdmin.createSubscription("subscriptionName", "topicName", 10, “http://my.endpoint/push”); }
Alternative methods with default settings are provided for ease of use.
The default value for ackDeadline
is 10 seconds.
If pushEndpoint
isn’t specified, the subscription uses message pulling, instead.
public Subscription createSubscription(String subscriptionName, String topicName)
public Subscription createSubscription(String subscriptionName, String topicName, Integer ackDeadline)
public Subscription createSubscription(String subscriptionName, String topicName, String pushEndpoint)
PubSubAdmin
implements a method to delete subscriptions:
public void deleteSubscription(String subscriptionName)
Here is an example of how to delete a Google Cloud Pub/Sub subscription:
public void deleteSubscription() { pubSubAdmin.deleteSubscription("subscriptionName"); }
PubSubAdmin
implements a method to list subscriptions:
public List<Subscription> listSubscriptions()
Here is an example of how to list every subscription name in a project:
public List<String> listSubscriptions() { return pubSubAdmin .listSubscriptions() .stream() .map(Subscription::getNameAsSubscriptionName) .map(SubscriptionName::getSubscription) .collect(Collectors.toList()); }
The Spring Boot starter for Google Cloud Pub/Sub provides the following configuration options:
Name | Description | Optional | Default value |
| Enables or disables Pub/Sub auto-configuration | Yes |
|
| Number of threads used by | Yes | 4 |
| Number of threads used by | Yes | 4 |
| GCP project ID where the Google Cloud Pub/Sub API is hosted, if different from the one in the Spring Cloud GCP Core Module | Yes | |
| OAuth2 credentials for authenticating with the Google Cloud Pub/Sub API, if different from the ones in the Spring Cloud GCP Core Module | Yes | |
| OAuth2 scope for Spring Cloud GCP Pub/Sub credentials | Yes |