Google Cloud Pub/Sub C++ Client  1.32.1
A C++ Client Library for Google Cloud Pub/Sub
Public Member Functions | List of all members
google::cloud::pubsub::v1::TopicAdminClient Class Reference

Performs topic admin operations in Cloud Pub/Sub. More...

#include <google/cloud/pubsub/topic_admin_client.h>

Public Member Functions

 TopicAdminClient (std::shared_ptr< TopicAdminConnection > connection)
 
 TopicAdminClient ()=delete
 The default constructor is deleted. More...
 
StatusOr< google::pubsub::v1::Topic > CreateTopic (TopicBuilder builder)
 Creates a new topic in Cloud Pub/Sub. More...
 
StatusOr< google::pubsub::v1::Topic > CreateTopic (google::pubsub::v1::Topic request)
 Create a new topic in Cloud Pub/Sub. More...
 
StatusOr< google::pubsub::v1::Topic > GetTopic (Topic topic)
 Gets information about an existing Cloud Pub/Sub topic. More...
 
StatusOr< google::pubsub::v1::Topic > UpdateTopic (TopicBuilder builder)
 Updates the configuration of an existing Cloud Pub/Sub topic. More...
 
ListTopicsRange ListTopics (std::string const &project_id)
 Lists all the topics for a given project id. More...
 
Status DeleteTopic (Topic topic)
 Deletes an existing topic in Cloud Pub/Sub. More...
 
StatusOr< google::pubsub::v1::DetachSubscriptionResponse > DetachSubscription (Subscription subscription)
 Detaches an existing subscription. More...
 
ListTopicSubscriptionsRange ListTopicSubscriptions (Topic const &topic)
 Lists all the subscription names for a given topic. More...
 
ListTopicSnapshotsRange ListTopicSnapshots (Topic const &topic)
 Lists all the subscription names for a given topic. More...
 

Detailed Description

Performs topic admin operations in Cloud Pub/Sub.

Applications use this class to perform operations on Cloud Pub/Sub.

Performance
TopicAdminClient objects are cheap to create, copy, and move. However, each TopicAdminClient object must be created with a std::shared_ptr<TopicAdminConnection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeTopicAdminConnection() function and the TopicAdminConnection interface for more details.
Thread Safety
Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.
Error Handling
This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. Please consult the StatusOr<T> documentation for more details.

Definition at line 59 of file topic_admin_client.h.

Constructor & Destructor Documentation

◆ TopicAdminClient() [1/2]

google::cloud::pubsub::v1::TopicAdminClient::TopicAdminClient ( std::shared_ptr< TopicAdminConnection connection)
explicit

Definition at line 22 of file topic_admin_client.cc.

◆ TopicAdminClient() [2/2]

google::cloud::pubsub::v1::TopicAdminClient::TopicAdminClient ( )
delete

The default constructor is deleted.

Use PublisherClient(std::shared_ptr<PublisherConnection>)

Member Function Documentation

◆ CreateTopic() [1/2]

StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::v1::TopicAdminClient::CreateTopic ( google::pubsub::v1::Topic  request)
inline

Create a new topic in Cloud Pub/Sub.

Definition at line 89 of file topic_admin_client.h.

◆ CreateTopic() [2/2]

StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::v1::TopicAdminClient::CreateTopic ( TopicBuilder  builder)
inline

Creates a new topic in Cloud Pub/Sub.

Idempotency
This operation is idempotent, as it succeeds only once, therefore the library retries the call. It might return a status code of kAlreadyExists as a consequence of retrying a successful (but reported as failed) request.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string topic_id) {
auto topic = client.CreateTopic(pubsub::TopicBuilder(
pubsub::Topic(std::move(project_id), std::move(topic_id))));
// Note that kAlreadyExists is a possible error when the library retries.
if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
std::cout << "The topic already exists\n";
return;
}
if (!topic) throw std::runtime_error(topic.status().message());
std::cout << "The topic was successfully created: " << topic->DebugString()
<< "\n";
}
Performs topic admin operations in Cloud Pub/Sub.
StatusOr< google::pubsub::v1::Topic > CreateTopic(TopicBuilder builder)
Creates a new topic in Cloud Pub/Sub.
Builds requests to create or update a Cloud Pub/Sub topic.
Definition: topic_builder.h:34
Objects of this class identify a Cloud Pub/Sub topic.
Definition: topic.h:37
Contains all the Cloud Pubsub C++ client types and functions.
Definition: ack_handler.cc:20
Parameters
builderthe configuration for the new topic, includes the name.

Definition at line 84 of file topic_admin_client.h.

◆ DeleteTopic()

Status google::cloud::pubsub::v1::TopicAdminClient::DeleteTopic ( Topic  topic)
inline

Deletes an existing topic in Cloud Pub/Sub.

Idempotency
This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried. It might return a status code of kNotFound as a consequence of retrying a successful (but reported as failed) request.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string const& project_id,
std::string const& topic_id) {
auto status = client.DeleteTopic(
pubsub::Topic(std::move(project_id), std::move(topic_id)));
// Note that kNotFound is a possible result when the library retries.
if (status.code() == google::cloud::StatusCode::kNotFound) {
std::cout << "The topic was not found\n";
return;
}
if (!status.ok()) throw std::runtime_error(status.message());
std::cout << "The topic was successfully deleted\n";
}
Status DeleteTopic(Topic topic)
Deletes an existing topic in Cloud Pub/Sub.
Parameters
topicthe name of the topic to be deleted.

Definition at line 150 of file topic_admin_client.h.

◆ DetachSubscription()

StatusOr<google::pubsub::v1::DetachSubscriptionResponse> google::cloud::pubsub::v1::TopicAdminClient::DetachSubscription ( Subscription  subscription)
inline

Detaches an existing subscription.

This operation stops the subscription from receiving any further messages, it drops any messages still retained by the subscription, and any outstanding pull requests will fail with kFailedPrecondition.

Idempotency
This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string subscription_id) {
auto response = client.DetachSubscription(pubsub::Subscription(
std::move(project_id), std::move(subscription_id)));
if (!response.ok()) return; // TODO(#4792) - not implemented in emulator
std::cout << "The subscription was successfully detached: "
<< response->DebugString() << "\n";
}
Objects of this class identify a Cloud Pub/Sub subscription.
Definition: subscription.h:37
StatusOr< google::pubsub::v1::DetachSubscriptionResponse > DetachSubscription(Subscription subscription)
Detaches an existing subscription.
Parameters
subscriptionthe name of the subscription to detach.

Definition at line 170 of file topic_admin_client.h.

◆ GetTopic()

StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::v1::TopicAdminClient::GetTopic ( Topic  topic)
inline

Gets information about an existing Cloud Pub/Sub topic.

Idempotency
This is a read-only operation and therefore always idempotent and retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string topic_id) {
auto topic = client.GetTopic(
pubsub::Topic(std::move(project_id), std::move(topic_id)));
if (!topic) throw std::runtime_error(topic.status().message());
std::cout << "The topic information was successfully retrieved: "
<< topic->DebugString() << "\n";
}
StatusOr< google::pubsub::v1::Topic > GetTopic(Topic topic)
Gets information about an existing Cloud Pub/Sub topic.

Definition at line 103 of file topic_admin_client.h.

◆ ListTopics()

ListTopicsRange google::cloud::pubsub::v1::TopicAdminClient::ListTopics ( std::string const &  project_id)
inline

Lists all the topics for a given project id.

Idempotency
This is a read-only operation and therefore always idempotent and retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string const& project_id) {
int count = 0;
for (auto const& topic : client.ListTopics(project_id)) {
if (!topic) throw std::runtime_error(topic.status().message());
std::cout << "Topic Name: " << topic->name() << "\n";
++count;
}
if (count == 0) {
std::cout << "No topics found in project " << project_id << "\n";
}
}
ListTopicsRange ListTopics(std::string const &project_id)
Lists all the topics for a given project id.

Definition at line 132 of file topic_admin_client.h.

◆ ListTopicSnapshots()

ListTopicSnapshotsRange google::cloud::pubsub::v1::TopicAdminClient::ListTopicSnapshots ( Topic const &  topic)
inline

Lists all the subscription names for a given topic.

Note
The returned range contains fully qualified snapshot names, e.g., "projects/my-project/snapshots/my-subscription". Applications may need to parse these names to use with other APIs.
Idempotency
This is a read-only operation and therefore always idempotent and retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string topic_id) {
auto const topic =
pubsub::Topic(std::move(project_id), std::move(topic_id));
std::cout << "Snapshot list for topic " << topic << ":\n";
for (auto const& name : client.ListTopicSnapshots(topic)) {
if (!name) throw std::runtime_error(name.status().message());
std::cout << " " << *name << "\n";
}
}
ListTopicSnapshotsRange ListTopicSnapshots(Topic const &topic)
Lists all the subscription names for a given topic.
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 210 of file topic_admin_client.h.

◆ ListTopicSubscriptions()

ListTopicSubscriptionsRange google::cloud::pubsub::v1::TopicAdminClient::ListTopicSubscriptions ( Topic const &  topic)
inline

Lists all the subscription names for a given topic.

Note
The returned range contains fully qualified subscription names, e.g., "projects/my-project/subscriptions/my-subscription". Applications may need to parse these names to use with other APIs.
Idempotency
This is a read-only operation and therefore always idempotent and retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string topic_id) {
auto const topic =
pubsub::Topic(std::move(project_id), std::move(topic_id));
std::cout << "Subscription list for topic " << topic << ":\n";
for (auto const& name : client.ListTopicSubscriptions(topic)) {
if (!name) throw std::runtime_error(name.status().message());
std::cout << " " << *name << "\n";
}
}
ListTopicSubscriptionsRange ListTopicSubscriptions(Topic const &topic)
Lists all the subscription names for a given topic.

Definition at line 189 of file topic_admin_client.h.

◆ UpdateTopic()

StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::v1::TopicAdminClient::UpdateTopic ( TopicBuilder  builder)
inline

Updates the configuration of an existing Cloud Pub/Sub topic.

Idempotency
This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.
Example
namespace pubsub = ::google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
std::string topic_id) {
auto topic = client.UpdateTopic(
pubsub::Topic(std::move(project_id), std::move(topic_id)))
.add_label("test-key", "test-value"));
if (!topic) return; // TODO(#4792) - emulator lacks UpdateTopic()
std::cout << "The topic was successfully updated: " << topic->DebugString()
<< "\n";
}
StatusOr< google::pubsub::v1::Topic > UpdateTopic(TopicBuilder builder)
Updates the configuration of an existing Cloud Pub/Sub topic.
TopicBuilder & add_label(std::string const &key, std::string const &value) &
Definition: topic_builder.h:44
Parameters
builderthe configuration for the new topic, includes the name.

Definition at line 119 of file topic_admin_client.h.