com.google.cloud.pubsub

Class Subscription

java.lang.Object

com.google.cloud.pubsub.SubscriptionInfo

com.google.cloud.pubsub.Subscription

All Implemented Interfaces:

Serializable

public class Subscription
extends SubscriptionInfo

A Google Cloud Pub/Sub subscription. A subscription represents the stream of messages from a single, specific topic, to be delivered to the subscribing application. Pub/Sub subscriptions support both push and pull message delivery.

In a push subscription, the Pub/Sub server sends a request to the subscriber application, at a preconfigured endpoint (see PushConfig). The subscriber's HTTP response serves as an implicit acknowledgement: a success response indicates that the message has been succesfully processed and the Pub/Sub system can delete it from the subscription; a non-success response indicates that the Pub/Sub server should resend it (implicit "nack").

In a pull subscription, the subscribing application must explicitly pull messages using one of PubSub.pull(String, int), PubSub.pullAsync(String, int) or PubSub.pullAsync(String, PubSub.MessageProcessor callback, PubSub.PullOption...). When messages are pulled with PubSub.pull(String, int) or PubSub.pullAsync(String, int) the subscribing application must also explicitly acknowledge them using one of PubSub.ack(String, Iterable), PubSub.ack(String, String, String...), PubSub.ackAsync(String, Iterable) or PubSub.ackAsync(String, String, String...).

Subscription adds a layer of service-related functionality over SubscriptionInfo. Objects of this class are immutable. To get a Subscription object with the most recent information use reload() or reloadAsync().

See Also:

Pub/Sub Data Model, Subscriber Guide, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Subscription.Builder A builder for Subscription objects.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	delete() Deletes this subscription.
Future<Boolean>	deleteAsync() Sends a request for deleting this subscription.
boolean	equals(Object obj)
int	hashCode()
PubSub	pubSub() Returns the subscription's PubSub object used to issue requests.
Iterator<ReceivedMessage>	pull(int maxMessages) Pulls messages from this subscription.
Future<Iterator<ReceivedMessage>>	pullAsync(int maxMessages) Sends a request for pulling messages from this subscription.
PubSub.MessageConsumer	pullAsync(PubSub.MessageProcessor callback, PubSub.PullOption... options) Creates a message consumer that pulls messages from this subscription.
Subscription	reload() Fetches current subscription's latest information.
Future<Subscription>	reloadAsync() Sends a request for fetching current subscription's latest information.
void	replacePushConfig(PushConfig pushConfig) Sets the push configuration for this subscription.
Future<Void>	replacePushConfigAsync(PushConfig pushConfig) Sends a request for updating the push configuration for a specified subscription.
Subscription.Builder	toBuilder() Returns a builder for the subscription object.

Methods inherited from class com.google.cloud.pubsub.SubscriptionInfo

ackDeadlineSeconds, builder, builder, name, of, of, of, of, pushConfig, topic, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

toBuilder

public Subscription.Builder toBuilder()

Description copied from class: SubscriptionInfo

Returns a builder for the subscription object.

Overrides:

toBuilder in class SubscriptionInfo

hashCode

public final int hashCode()

Overrides:

hashCode in class SubscriptionInfo

equals

public final boolean equals(Object obj)

Overrides:

equals in class SubscriptionInfo

pubSub

public PubSub pubSub()

Returns the subscription's PubSub object used to issue requests.

delete

public boolean delete()

Deletes this subscription.

Returns:

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

Throws:

PubSubException - upon failure

deleteAsync

public Future<Boolean> deleteAsync()

Sends a request for deleting this 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.

reload

public Subscription reload()

Fetches current subscription's latest information. Returns null if the subscription does not exist.

Returns:

a Subscription object with latest information or null if not found

Throws:

PubSubException - upon failure

reloadAsync

public Future<Subscription> reloadAsync()

Sends a request for fetching current subscription's latest information. This method returns a Future object to consume the result. Future.get() returns the requested subscription or null if not found.

Returns:

a Subscription object with latest information or null if not found

Throws:

PubSubException - upon failure

replacePushConfig

public void replacePushConfig(PushConfig pushConfig)

Sets the push configuration for this 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:

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

Throws:

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

replacePushConfigAsync

public Future<Void> replacePushConfigAsync(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:

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

Returns:

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

pull

public Iterator<ReceivedMessage> pull(int maxMessages)

Pulls messages from this 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:

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

Throws:

PubSubException - upon failure

pullAsync

public Future<Iterator<ReceivedMessage>> pullAsync(int maxMessages)

Sends a request for pulling messages from this 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:

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

Throws:

PubSubException - upon failure

pullAsync

public PubSub.MessageConsumer pullAsync(PubSub.MessageProcessor callback,
                               PubSub.PullOption... options)

Creates a message consumer that pulls messages from this 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 PubSub.PullOption.executorFactory(GrpcServiceOptions.ExecutorFactory) can be used to provide an executor to run message processor callbacks.

Parameters:

callback - the callback to be executed on each message

options - pulling options

Returns:

a message consumer for the provided subscription and options