Google Cloud Pub/Sub C++ Client  1.32.1
A C++ Client Library for Google Cloud Pub/Sub
topic_admin_client.h
Go to the documentation of this file.
1 // Copyright 2020 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_ADMIN_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_ADMIN_CLIENT_H
17 
18 #include "google/cloud/pubsub/snapshot.h"
19 #include "google/cloud/pubsub/topic_admin_connection.h"
20 #include "google/cloud/pubsub/topic_builder.h"
21 #include "google/cloud/pubsub/version.h"
22 #include <memory>
23 #include <string>
24 
25 namespace google {
26 namespace cloud {
27 namespace pubsub {
28 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
29 
30 /**
31  * Performs topic admin operations in Cloud Pub/Sub.
32  *
33  * Applications use this class to perform operations on
34  * [Cloud Pub/Sub][pubsub-doc-link].
35  *
36  * @par Performance
37  * `TopicAdminClient` objects are cheap to create, copy, and move. However,
38  * each `TopicAdminClient` object must be created with a
39  * `std::shared_ptr<TopicAdminConnection>`, which itself is relatively
40  * expensive to create. Therefore, connection instances should be shared when
41  * possible. See the `MakeTopicAdminConnection()` function and the
42  * `TopicAdminConnection` interface for more details.
43  *
44  * @par Thread Safety
45  * Instances of this class created via copy-construction or copy-assignment
46  * share the underlying pool of connections. Access to these copies via multiple
47  * threads is guaranteed to work. Two threads operating on the same instance of
48  * this class is not guaranteed to work.
49  *
50  * @par Error Handling
51  * This class uses `StatusOr<T>` to report errors. When an operation fails to
52  * perform its work the returned `StatusOr<T>` contains the error details. If
53  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
54  * contains the expected result. Please consult the
55  * [`StatusOr<T>` documentation](#google::cloud::v1::StatusOr) for more details.
56  *
57  * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs
58  */
60  public:
61  explicit TopicAdminClient(std::shared_ptr<TopicAdminConnection> connection);
62 
63  /**
64  * The default constructor is deleted.
65  *
66  * Use `PublisherClient(std::shared_ptr<PublisherConnection>)`
67  */
68  TopicAdminClient() = delete;
69 
70  /**
71  * Creates a new topic in Cloud Pub/Sub.
72  *
73  * @par Idempotency
74  * This operation is idempotent, as it succeeds only once, therefore the
75  * library retries the call. It might return a status code of
76  * `kAlreadyExists` as a consequence of retrying a successful (but reported as
77  * failed) request.
78  *
79  * @par Example
80  * @snippet samples.cc create-topic
81  *
82  * @param builder the configuration for the new topic, includes the name.
83  */
84  StatusOr<google::pubsub::v1::Topic> CreateTopic(TopicBuilder builder) {
85  return CreateTopic(std::move(builder).BuildCreateRequest());
86  }
87 
88  /// Create a new topic in Cloud Pub/Sub.
89  StatusOr<google::pubsub::v1::Topic> CreateTopic(
90  google::pubsub::v1::Topic request) {
91  return connection_->CreateTopic({std::move(request)});
92  }
93 
94  /**
95  * Gets information about an existing Cloud Pub/Sub topic.
96  *
97  * @par Idempotency
98  * This is a read-only operation and therefore always idempotent and retried.
99  *
100  * @par Example
101  * @snippet samples.cc get-topic
102  */
103  StatusOr<google::pubsub::v1::Topic> GetTopic(Topic topic) {
104  return connection_->GetTopic({std::move(topic)});
105  }
106 
107  /**
108  * Updates the configuration of an existing Cloud Pub/Sub topic.
109  *
110  * @par Idempotency
111  * This operation is idempotent, the state of the system is the same after one
112  * or several calls, and therefore it is always retried.
113  *
114  * @par Example
115  * @snippet samples.cc update-topic
116  *
117  * @param builder the configuration for the new topic, includes the name.
118  */
119  StatusOr<google::pubsub::v1::Topic> UpdateTopic(TopicBuilder builder) {
120  return connection_->UpdateTopic({std::move(builder).BuildUpdateRequest()});
121  }
122 
123  /**
124  * Lists all the topics for a given project id.
125  *
126  * @par Idempotency
127  * This is a read-only operation and therefore always idempotent and retried.
128  *
129  * @par Example
130  * @snippet samples.cc list-topics
131  */
132  ListTopicsRange ListTopics(std::string const& project_id) {
133  return connection_->ListTopics({"projects/" + project_id});
134  }
135 
136  /**
137  * Deletes an existing topic in Cloud Pub/Sub.
138  *
139  * @par Idempotency
140  * This operation is idempotent, the state of the system is the same after one
141  * or several calls, and therefore it is always retried. It might return a
142  * status code of `kNotFound` as a consequence of retrying a successful
143  * (but reported as failed) request.
144  *
145  * @par Example
146  * @snippet samples.cc delete-topic
147  *
148  * @param topic the name of the topic to be deleted.
149  */
151  return connection_->DeleteTopic({std::move(topic)});
152  }
153 
154  /**
155  * Detaches an existing subscription.
156  *
157  * This operation stops the subscription from receiving any further messages,
158  * it drops any messages still retained by the subscription, and any
159  * outstanding pull requests will fail with `kFailedPrecondition`.
160  *
161  * @par Idempotency
162  * This operation is idempotent, the state of the system is the same after one
163  * or several calls, and therefore it is always retried.
164  *
165  * @par Example
166  * @snippet samples.cc detach-subscription
167  *
168  * @param subscription the name of the subscription to detach.
169  */
170  StatusOr<google::pubsub::v1::DetachSubscriptionResponse> DetachSubscription(
171  Subscription subscription) {
172  return connection_->DetachSubscription({std::move(subscription)});
173  }
174 
175  /**
176  * Lists all the subscription names for a given topic.
177  *
178  * @note
179  * The returned range contains fully qualified subscription names, e.g.,
180  * `"projects/my-project/subscriptions/my-subscription"`. Applications may
181  * need to parse these names to use with other APIs.
182  *
183  * @par Idempotency
184  * This is a read-only operation and therefore always idempotent and retried.
185  *
186  * @par Example
187  * @snippet samples.cc list-topic-subscriptions
188  */
189  ListTopicSubscriptionsRange ListTopicSubscriptions(Topic const& topic) {
190  return connection_->ListTopicSubscriptions({topic.FullName()});
191  }
192 
193  /**
194  * Lists all the subscription names for a given topic.
195  *
196  * @note
197  * The returned range contains fully qualified snapshot names, e.g.,
198  * `"projects/my-project/snapshots/my-subscription"`. Applications may
199  * need to parse these names to use with other APIs.
200  *
201  * @par Idempotency
202  * This is a read-only operation and therefore always idempotent and retried.
203  *
204  * @par Example
205  * @snippet samples.cc list-topic-snapshots
206  *
207  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
208  * description of Cloud Pub/Sub's snapshots.
209  */
210  ListTopicSnapshotsRange ListTopicSnapshots(Topic const& topic) {
211  return connection_->ListTopicSnapshots({topic.FullName()});
212  }
213 
214  private:
215  std::shared_ptr<TopicAdminConnection> connection_;
216 };
217 
218 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
219 } // namespace pubsub
220 } // namespace cloud
221 } // namespace google
222 
223 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_ADMIN_CLIENT_H