Package com.google.cloud.pubsub.v1 (1.118.0)

A client to Cloud Pub/Sub API

The interfaces provided are listed below, along with usage samples.

TopicAdminClient

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

Sample for TopicAdminClient:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
   TopicName name = TopicName.ofProjectTopicName("[PROJECT]", "[TOPIC]");
   Topic response = topicAdminClient.createTopic(name);
 }

SubscriptionAdminClient

Service Description: The service that an application uses to manipulate subscriptions and to consume messages from a subscription via the Pull method or by establishing a bi-directional stream using the StreamingPull method.

Sample for SubscriptionAdminClient:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
   SubscriptionName name = SubscriptionName.of("[PROJECT]", "[SUBSCRIPTION]");
   TopicName topic = TopicName.ofProjectTopicName("[PROJECT]", "[TOPIC]");
   PushConfig pushConfig = PushConfig.newBuilder().build();
   int ackDeadlineSeconds = 2135351438;
   Subscription response =
       subscriptionAdminClient.createSubscription(name, topic, pushConfig, ackDeadlineSeconds);
 }

SchemaServiceClient

Service Description: Service for doing schema-related operations.

Sample for SchemaServiceClient:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
   ProjectName parent = ProjectName.of("[PROJECT]");
   Schema schema = Schema.newBuilder().build();
   String schemaId = "schemaId-697673060";
   Schema response = schemaServiceClient.createSchema(parent, schema, schemaId);
 }

Classes

AckRequestData

AckRequestData.Builder

Builder of AckRequestData.

OpenCensusUtil

Utilities for propagating OpenCensus TagContext and SpanContext from publishers to subscribers.

OpenCensusUtil.OpenCensusMessageReceiver

Wrapper class for MessageReceiver that decodes any received trace and tag contexts and puts them in scope.

Publisher

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.

Publisher.Builder

A builder of Publishers.

SchemaServiceClient

Service Description: Service for doing schema-related operations.

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:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
   ProjectName parent = ProjectName.of("[PROJECT]");
   Schema schema = Schema.newBuilder().build();
   String schemaId = "schemaId-697673060";
   Schema response = schemaServiceClient.createSchema(parent, schema, schemaId);
 }

Note: close() needs to be called on the SchemaServiceClient 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 API callable 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 SchemaServiceSettings to create(). For example:

To customize credentials:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SchemaServiceSettings schemaServiceSettings =
     SchemaServiceSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 SchemaServiceClient schemaServiceClient = SchemaServiceClient.create(schemaServiceSettings);

To customize the endpoint:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SchemaServiceSettings schemaServiceSettings =
     SchemaServiceSettings.newBuilder().setEndpoint(myEndpoint).build();
 SchemaServiceClient schemaServiceClient = SchemaServiceClient.create(schemaServiceSettings);

Please refer to the GitHub repository's samples for more quickstart code snippets.

SchemaServiceClient.ListSchemasFixedSizeCollection

SchemaServiceClient.ListSchemasPage

SchemaServiceClient.ListSchemasPagedResponse

SchemaServiceSettings

Settings class to configure an instance of SchemaServiceClient.

The default instance has everything set to sensible defaults:

  • The default service address (pubsub.googleapis.com) and default port (443) are used.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.

For example, to set the total timeout of createSchema to 30 seconds:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SchemaServiceSettings.Builder schemaServiceSettingsBuilder = SchemaServiceSettings.newBuilder();
 schemaServiceSettingsBuilder
     .createSchemaSettings()
     .setRetrySettings(
         schemaServiceSettingsBuilder
             .createSchemaSettings()
             .getRetrySettings()
             .toBuilder()
             .setTotalTimeout(Duration.ofSeconds(30))
             .build());
 SchemaServiceSettings schemaServiceSettings = schemaServiceSettingsBuilder.build();

SchemaServiceSettings.Builder

Builder for SchemaServiceSettings.

Subscriber

A Cloud Pub/Sub subscriber that is associated with a specific subscription at creation.

A Subscriber allows you to provide an implementation of a receiver to which messages are going to be delivered as soon as they are received by the subscriber. The delivered messages then can be acked or nacked at will as they get processed by the receiver. Nacking a messages implies a later redelivery of such message.

The subscriber handles the ack management, by automatically extending the ack deadline while the message is being processed, to then issue the ack or nack of such message when the processing is done (see Builder#setMaxAckExtensionPeriod(Duration)). Note: message redelivery is still possible.

It also provides customizable options that control:

  • Ack deadline extension: such as the amount of time ahead to trigger the extension of message acknowledgement expiration.
  • Flow control: such as the maximum outstanding messages or maximum outstanding bytes to keep in memory before the receiver either ack or nack them.

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

Subscriber is implemented using Guava's Service and provides the same methods. See Guava documentation for more details.

Subscriber.Builder

Builder of Subscribers.

SubscriptionAdminClient

Service Description: The service that an application uses to manipulate subscriptions and to consume messages from a subscription via the Pull method or by establishing a bi-directional stream using the StreamingPull method.

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:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
   SubscriptionName name = SubscriptionName.of("[PROJECT]", "[SUBSCRIPTION]");
   TopicName topic = TopicName.ofProjectTopicName("[PROJECT]", "[TOPIC]");
   PushConfig pushConfig = PushConfig.newBuilder().build();
   int ackDeadlineSeconds = 2135351438;
   Subscription response =
       subscriptionAdminClient.createSubscription(name, topic, pushConfig, ackDeadlineSeconds);
 }

Note: close() needs to be called on the SubscriptionAdminClient 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 API callable 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 SubscriptionAdminSettings to create(). For example:

To customize credentials:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SubscriptionAdminSettings subscriptionAdminSettings =
     SubscriptionAdminSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 SubscriptionAdminClient subscriptionAdminClient =
     SubscriptionAdminClient.create(subscriptionAdminSettings);

To customize the endpoint:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SubscriptionAdminSettings subscriptionAdminSettings =
     SubscriptionAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
 SubscriptionAdminClient subscriptionAdminClient =
     SubscriptionAdminClient.create(subscriptionAdminSettings);

Please refer to the GitHub repository's samples for more quickstart code snippets.

SubscriptionAdminClient.ListSnapshotsFixedSizeCollection

SubscriptionAdminClient.ListSnapshotsPage

SubscriptionAdminClient.ListSnapshotsPagedResponse

SubscriptionAdminClient.ListSubscriptionsFixedSizeCollection

SubscriptionAdminClient.ListSubscriptionsPage

SubscriptionAdminClient.ListSubscriptionsPagedResponse

SubscriptionAdminSettings

Settings class to configure an instance of SubscriptionAdminClient.

The default instance has everything set to sensible defaults:

  • The default service address (pubsub.googleapis.com) and default port (443) are used.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.

For example, to set the total timeout of createSubscription to 30 seconds:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 SubscriptionAdminSettings.Builder subscriptionAdminSettingsBuilder =
     SubscriptionAdminSettings.newBuilder();
 subscriptionAdminSettingsBuilder
     .createSubscriptionSettings()
     .setRetrySettings(
         subscriptionAdminSettingsBuilder
             .createSubscriptionSettings()
             .getRetrySettings()
             .toBuilder()
             .setTotalTimeout(Duration.ofSeconds(30))
             .build());
 SubscriptionAdminSettings subscriptionAdminSettings = subscriptionAdminSettingsBuilder.build();

SubscriptionAdminSettings.Builder

Builder for SubscriptionAdminSettings.

TopicAdminClient

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:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
   TopicName name = TopicName.ofProjectTopicName("[PROJECT]", "[TOPIC]");
   Topic response = topicAdminClient.createTopic(name);
 }

Note: close() needs to be called on the TopicAdminClient 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 API callable 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 TopicAdminSettings to create(). For example:

To customize credentials:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 TopicAdminSettings topicAdminSettings =
     TopicAdminSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 TopicAdminClient topicAdminClient = TopicAdminClient.create(topicAdminSettings);

To customize the endpoint:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 TopicAdminSettings topicAdminSettings =
     TopicAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
 TopicAdminClient topicAdminClient = TopicAdminClient.create(topicAdminSettings);

Please refer to the GitHub repository's samples for more quickstart code snippets.

TopicAdminClient.ListTopicSnapshotsFixedSizeCollection

TopicAdminClient.ListTopicSnapshotsPage

TopicAdminClient.ListTopicSnapshotsPagedResponse

TopicAdminClient.ListTopicSubscriptionsFixedSizeCollection

TopicAdminClient.ListTopicSubscriptionsPage

TopicAdminClient.ListTopicSubscriptionsPagedResponse

TopicAdminClient.ListTopicsFixedSizeCollection

TopicAdminClient.ListTopicsPage

TopicAdminClient.ListTopicsPagedResponse

TopicAdminSettings

Settings class to configure an instance of TopicAdminClient.

The default instance has everything set to sensible defaults:

  • The default service address (pubsub.googleapis.com) and default port (443) are used.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.

For example, to set the total timeout of createTopic to 30 seconds:


 // This snippet has been automatically generated for illustrative purposes only.
 // It may require modifications to work in your environment.
 TopicAdminSettings.Builder topicAdminSettingsBuilder = TopicAdminSettings.newBuilder();
 topicAdminSettingsBuilder
     .createTopicSettings()
     .setRetrySettings(
         topicAdminSettingsBuilder
             .createTopicSettings()
             .getRetrySettings()
             .toBuilder()
             .setTotalTimeout(Duration.ofSeconds(30))
             .build());
 TopicAdminSettings topicAdminSettings = topicAdminSettingsBuilder.build();

TopicAdminSettings.Builder

Builder for TopicAdminSettings.

Interfaces

AckReplyConsumer

Accepts a reply, sending it to the service.

AckReplyConsumerWithResponse

Acknowledging a message in Pub/Sub means that you are done with it, and it will not be delivered to this subscription again. You should avoid acknowledging messages until you have finished processing them, so that in the event of a failure, you receive the message again.

If exactly-once delivery is enabled on the subscription, the future returned by the ack/nack methods track the state of acknowledgement operation by the server. If the future completes successfully, the message is guaranteed NOT to be re-delivered. Otherwise, the future will contain an exception with more details about the failure and the message may be re-delivered.

If exactly-once delivery is NOT enabled on the subscription, the future returns immediately with an AckResponse.SUCCESS. Because re-deliveries are possible, you should ensure that your processing code is idempotent, as you may receive any given message more than once.

MessageReceiver

This interface can be implemented by users of Subscriber to receive messages.

MessageReceiverWithAckResponse

PublisherInterface

An interface for a Cloud Pub/Sub publisher.

SubscriberInterface

The core interface for a Cloud Pub/Sub subscriber, consisting only of ApiService methods.

Enums

AckResponse