com.google.cloud.pubsub

Interface PubSub

All Superinterfaces:

AutoCloseable, Service<PubSubOptions>

public interface PubSub
extends AutoCloseable, Service<PubSubOptions>

An interface for Google Cloud Pub/Sub.

See Also:

Google Cloud Pub/Sub

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	PubSub.ListOption Class for specifying options for listing topics and subscriptions.
static interface	PubSub.MessageConsumer An interface to control a message consumer.
static interface	PubSub.MessageProcessor A callback to process pulled messages.
static class	PubSub.PullOption Class for specifying options for pulling messages.

Method Summary

Methods

Modifier and Type	Method and Description
void	ack(String subscription, Iterable<String> ackIds) Acknowledges the given messages for the provided subscription.
void	ack(String subscription, String ackId, String... ackIds) Acknowledges the given messages for the provided subscription.
Future<Void>	ackAsync(String subscription, Iterable<String> ackIds) Sends a request to acknowledge the given messages for the provided subscription.
Future<Void>	ackAsync(String subscription, String ackId, String... ackIds) Sends a request to acknowledge the given messages for the provided subscription.
Subscription	create(SubscriptionInfo subscription) Creates a new subscription.
Topic	create(TopicInfo topic) Creates a new topic.
Future<Subscription>	createAsync(SubscriptionInfo subscription) Sends a request for creating a subscription.
Future<Topic>	createAsync(TopicInfo topic) Sends a request for creating a topic.
boolean	deleteSubscription(String subscription) Deletes the requested subscription.
Future<Boolean>	deleteSubscriptionAsync(String subscription) Sends a request for deleting a subscription.
boolean	deleteTopic(String topic) Deletes the requested topic.
Future<Boolean>	deleteTopicAsync(String topic) Sends a request for deleting a topic.
Subscription	getSubscription(String subscription) Returns the requested subscription or null if not found.
Future<Subscription>	getSubscriptionAsync(String subscription) Sends a request for getting a subscription.
Topic	getTopic(String topic) Returns the requested topic or null if not found.
Future<Topic>	getTopicAsync(String topic) Sends a request for getting a topic.
Page<Subscription>	listSubscriptions(PubSub.ListOption... options) Lists the subscriptions.
Page<SubscriptionId>	listSubscriptions(String topic, PubSub.ListOption... options) Lists the identities of the subscriptions for the provided topic.
Future<AsyncPage<Subscription>>	listSubscriptionsAsync(PubSub.ListOption... options) Sends a request for listing subscriptions.
Future<AsyncPage<SubscriptionId>>	listSubscriptionsAsync(String topic, PubSub.ListOption... options) Sends a request for listing the identities of subscriptions for the provided topic.
Page<Topic>	listTopics(PubSub.ListOption... options) Lists the topics.
Future<AsyncPage<Topic>>	listTopicsAsync(PubSub.ListOption... options) Sends a request for listing topics.
void	modifyAckDeadline(String subscription, int deadline, TimeUnit unit, Iterable<String> ackIds) Modifies the acknowledge deadline of the given messages.
void	modifyAckDeadline(String subscription, int deadline, TimeUnit unit, String ackId, String... ackIds) Modifies the acknowledge deadline of the given messages.
Future<Void>	modifyAckDeadlineAsync(String subscription, int deadline, TimeUnit unit, Iterable<String> ackIds) Sends a request to modify the acknowledge deadline of the given messages.
Future<Void>	modifyAckDeadlineAsync(String subscription, int deadline, TimeUnit unit, String ackId, String... ackIds) Sends a request to modify the acknowledge deadline of the given messages.
void	nack(String subscription, Iterable<String> ackIds) "Nacks" the given messages for the provided subscription.
void	nack(String subscription, String ackId, String... ackIds) "Nacks" the given messages for the provided subscription.
Future<Void>	nackAsync(String subscription, Iterable<String> ackIds) Sends a request to "nack" the given messages for the provided subscription.
Future<Void>	nackAsync(String subscription, String ackId, String... ackIds) Sends a request to "nack" the given messages for the provided subscription.
List<String>	publish(String topic, Iterable<Message> messages) Publishes a number of messages to the provided topic.
String	publish(String topic, Message message) Publishes a message to the provided topic.
List<String>	publish(String topic, Message message, Message... messages) Publishes a number of messages to the provided topic.
Future<List<String>>	publishAsync(String topic, Iterable<Message> messages) Sends a request to publish a number of messages to the provided topic.
Future<String>	publishAsync(String topic, Message message) Sends a request for publishing a message to the provided topic.
Future<List<String>>	publishAsync(String topic, Message message, Message... messages) Sends a request to publish a number of messages to the provided topic.
Iterator<ReceivedMessage>	pull(String subscription, int maxMessages) Pulls messages from the provided subscription.
Future<Iterator<ReceivedMessage>>	pullAsync(String subscription, int maxMessages) Sends a request for pulling messages from the provided subscription.
PubSub.MessageConsumer	pullAsync(String subscription, PubSub.MessageProcessor callback, PubSub.PullOption... options) Creates a message consumer that pulls messages from the provided subscription.
void	replacePushConfig(String subscription, PushConfig pushConfig) Sets the push configuration for a specified subscription.
Future<Void>	replacePushConfigAsync(String subscription, PushConfig pushConfig) Sends a request for updating the push configuration for a specified subscription.

Methods inherited from interface java.lang.AutoCloseable

close

Methods inherited from interface com.google.cloud.Service

options

Method Detail

create

Topic create(TopicInfo topic)

Creates a new topic.

Returns:

the created topic

Throws:

PubSubException - upon failure

createAsync

Future<Topic> createAsync(TopicInfo topic)

Sends a request for creating a topic. This method returns a Future object to consume the result. Future.get() returns the created topic.

getTopic

Topic getTopic(String topic)

Returns the requested topic or null if not found.

Throws:

PubSubException - upon failure

getTopicAsync

Future<Topic> getTopicAsync(String topic)

Sends a request for getting a topic. This method returns a Future object to consume the result. Future.get() returns the requested topic or null if not found.

Throws:

PubSubException - upon failure

deleteTopic

boolean deleteTopic(String topic)

Deletes the requested topic.

Returns:

true if the topic was deleted, false if it was not found

deleteTopicAsync

Future<Boolean> deleteTopicAsync(String topic)

Sends a request for deleting a topic. This method returns a Future object to consume the result. Future.get() returns true if the topic was deleted, false if it was not found.

listTopics

Page<Topic> listTopics(PubSub.ListOption... options)

Lists the topics. This method returns a Page object that can be used to consume paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing topics.

Throws:

PubSubException - upon failure

listTopicsAsync

Future<AsyncPage<Topic>> listTopicsAsync(PubSub.ListOption... options)

Sends a request for listing topics. This method returns a Future object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing topics.

publish

String publish(String topic,
             Message message)

Publishes a message to the provided topic. This method returns a service-generated id for the published message. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

message - the message to publish

Returns:

a unique service-generated id for the message

Throws:

PubSubException - upon failure, if the topic does not exist or if the message has empty payload and no attributes

publishAsync

Future<String> publishAsync(String topic,
                          Message message)

Sends a request for publishing a message to the provided topic. This method returns a Future object to consume the result. Future.get() returns a service-generated id for the published message. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

message - the message to publish

Returns:

a Future for the unique service-generated id for the message

publish

List<String> publish(String topic,
                   Message message,
                   Message... messages)

Publishes a number of messages to the provided topic. This method returns a list of service-generated ids for the published messages. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

message - the first message to publish

messages - other messages to publish

Returns:

a list of unique, service-generated, ids. Ids are in the same order as the messages.

Throws:

PubSubException - upon failure, if the topic does not exist or if one of the messages has empty payload and no attributes

publishAsync

Future<List<String>> publishAsync(String topic,
                                Message message,
                                Message... messages)

Sends a request to publish a number of messages to the provided topic. This method returns a Future object to consume the result. Future.get() returns a list of service-generated ids for the published messages. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

message - the first message to publish

messages - other messages to publish

Returns:

a Future for the unique, service-generated ids. Ids are in the same order as the messages.

publish

List<String> publish(String topic,
                   Iterable<Message> messages)

Publishes a number of messages to the provided topic. This method returns a list of service-generated ids for the published messages. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

messages - the messages to publish

Returns:

a list of unique, service-generated, ids. Ids are in the same order as the messages.

Throws:

PubSubException - upon failure, if the topic does not exist or if one of the messages has empty payload and no attributes

publishAsync

Future<List<String>> publishAsync(String topic,
                                Iterable<Message> messages)

Sends a request to publish a number of messages to the provided topic. This method returns a Future object to consume the result. Future.get() returns a list of service-generated ids for the published messages. Service-generated ids are guaranteed to be unique within the topic.

Parameters:

topic - the topic where the message is published

messages - the messages to publish

Returns:

a Future for the unique, service-generated ids. Ids are in the same order as the messages

create

Subscription create(SubscriptionInfo subscription)

Creates a new subscription.

Returns:

the created subscription

Throws:

PubSubException - upon failure

createAsync

Future<Subscription> createAsync(SubscriptionInfo subscription)

Sends a request for creating a subscription. This method returns a Future object to consume the result. Future.get() returns the created subscription.

getSubscription

Subscription getSubscription(String subscription)

Returns the requested subscription or null if not found.

getSubscriptionAsync

Future<Subscription> getSubscriptionAsync(String subscription)

Sends a request for getting a subscription. This method returns a Future object to consume the result. Future.get() returns the requested subscription or null if not found.

replacePushConfig

void replacePushConfig(String subscription,
                     PushConfig pushConfig)

Sets the push configuration for a specified subscription. This may be used to change a push subscription to a pull one (passing a null pushConfig parameter) or vice versa. This methods can also be used to change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery regardless of changes to the push configuration.

Parameters:

subscription - the subscription for which to replace push configuration

pushConfig - the new push configuration. Use null to unset it

Throws:

PubSubException - upon failure, or if the subscription does not exist

replacePushConfigAsync

Future<Void> replacePushConfigAsync(String subscription,
                                  PushConfig pushConfig)

Sends a request for updating the push configuration for a specified subscription. This may be used to change a push subscription to a pull one (passing a null pushConfig parameter) or vice versa. This methods can also be used to change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery regardless of changes to the push configuration. The method returns a Future object that can be used to wait for the replace operation to be completed.

Parameters:

subscription - the subscription for which to replace push configuration

pushConfig - the new push configuration. Use null to unset it

Returns:

a Future to wait for the replace operation to be completed.

deleteSubscription

boolean deleteSubscription(String subscription)

Deletes the requested subscription.

Returns:

true if the subscription was deleted, false if it was not found

Throws:

PubSubException - upon failure

deleteSubscriptionAsync

Future<Boolean> deleteSubscriptionAsync(String subscription)

Sends a request for deleting a subscription. This method returns a Future object to consume the result. Future.get() returns true if the subscription was deleted, false if it was not found.

listSubscriptions

Page<Subscription> listSubscriptions(PubSub.ListOption... options)

Lists the subscriptions. This method returns a Page object that can be used to consume paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing subscriptions.

Throws:

PubSubException - upon failure

listSubscriptionsAsync

Future<AsyncPage<Subscription>> listSubscriptionsAsync(PubSub.ListOption... options)

Sends a request for listing subscriptions. This method returns a Future object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing subscriptions.

Throws:

PubSubException - upon failure

listSubscriptions

Page<SubscriptionId> listSubscriptions(String topic,
                                     PubSub.ListOption... options)

Lists the identities of the subscriptions for the provided topic. This method returns a Page object that can be used to consume paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing subscriptions.

Parameters:

topic - the topic for which to list subscriptions

Throws:

PubSubException - upon failure

listSubscriptionsAsync

Future<AsyncPage<SubscriptionId>> listSubscriptionsAsync(String topic,
                                                       PubSub.ListOption... options)

Sends a request for listing the identities of subscriptions for the provided topic. This method returns a Future object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use PubSub.ListOption to specify the page size or the page token from which to start listing subscriptions.

Parameters:

topic - the topic for which to list subscriptions

pull

Iterator<ReceivedMessage> pull(String subscription,
                             int maxMessages)

Pulls messages from the provided subscription. This method possibly returns no messages if no message was available at the time the request was processed by the Pub/Sub service (i.e. the system is not allowed to wait until at least one message is available). Pulled messages have their acknowledge deadline automatically renewed until they are explicitly consumed using Iterator.next().

Example usage of synchronous message pulling:

 Iterator<ReceivedMessage> messageIterator = pubsub.pull("subscription", 100);
 while (messageIterator.hasNext()) {
   ReceivedMessage message = messageIterator.next();
   // message's acknowledge deadline is no longer automatically renewed. If processing takes
   // long pubsub.modifyAckDeadline(String, String, long, TimeUnit) can be used to extend it.
   doSomething(message);
   message.ack(); // or message.nack()
 }

Parameters:

subscription - the subscription from which to pull messages

maxMessages - the maximum number of messages pulled by this method. This method can possibly return fewer messages.

Throws:

PubSubException - upon failure

pullAsync

Future<Iterator<ReceivedMessage>> pullAsync(String subscription,
                                          int maxMessages)

Sends a request for pulling messages from the provided subscription. This method returns a Future object to consume the result. Future.get() returns a message iterator. This method possibly returns no messages if no message was available at the time the request was processed by the Pub/Sub service (i.e. the system is not allowed to wait until at least one message is available).

Example usage of asynchronous message pulling:

 Future<Iterator<ReceivedMessage>> future = pubsub.pull("subscription", 100);
 // do something while the request gets processed
 Iterator<ReceivedMessage> messageIterator = future.get();
 while (messageIterator.hasNext()) {
   ReceivedMessage message = messageIterator.next();
   // message's acknowledge deadline is no longer automatically renewed. If processing takes
   // long pubsub.modifyAckDeadline(String, String, long, TimeUnit) can be used to extend it.
   doSomething(message);
   message.ack(); // or message.nack()
 }

Parameters:

subscription - the subscription from which to pull messages

maxMessages - the maximum number of messages pulled by this method. This method can possibly return fewer messages.

Throws:

PubSubException - upon failure

pullAsync

PubSub.MessageConsumer pullAsync(String subscription,
                               PubSub.MessageProcessor callback,
                               PubSub.PullOption... options)

Creates a message consumer that pulls messages from the provided subscription. You can stop pulling messages by calling PubSub.MessageConsumer.close(). The returned message consumer executes PubSub.MessageProcessor.process(Message) on each pulled message. If PubSub.MessageProcessor.process(Message) executes correctly, the message is acknowledged. If PubSub.MessageProcessor.process(Message) throws an exception, the message is "nacked". For all pulled messages, the ack deadline is automatically renewed until the message is either acknowledged or "nacked".

The PubSub.PullOption.maxQueuedCallbacks(int) option can be used to control the maximum number of queued messages (messages either being processed or waiting to be processed). The PullOption#executorFactory(ExecutorFactory) can be used to provide an executor to run message processor callbacks.

Parameters:

subscription - the subscription from which to pull messages

callback - the callback to be executed on each message

options - pulling options

Returns:

a message consumer for the provided subscription and options

ack

void ack(String subscription,
       String ackId,
       String... ackIds)

Acknowledges the given messages for the provided subscription. Ack ids identify the messages to acknowledge, as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int).

Parameters:

subscription - the subscription whose messages must be acknowledged

ackId - the ack id of the first message to acknowledge

ackIds - other ack ids of messages to acknowledge

Throws:

PubSubException - upon failure, or if the subscription was not found

ackAsync

Future<Void> ackAsync(String subscription,
                    String ackId,
                    String... ackIds)

Sends a request to acknowledge the given messages for the provided subscription. Ack ids identify the messages to acknowledge, as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). The method returns a Future object that can be used to wait for the acknowledge operation to be completed.

Parameters:

subscription - the subscription whose messages must be acknowledged

ackId - the ack id of the first message to acknowledge

ackIds - other ack ids of messages to acknowledge

ack

void ack(String subscription,
       Iterable<String> ackIds)

Acknowledges the given messages for the provided subscription. Ack ids identify the messages to acknowledge, as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int).

Parameters:

subscription - the subscription whose messages must be acknowledged

ackIds - the ack ids of messages to acknowledge

Throws:

PubSubException - upon failure, or if the subscription was not found

ackAsync

Future<Void> ackAsync(String subscription,
                    Iterable<String> ackIds)

Sends a request to acknowledge the given messages for the provided subscription. Ack ids identify the messages to acknowledge, as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). The method returns a Future object that can be used to wait for the acknowledge operation to be completed.

Parameters:

subscription - the subscription whose messages must be acknowledged

ackIds - the ack ids of messages to acknowledge

nack

void nack(String subscription,
        String ackId,
        String... ackIds)

"Nacks" the given messages for the provided subscription. Ack ids identify the messages to "nack", as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). This method corresponds to calling modifyAckDeadline(String, int, TimeUnit, String, String...) with a deadline of 0.

Parameters:

subscription - the subscription whose messages must be "nacked"

ackId - the ack id of the first message to "nack"

ackIds - other ack ids of messages to "nack"

Throws:

PubSubException - upon failure, or if the subscription was not found

nackAsync

Future<Void> nackAsync(String subscription,
                     String ackId,
                     String... ackIds)

Sends a request to "nack" the given messages for the provided subscription. Ack ids identify the messages to "nack", as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). This method corresponds to calling modifyAckDeadlineAsync(String, int, TimeUnit, String, String...) with a deadline of 0. The method returns a Future object that can be used to wait for the "nack" operation to be completed.

Parameters:

subscription - the subscription whose messages must be "nacked"

ackId - the ack id of the first message to "nack"

ackIds - other ack ids of messages to "nack"

nack

void nack(String subscription,
        Iterable<String> ackIds)

"Nacks" the given messages for the provided subscription. Ack ids identify the messages to "nack", as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). This method corresponds to calling modifyAckDeadline(String, int, TimeUnit, Iterable) with a deadline of 0.

Parameters:

subscription - the subscription whose messages must be "nacked"

ackIds - the ack ids of messages to "nack"

Throws:

PubSubException - upon failure, or if the subscription was not found

nackAsync

Future<Void> nackAsync(String subscription,
                     Iterable<String> ackIds)

Sends a request to "nack" the given messages for the provided subscription. Ack ids identify the messages to "nack", as returned in ReceivedMessage.ackId() by pull(String, int) and pullAsync(String, int). This method corresponds to calling modifyAckDeadlineAsync(String, int, TimeUnit, Iterable) with a deadline of 0. The method returns a Future object that can be used to wait for the "nack" operation to be completed.

Parameters:

subscription - the subscription whose messages must be "nacked"

ackIds - the ack ids of messages to "nack"

modifyAckDeadline

void modifyAckDeadline(String subscription,
                     int deadline,
                     TimeUnit unit,
                     String ackId,
                     String... ackIds)

Modifies the acknowledge deadline of the given messages. deadline must be >= 0 and is the new deadline with respect to the time the modify request was received by the Pub/Sub service. For example, if deadline is 10 and unit is TimeUnit.SECONDS, the new ack deadline will expire 10 seconds after the modify request was received by the service. Specifying 0 may be used to make the message available for another pull request (corresponds to calling nack(String, String, String...)).

Parameters:

subscription - the subscription whose messages need to update their acknowledge deadline

deadline - the new deadline, relative to the time the modify request is received by the Pub/Sub service

unit - time unit for the deadline parameter

ackId - the ack id of the first message for which the acknowledge deadline must be modified

ackIds - other ack ids of messages for which the acknowledge deadline must be modified

Throws:

PubSubException - upon failure, or if the subscription was not found

modifyAckDeadlineAsync

Future<Void> modifyAckDeadlineAsync(String subscription,
                                  int deadline,
                                  TimeUnit unit,
                                  String ackId,
                                  String... ackIds)

Sends a request to modify the acknowledge deadline of the given messages. deadline must be >= 0 and is the new deadline with respect to the time the modify request was received by the Pub/Sub service. For example, if deadline is 10 and unit is TimeUnit.SECONDS, the new ack deadline will expire 10 seconds after the modify request was received by the service. Specifying 0 may be used to make the message available for another pull request (corresponds to calling nackAsync(String, Iterable)). The method returns a Future object that can be used to wait for the modify operation to be completed.

Parameters:

subscription - the subscription whose messages need to update their acknowledge deadline

deadline - the new deadline, relative to the time the modify request is received by the Pub/Sub service

unit - time unit for the deadline parameter

ackId - the ack id of the first message for which the acknowledge deadline must be modified

ackIds - other ack ids of messages for which the acknowledge deadline must be modified

modifyAckDeadline

void modifyAckDeadline(String subscription,
                     int deadline,
                     TimeUnit unit,
                     Iterable<String> ackIds)

Modifies the acknowledge deadline of the given messages. deadline must be >= 0 and is the new deadline with respect to the time the modify request was received by the Pub/Sub service. For example, if deadline is 10 and unit is TimeUnit.SECONDS, the new ack deadline will expire 10 seconds after the modify request was received by the service. Specifying 0 may be used to make the message available for another pull request (corresponds to calling nack(String, Iterable)).

Parameters:

subscription - the subscription whose messages need to update their acknowledge deadline

deadline - the new deadline, relative to the time the modify request is received by the Pub/Sub service

unit - time unit for the deadline parameter

ackIds - the ack ids of messages for which the acknowledge deadline must be modified

Throws:

PubSubException - upon failure, or if the subscription was not found

modifyAckDeadlineAsync

Future<Void> modifyAckDeadlineAsync(String subscription,
                                  int deadline,
                                  TimeUnit unit,
                                  Iterable<String> ackIds)

Sends a request to modify the acknowledge deadline of the given messages. deadline must be >= 0 and is the new deadline with respect to the time the modify request was received by the Pub/Sub service. For example, if deadline is 10 and unit is TimeUnit.SECONDS, the new ack deadline will expire 10 seconds after the modify request was received by the service. Specifying 0 may be used to make the message available for another pull request (corresponds to calling nackAsync(String, Iterable)). The method returns a Future object that can be used to wait for the modify operation to be completed.

Parameters:

subscription - the subscription whose messages need to update their acknowledge deadline

deadline - the new deadline, relative to the time the modify request is received by the Pub/Sub service

unit - time unit for the deadline parameter

ackIds - the ack ids of messages for which the acknowledge deadline must be modified