com.google.cloud.pubsub.spi.v1

Class PublisherApi

java.lang.Object

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

All Implemented Interfaces:

AutoCloseable

@Generated(value="by GAPIC")
public class PublisherApi
extends Object
implements 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);
 
 

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PublisherApi(PublisherSettings settings) Constructs an instance of PublisherApi, using the given settings.

Method Summary

Methods

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.
com.google.pubsub.v1.Topic	createTopic(String name) Creates the given topic with the given name.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.Topic,com.google.pubsub.v1.Topic>	createTopicCallable() Creates the given topic with the given name.
static PublisherApi	createWithDefaults() Constructs an instance of PublisherApi with default settings.
void	deleteTopic(String topic) Deletes the topic with the given name.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.DeleteTopicRequest,com.google.protobuf.Empty>	deleteTopicCallable() Deletes the topic with the given name.
static String	formatProjectName(String project) Formats a string containing the fully-qualified path to represent a project resource.
static String	formatTopicName(String project, String topic) Formats a string containing the fully-qualified path to represent a topic resource.
PublisherSettings	getSettings()
com.google.pubsub.v1.Topic	getTopic(String topic) Gets the configuration of a topic.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.GetTopicRequest,com.google.pubsub.v1.Topic>	getTopicCallable() Gets the configuration of a topic.
com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.Topic>	listTopics(com.google.pubsub.v1.ListTopicsRequest request) Lists matching topics.
com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.Topic>	listTopics(String project) Lists matching topics.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicsRequest,com.google.pubsub.v1.ListTopicsResponse>	listTopicsCallable() Lists matching topics.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicsRequest,com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.Topic>>	listTopicsPagedCallable() Lists matching topics.
com.google.api.gax.core.PageAccessor<String>	listTopicSubscriptions(com.google.pubsub.v1.ListTopicSubscriptionsRequest request) Lists the name of the subscriptions for this topic.
com.google.api.gax.core.PageAccessor<String>	listTopicSubscriptions(String topic) Lists the name of the subscriptions for this topic.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicSubscriptionsRequest,com.google.pubsub.v1.ListTopicSubscriptionsResponse>	listTopicSubscriptionsCallable() Lists the name of the subscriptions for this topic.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicSubscriptionsRequest,com.google.api.gax.core.PageAccessor<String>>	listTopicSubscriptionsPagedCallable() Lists the name of the subscriptions for this topic.
static String	parseProjectFromProjectName(String projectName) Parses the project from the given fully-qualified path which represents a project resource.
static String	parseProjectFromTopicName(String topicName) Parses the project from the given fully-qualified path which represents a topic resource.
static String	parseTopicFromTopicName(String topicName) Parses the topic from the given fully-qualified path which represents a topic resource.
com.google.pubsub.v1.PublishResponse	publish(com.google.pubsub.v1.PublishRequest request) Adds one or more messages to the topic.
com.google.pubsub.v1.PublishResponse	publish(String topic, List<com.google.pubsub.v1.PubsubMessage> messages) Adds one or more messages to the topic.
com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.PublishRequest,com.google.pubsub.v1.PublishResponse>	publishCallable() Adds one or more messages to the topic.

Methods inherited from class java.lang.Object

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

Constructor Detail

PublisherApi

protected PublisherApi(PublisherSettings settings)
                throws IOException

Constructs an instance of PublisherApi, using the given settings. This is protected so that it easy to make a subclass, but otherwise, the static factory methods should be preferred.

Throws:

IOException

Method Detail

getSettings

public final PublisherSettings getSettings()

formatProjectName

public static final String formatProjectName(String project)

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

formatTopicName

public static final String formatTopicName(String project,
                     String topic)

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

parseProjectFromProjectName

public static final String parseProjectFromProjectName(String projectName)

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

parseProjectFromTopicName

public static final String parseProjectFromTopicName(String topicName)

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

parseTopicFromTopicName

public static final String parseTopicFromTopicName(String topicName)

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

createWithDefaults

public static final PublisherApi createWithDefaults()
                                             throws IOException

Constructs an instance of PublisherApi with default settings.

Throws:

IOException

create

public static final PublisherApi create(PublisherSettings settings)
                                 throws 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:

IOException

createTopic

public final com.google.pubsub.v1.Topic createTopic(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:

com.google.api.gax.grpc.ApiException - if the remote call fails

createTopicCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.Topic,com.google.pubsub.v1.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 com.google.pubsub.v1.PublishResponse publish(String topic,
                                           List<com.google.pubsub.v1.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]");
   List<PubsubMessage> messages = new ArrayList<>();
   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:

com.google.api.gax.grpc.ApiException - if the remote call fails

publish

public com.google.pubsub.v1.PublishResponse publish(com.google.pubsub.v1.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]");
   List<PubsubMessage> messages = new ArrayList<>();
   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:

com.google.api.gax.grpc.ApiException - if the remote call fails

publishCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.PublishRequest,com.google.pubsub.v1.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]");
   List<PubsubMessage> messages = new ArrayList<>();
   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 com.google.pubsub.v1.Topic getTopic(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:

com.google.api.gax.grpc.ApiException - if the remote call fails

getTopicCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.GetTopicRequest,com.google.pubsub.v1.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 com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.Topic> listTopics(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:

com.google.api.gax.grpc.ApiException - if the remote call fails

listTopics

public final com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.Topic> listTopics(com.google.pubsub.v1.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:

com.google.api.gax.grpc.ApiException - if the remote call fails

listTopicsPagedCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicsRequest,com.google.api.gax.core.PageAccessor<com.google.pubsub.v1.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 com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicsRequest,com.google.pubsub.v1.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 com.google.api.gax.core.PageAccessor<String> listTopicSubscriptions(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:

com.google.api.gax.grpc.ApiException - if the remote call fails

listTopicSubscriptions

public final com.google.api.gax.core.PageAccessor<String> listTopicSubscriptions(com.google.pubsub.v1.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:

com.google.api.gax.grpc.ApiException - if the remote call fails

listTopicSubscriptionsPagedCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicSubscriptionsRequest,com.google.api.gax.core.PageAccessor<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 com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.ListTopicSubscriptionsRequest,com.google.pubsub.v1.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(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:

com.google.api.gax.grpc.ApiException - if the remote call fails

deleteTopicCallable

public final com.google.api.gax.grpc.ApiCallable<com.google.pubsub.v1.DeleteTopicRequest,com.google.protobuf.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 Exception

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

Specified by:

close in interface AutoCloseable

Throws:

Exception