Class Publisher (1.123.0)

public class Publisher implements PublisherInterface

A Cloud Pub/Sub publisher, that is associated with a specific topic at creation.

A Publisher provides built-in capabilities to automatically handle batching of messages, controlling memory utilization, and retrying API calls on transient errors.

With customizable options that control:

  • Message batching: such as number of messages or max batch byte size.
  • Retries: such as the maximum duration of retries for a failing batch of messages.

Publisher will use the credentials set on the channel, which uses application default credentials through GoogleCredentials#getApplicationDefault by default.

Inheritance

java.lang.Object > Publisher

Implements

PublisherInterface

Static Methods

getApiMaxRequestBytes()

public static long getApiMaxRequestBytes()

The maximum size of one request. Defined by the API.

Returns
TypeDescription
long

getApiMaxRequestElementCount()

public static long getApiMaxRequestElementCount()

The maximum number of messages in one request. Defined by the API.

Returns
TypeDescription
long

newBuilder(TopicName topicName)

public static Publisher.Builder newBuilder(TopicName topicName)

Constructs a new Builder using the given topic.

Example of creating a Publisher.


 String projectName = "my_project";
 String topicName = "my_topic";
 ProjectTopicName topic = ProjectTopicName.create(projectName, topicName);
 Publisher publisher = Publisher.newBuilder(topic).build();
 try {
   // ...
 } finally {
   // When finished with the publisher, make sure to shutdown to free up resources.
   publisher.shutdown();
   publisher.awaitTermination(1, TimeUnit.MINUTES);
 }
 
Parameter
NameDescription
topicNameTopicName
Returns
TypeDescription
Publisher.Builder

newBuilder(String topicName)

public static Publisher.Builder newBuilder(String topicName)

Constructs a new Builder using the given topic.

Example of creating a Publisher.


 String topic = "projects/my_project/topics/my_topic";
 Publisher publisher = Publisher.newBuilder(topic).build();
 try {
   // ...
 } finally {
   // When finished with the publisher, make sure to shutdown to free up resources.
   publisher.shutdown();
   publisher.awaitTermination(1, TimeUnit.MINUTES);
 }
 
Parameter
NameDescription
topicNameString
Returns
TypeDescription
Publisher.Builder

Methods

awaitTermination(long duration, TimeUnit unit)

public boolean awaitTermination(long duration, TimeUnit unit)

Wait for all work has completed execution after a #shutdown() request, or the timeout occurs, or the current thread is interrupted.

Call this method to make sure all resources are freed properly.

Parameters
NameDescription
durationlong
unitTimeUnit
Returns
TypeDescription
boolean
Exceptions
TypeDescription
InterruptedException

getBatchingSettings()

public BatchingSettings getBatchingSettings()

The batching settings configured on this Publisher.

Returns
TypeDescription
BatchingSettings

getTopicName()

public TopicName getTopicName()

Topic which the publisher publishes to.

Returns
TypeDescription
TopicName

getTopicNameString()

public String getTopicNameString()

Topic which the publisher publishes to.

Returns
TypeDescription
String

publish(PubsubMessage message)

public ApiFuture<String> publish(PubsubMessage message)

Schedules the publishing of a message. The publishing of the message may occur immediately or be delayed based on the publisher batching options.

This method blocks in the downcall if using LimitExceededBehavior.Block in the flow control settings.

Example of publishing a message.


 String message = "my_message";
 ByteString data = ByteString.copyFromUtf8(message);
 PubsubMessage pubsubMessage = PubsubMessage.newBuilder().setData(data).build();
 ApiFuture<String> messageIdFuture = publisher.publish(pubsubMessage);
 ApiFutures.addCallback(messageIdFuture, new ApiFutureCallback<String>() {
   public void onSuccess(String messageId) {
     System.out.println("published with message id: " + messageId);
   }

   public void onFailure(Throwable t) {
     System.out.println("failed to publish: " + t);
   }
 }, MoreExecutors.directExecutor());
 
Parameter
NameDescription
messagePubsubMessage

the message to publish.

Returns
TypeDescription
ApiFuture<String>

the message ID wrapped in a future.

publishAllOutstanding()

public void publishAllOutstanding()

Publish any outstanding batches if non-empty. This method sends buffered messages, but does not wait for the send operations to complete. To wait for messages to send, call get on the futures returned from publish.

resumePublish(String key)

public void resumePublish(String key)

There may be non-recoverable problems with a request for an ordering key. In that case, all subsequent requests will fail until this method is called. If the key is not currently paused, calling this method will be a no-op.

Parameter
NameDescription
keyString

The key for which to resume publishing.

shutdown()

public void shutdown()

Schedules immediate publishing of any outstanding messages and waits until all are processed.

Sends remaining outstanding messages and prevents future calls to publish. This method should be invoked prior to deleting the Publisher object in order to ensure that no pending messages are lost.