Google Cloud Pub/Sub C++ Client  2.4.0
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 // https://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 {
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 [`StatusOr<T>`
55  * documentation](#google::cloud::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  Options opts = {});
63 
64  /**
65  * The default constructor is deleted.
66  *
67  * Use `PublisherClient(std::shared_ptr<PublisherConnection>)`
68  */
69  TopicAdminClient() = delete;
70 
71  /**
72  * Creates a new topic in Cloud Pub/Sub.
73  *
74  * @par Idempotency
75  * This operation is idempotent, as it succeeds only once, therefore the
76  * library retries the call. It might return a status code of
77  * `kAlreadyExists` as a consequence of retrying a successful (but reported as
78  * failed) request.
79  *
80  * @par Example
81  * @snippet samples.cc create-topic
82  *
83  * @param builder the configuration for the new topic, includes the name.
84  * @param opts Override the class-level options, such as retry and backoff
85  * policies.
86  */
87  StatusOr<google::pubsub::v1::Topic> CreateTopic(TopicBuilder builder,
88  Options opts = {}) {
89  return CreateTopic(std::move(builder).BuildCreateRequest(),
90  std::move(opts));
91  }
92 
93  /// Create a new topic in Cloud Pub/Sub.
94  StatusOr<google::pubsub::v1::Topic> CreateTopic(
95  google::pubsub::v1::Topic request, Options opts = {}) {
96  internal::OptionsSpan span(
97  internal::MergeOptions(std::move(opts), options_));
98  return connection_->CreateTopic({std::move(request)});
99  }
100 
101  /**
102  * Gets information about an existing Cloud Pub/Sub topic.
103  *
104  * @par Idempotency
105  * This is a read-only operation and therefore always idempotent and retried.
106  *
107  * @par Example
108  * @snippet samples.cc get-topic
109  */
110  StatusOr<google::pubsub::v1::Topic> GetTopic(Topic topic, Options opts = {}) {
111  internal::OptionsSpan span(
112  internal::MergeOptions(std::move(opts), options_));
113  return connection_->GetTopic({std::move(topic)});
114  }
115 
116  /**
117  * Updates the configuration of an existing Cloud Pub/Sub topic.
118  *
119  * @par Idempotency
120  * This operation is idempotent, the state of the system is the same after one
121  * or several calls, and therefore it is always retried.
122  *
123  * @par Example
124  * @snippet samples.cc update-topic
125  *
126  * @param builder the configuration for the new topic, includes the name.
127  * @param opts Override the class-level options, such as retry and backoff
128  * policies.
129  */
130  StatusOr<google::pubsub::v1::Topic> UpdateTopic(TopicBuilder builder,
131  Options opts = {}) {
132  internal::OptionsSpan span(
133  internal::MergeOptions(std::move(opts), options_));
134  return connection_->UpdateTopic({std::move(builder).BuildUpdateRequest()});
135  }
136 
137  /**
138  * Lists all the topics for a given project id.
139  *
140  * @par Idempotency
141  * This is a read-only operation and therefore always idempotent and retried.
142  *
143  * @par Example
144  * @snippet samples.cc list-topics
145  */
146  ListTopicsRange ListTopics(std::string const& project_id, Options opts = {}) {
147  internal::OptionsSpan span(
148  internal::MergeOptions(std::move(opts), options_));
149  return connection_->ListTopics({"projects/" + project_id});
150  }
151 
152  /**
153  * Deletes an existing topic in Cloud Pub/Sub.
154  *
155  * @par Idempotency
156  * This operation is idempotent, the state of the system is the same after one
157  * or several calls, and therefore it is always retried. It might return a
158  * status code of `kNotFound` as a consequence of retrying a successful
159  * (but reported as failed) request.
160  *
161  * @par Example
162  * @snippet samples.cc delete-topic
163  *
164  * @param topic the name of the topic to be deleted.
165  * @param opts Override the class-level options, such as retry and backoff
166  * policies.
167  */
169  internal::OptionsSpan span(
170  internal::MergeOptions(std::move(opts), options_));
171  return connection_->DeleteTopic({std::move(topic)});
172  }
173 
174  /**
175  * Detaches an existing subscription.
176  *
177  * This operation stops the subscription from receiving any further messages,
178  * it drops any messages still retained by the subscription, and any
179  * outstanding pull requests will fail with `kFailedPrecondition`.
180  *
181  * @par Idempotency
182  * This operation is idempotent, the state of the system is the same after one
183  * or several calls, and therefore it is always retried.
184  *
185  * @par Example
186  * @snippet samples.cc detach-subscription
187  *
188  * @param subscription the name of the subscription to detach.
189  * @param opts Override the class-level options, such as retry and backoff
190  * policies.
191  */
192  StatusOr<google::pubsub::v1::DetachSubscriptionResponse> DetachSubscription(
193  Subscription subscription, Options opts = {}) {
194  internal::OptionsSpan span(
195  internal::MergeOptions(std::move(opts), options_));
196  return connection_->DetachSubscription({std::move(subscription)});
197  }
198 
199  /**
200  * Lists all the subscription names for a given topic.
201  *
202  * @note
203  * The returned range contains fully qualified subscription names, e.g.,
204  * `"projects/my-project/subscriptions/my-subscription"`. Applications may
205  * need to parse these names to use with other APIs.
206  *
207  * @par Idempotency
208  * This is a read-only operation and therefore always idempotent and retried.
209  *
210  * @par Example
211  * @snippet samples.cc list-topic-subscriptions
212  */
213  ListTopicSubscriptionsRange ListTopicSubscriptions(Topic const& topic,
214  Options opts = {}) {
215  internal::OptionsSpan span(
216  internal::MergeOptions(std::move(opts), options_));
217  return connection_->ListTopicSubscriptions({topic.FullName()});
218  }
219 
220  /**
221  * Lists all the subscription names for a given topic.
222  *
223  * @note
224  * The returned range contains fully qualified snapshot names, e.g.,
225  * `"projects/my-project/snapshots/my-subscription"`. Applications may
226  * need to parse these names to use with other APIs.
227  *
228  * @par Idempotency
229  * This is a read-only operation and therefore always idempotent and retried.
230  *
231  * @par Example
232  * @snippet samples.cc list-topic-snapshots
233  *
234  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
235  * description of Cloud Pub/Sub's snapshots.
236  */
237  ListTopicSnapshotsRange ListTopicSnapshots(Topic const& topic,
238  Options opts = {}) {
239  internal::OptionsSpan span(
240  internal::MergeOptions(std::move(opts), options_));
241  return connection_->ListTopicSnapshots({topic.FullName()});
242  }
243 
244  private:
245  std::shared_ptr<TopicAdminConnection> connection_;
246  Options options_;
247 };
248 
250 } // namespace pubsub
251 } // namespace cloud
252 } // namespace google
253 
254 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_ADMIN_CLIENT_H