com.google.cloud.pubsub.spi.v1

Class PublisherApi

java.lang.Object

com.google.cloud.pubsub.spi.v1.PublisherApi

All Implemented Interfaces:

java.lang.AutoCloseable

@Generated(value="by GAPIC")
public class PublisherApi
extends java.lang.Object
implements java.lang.AutoCloseable

Service Description: The service that an application uses to manipulate topics, and to send messages to a topic.

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:

 
 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedName = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   Topic response = publisherApi.createTopic(formattedName);
 }
 
 

Note: close() needs to be called on the publisherApi object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

The surface of this class includes several types of Java methods for each of the API's methods:

1. A "flattened" method. With this type of method, the fields of the request type have been converted into function parameters. It may be the case that not all fields are available as parameters, and not every API method will have a flattened method entry point.
2. A "request object" method. This type of method only takes one parameter, a request object, which must be constructed before the call. Not every API method will have a request object method.
3. A "callable" method. This type of method takes no parameters and returns an immutable ApiCallable object, which can be used to initiate calls to the service.

See the individual methods for example code.

Many parameters require resource names to be formatted in a particular way. To assist with these names, this class includes a format method for each type of name, and additionally a parse method to extract the individual identifiers contained within names that are returned.

This class can be customized by passing in a custom instance of PublisherSettings to create(). For example:

 
 PublisherSettings publisherSettings = PublisherSettings.defaultBuilder()
     .provideChannelWith(myCredentials)
     .build();
 PublisherApi publisherApi = PublisherApi.create(publisherSettings);
 
 

Method Summary

Modifier and Type	Method and Description
void	close() Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.
static PublisherApi	create(PublisherSettings settings) Constructs an instance of PublisherApi, using the given settings.
Topic	createTopic(java.lang.String name) Creates the given topic with the given name.
ApiCallable<Topic,Topic>	createTopicCallable() Creates the given topic with the given name.
static PublisherApi	createWithDefaults() Constructs an instance of PublisherApi with default settings.
void	deleteTopic(java.lang.String topic) Deletes the topic with the given name.
ApiCallable<DeleteTopicRequest,Empty>	deleteTopicCallable() Deletes the topic with the given name.
static java.lang.String	formatProjectName(java.lang.String project) Formats a string containing the fully-qualified path to represent a project resource.
static java.lang.String	formatTopicName(java.lang.String project, java.lang.String topic) Formats a string containing the fully-qualified path to represent a topic resource.
PublisherSettings	getSettings()
Topic	getTopic(java.lang.String topic) Gets the configuration of a topic.
ApiCallable<GetTopicRequest,Topic>	getTopicCallable() Gets the configuration of a topic.
PageAccessor<Topic>	listTopics(ListTopicsRequest request) Lists matching topics.
PageAccessor<Topic>	listTopics(java.lang.String project) Lists matching topics.
ApiCallable<ListTopicsRequest,ListTopicsResponse>	listTopicsCallable() Lists matching topics.
ApiCallable<ListTopicsRequest,PageAccessor<Topic>>	listTopicsPagedCallable() Lists matching topics.
PageAccessor<java.lang.String>	listTopicSubscriptions(ListTopicSubscriptionsRequest request) Lists the name of the subscriptions for this topic.
PageAccessor<java.lang.String>	listTopicSubscriptions(java.lang.String topic) Lists the name of the subscriptions for this topic.
ApiCallable<ListTopicSubscriptionsRequest,ListTopicSubscriptionsResponse>	listTopicSubscriptionsCallable() Lists the name of the subscriptions for this topic.
ApiCallable<ListTopicSubscriptionsRequest,PageAccessor<java.lang.String>>	listTopicSubscriptionsPagedCallable() Lists the name of the subscriptions for this topic.
static java.lang.String	parseProjectFromProjectName(java.lang.String projectName) Parses the project from the given fully-qualified path which represents a project resource.
static java.lang.String	parseProjectFromTopicName(java.lang.String topicName) Parses the project from the given fully-qualified path which represents a topic resource.
static java.lang.String	parseTopicFromTopicName(java.lang.String topicName) Parses the topic from the given fully-qualified path which represents a topic resource.
PublishResponse	publish(PublishRequest request) Adds one or more messages to the topic.
PublishResponse	publish(java.lang.String topic, java.util.List<PubsubMessage> messages) Adds one or more messages to the topic.
ApiCallable<PublishRequest,PublishResponse>	publishCallable() Adds one or more messages to the topic.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSettings

public final PublisherSettings getSettings()

formatProjectName

public static final java.lang.String formatProjectName(java.lang.String project)

Formats a string containing the fully-qualified path to represent a project resource.

formatTopicName

public static final java.lang.String formatTopicName(java.lang.String project,
                                                     java.lang.String topic)

Formats a string containing the fully-qualified path to represent a topic resource.

parseProjectFromProjectName

public static final java.lang.String parseProjectFromProjectName(java.lang.String projectName)

Parses the project from the given fully-qualified path which represents a project resource.

parseProjectFromTopicName

public static final java.lang.String parseProjectFromTopicName(java.lang.String topicName)

Parses the project from the given fully-qualified path which represents a topic resource.

parseTopicFromTopicName

public static final java.lang.String parseTopicFromTopicName(java.lang.String topicName)

Parses the topic from the given fully-qualified path which represents a topic resource.

createWithDefaults

public static final PublisherApi createWithDefaults()
                                             throws java.io.IOException

Constructs an instance of PublisherApi with default settings.

Throws:

java.io.IOException

create

public static final PublisherApi create(PublisherSettings settings)
                                 throws java.io.IOException

Constructs an instance of PublisherApi, using the given settings. The channels are created based on the settings passed in, or defaults for any settings that are not set.

Throws:

java.io.IOException

createTopic

public final Topic createTopic(java.lang.String name)

Creates the given topic with the given name. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedName = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   Topic response = publisherApi.createTopic(formattedName);
 }
 

Parameters:

name - The name of the topic. It must have the format `"projects/{project}/topics/{topic}"`. `{topic}` must start with a letter, and contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters in length, and it must not start with `"goog"`.

Throws:

ApiException - if the remote call fails

createTopicCallable

public final ApiCallable<Topic,Topic> createTopicCallable()

Creates the given topic with the given name. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedName = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   Topic request = Topic.newBuilder()
     .setName(formattedName)
     .build();
   ListenableFuture<Topic> future = publisherApi.createTopicCallable().futureCall(request);
   // Do something
   Topic response = future.get();
 }
 

publish

public final PublishResponse publish(java.lang.String topic,
                                     java.util.List<PubsubMessage> messages)

Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ByteString data = ByteString.copyFromUtf8("");
   PubsubMessage messagesElement = PubsubMessage.newBuilder()
     .setData(data)
     .build();
   List<PubsubMessage> messages = Arrays.asList(messagesElement);
   PublishResponse response = publisherApi.publish(formattedTopic, messages);
 }
 

Parameters:

topic - The messages in the request will be published on this topic.

messages - The messages to publish.

Throws:

ApiException - if the remote call fails

publish

public PublishResponse publish(PublishRequest request)

Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ByteString data = ByteString.copyFromUtf8("");
   PubsubMessage messagesElement = PubsubMessage.newBuilder()
     .setData(data)
     .build();
   List<PubsubMessage> messages = Arrays.asList(messagesElement);
   PublishRequest request = PublishRequest.newBuilder()
     .setTopic(formattedTopic)
     .addAllMessages(messages)
     .build();
   PublishResponse response = publisherApi.publish(request);
 }
 

Parameters:

request - The request object containing all of the parameters for the API call.

Throws:

ApiException - if the remote call fails

publishCallable

public final ApiCallable<PublishRequest,PublishResponse> publishCallable()

Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ByteString data = ByteString.copyFromUtf8("");
   PubsubMessage messagesElement = PubsubMessage.newBuilder()
     .setData(data)
     .build();
   List<PubsubMessage> messages = Arrays.asList(messagesElement);
   PublishRequest request = PublishRequest.newBuilder()
     .setTopic(formattedTopic)
     .addAllMessages(messages)
     .build();
   ListenableFuture<PublishResponse> future = publisherApi.publishCallable().futureCall(request);
   // Do something
   PublishResponse response = future.get();
 }
 

getTopic

public final Topic getTopic(java.lang.String topic)

Gets the configuration of a topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   Topic response = publisherApi.getTopic(formattedTopic);
 }
 

Parameters:

topic - The name of the topic to get.

Throws:

ApiException - if the remote call fails

getTopicCallable

public final ApiCallable<GetTopicRequest,Topic> getTopicCallable()

Gets the configuration of a topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   GetTopicRequest request = GetTopicRequest.newBuilder()
     .setTopic(formattedTopic)
     .build();
   ListenableFuture<Topic> future = publisherApi.getTopicCallable().futureCall(request);
   // Do something
   Topic response = future.get();
 }
 

listTopics

public final PageAccessor<Topic> listTopics(java.lang.String project)

Lists matching topics. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedProject = PublisherApi.formatProjectName("[PROJECT]");
   for (Topic elements : publisherApi.listTopics(formattedProject)) {
     // doThingsWith(elements);
   }
 }
 

Parameters:

project - The name of the cloud project that topics belong to.

Throws:

ApiException - if the remote call fails

listTopics

public final PageAccessor<Topic> listTopics(ListTopicsRequest request)

Lists matching topics. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedProject = PublisherApi.formatProjectName("[PROJECT]");
   ListTopicsRequest request = ListTopicsRequest.newBuilder()
     .setProject(formattedProject)
     .build();
   for (Topic elements : publisherApi.listTopics(request)) {
     // doThingsWith(elements);
   }
 }
 

Parameters:

request - The request object containing all of the parameters for the API call.

Throws:

ApiException - if the remote call fails

listTopicsPagedCallable

public final ApiCallable<ListTopicsRequest,PageAccessor<Topic>> listTopicsPagedCallable()

Lists matching topics. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedProject = PublisherApi.formatProjectName("[PROJECT]");
   ListTopicsRequest request = ListTopicsRequest.newBuilder()
     .setProject(formattedProject)
     .build();
   ListenableFuture<PageAccessor<Topic>> future = publisherApi.listTopicsPagedCallable().futureCall(request);
   // Do something
   for (Topic elements : future.get()) {
     // doThingsWith(elements);
   }
 }
 

listTopicsCallable

public final ApiCallable<ListTopicsRequest,ListTopicsResponse> listTopicsCallable()

Lists matching topics. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedProject = PublisherApi.formatProjectName("[PROJECT]");
   ListTopicsRequest request = ListTopicsRequest.newBuilder()
     .setProject(formattedProject)
     .build();
   while (true) {
     ListTopicsResponse response = publisherApi.listTopicsCallable().call(request);
     for (Topic elements : response.getTopicsList()) {
       // doThingsWith(elements);
     }
     String nextPageToken = response.getNextPageToken();
     if (!Strings.isNullOrEmpty(nextPageToken)) {
       request = request.toBuilder().setPageToken(nextPageToken).build();
     } else {
       break;
     }
   }
 }
 

listTopicSubscriptions

public final PageAccessor<java.lang.String> listTopicSubscriptions(java.lang.String topic)

Lists the name of the subscriptions for this topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   for (String elements : publisherApi.listTopicSubscriptions(formattedTopic)) {
     // doThingsWith(elements);
   }
 }
 

Parameters:

topic - The name of the topic that subscriptions are attached to.

Throws:

ApiException - if the remote call fails

listTopicSubscriptions

public final PageAccessor<java.lang.String> listTopicSubscriptions(ListTopicSubscriptionsRequest request)

Lists the name of the subscriptions for this topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ListTopicSubscriptionsRequest request = ListTopicSubscriptionsRequest.newBuilder()
     .setTopic(formattedTopic)
     .build();
   for (String elements : publisherApi.listTopicSubscriptions(request)) {
     // doThingsWith(elements);
   }
 }
 

Parameters:

request - The request object containing all of the parameters for the API call.

Throws:

ApiException - if the remote call fails

listTopicSubscriptionsPagedCallable

public final ApiCallable<ListTopicSubscriptionsRequest,PageAccessor<java.lang.String>> listTopicSubscriptionsPagedCallable()

Lists the name of the subscriptions for this topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ListTopicSubscriptionsRequest request = ListTopicSubscriptionsRequest.newBuilder()
     .setTopic(formattedTopic)
     .build();
   ListenableFuture<PageAccessor<String>> future = publisherApi.listTopicSubscriptionsPagedCallable().futureCall(request);
   // Do something
   for (String elements : future.get()) {
     // doThingsWith(elements);
   }
 }
 

listTopicSubscriptionsCallable

public final ApiCallable<ListTopicSubscriptionsRequest,ListTopicSubscriptionsResponse> listTopicSubscriptionsCallable()

Lists the name of the subscriptions for this topic. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   ListTopicSubscriptionsRequest request = ListTopicSubscriptionsRequest.newBuilder()
     .setTopic(formattedTopic)
     .build();
   while (true) {
     ListTopicSubscriptionsResponse response = publisherApi.listTopicSubscriptionsCallable().call(request);
     for (String elements : response.getSubscriptionsList()) {
       // doThingsWith(elements);
     }
     String nextPageToken = response.getNextPageToken();
     if (!Strings.isNullOrEmpty(nextPageToken)) {
       request = request.toBuilder().setPageToken(nextPageToken).build();
     } else {
       break;
     }
   }
 }
 

deleteTopic

public final void deleteTopic(java.lang.String topic)

Deletes the topic with the given name. Generates `NOT_FOUND` if the topic does not exist. After a topic is deleted, a new topic may be created with the same name; this is an entirely new topic with none of the old configuration or subscriptions. Existing subscriptions to this topic are not deleted, but their `topic` field is set to `_deleted-topic_`. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   publisherApi.deleteTopic(formattedTopic);
 }
 

Parameters:

topic - Name of the topic to delete.

Throws:

ApiException - if the remote call fails

deleteTopicCallable

public final ApiCallable<DeleteTopicRequest,Empty> deleteTopicCallable()

Deletes the topic with the given name. Generates `NOT_FOUND` if the topic does not exist. After a topic is deleted, a new topic may be created with the same name; this is an entirely new topic with none of the old configuration or subscriptions. Existing subscriptions to this topic are not deleted, but their `topic` field is set to `_deleted-topic_`. Sample code:

 try (PublisherApi publisherApi = PublisherApi.createWithDefaults()) {
   String formattedTopic = PublisherApi.formatTopicName("[PROJECT]", "[TOPIC]");
   DeleteTopicRequest request = DeleteTopicRequest.newBuilder()
     .setTopic(formattedTopic)
     .build();
   ListenableFuture<Void> future = publisherApi.deleteTopicCallable().futureCall(request);
   // Do something
   future.get();
 }
 

close

public final void close()
                 throws java.lang.Exception

Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception