Google Cloud Pub/Sub C++ Client  2.1.0
A C++ Client Library for Google Cloud Pub/Sub
subscription_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_SUBSCRIPTION_ADMIN_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIPTION_ADMIN_CLIENT_H
17 
18 #include "google/cloud/pubsub/snapshot_builder.h"
19 #include "google/cloud/pubsub/subscription_admin_connection.h"
20 #include "google/cloud/pubsub/subscription_builder.h"
21 #include "google/cloud/pubsub/version.h"
22 #include <chrono>
23 #include <memory>
24 #include <string>
25 
26 namespace google {
27 namespace cloud {
28 namespace pubsub {
30 
31 /**
32  * Performs subscription administrative operations in Cloud Pub/Sub.
33  *
34  * Applications use this class to perform subscription administrative operations
35  * on [Cloud Pub/Sub][pubsub-doc-link].
36  *
37  * @par Performance
38  * `SubscriptionAdminClient` objects are relatively cheap to create, copy, and
39  * move. However, each `SubscriptionAdminClient` object must be created with a
40  * `std::shared_ptr<SubscriptionAdminConnection>`, which itself is relatively
41  * expensive to create. Therefore, connection instances should be shared when
42  * possible. See the `MakeSubscriptionAdminConnection()` function and the
43  * `SubscriptionAdminConnection` interface for more details.
44  *
45  * @par Thread Safety
46  * Instances of this class created via copy-construction or copy-assignment
47  * share the underlying pool of connections. Access to these copies via multiple
48  * threads is guaranteed to work. Two threads operating on the same instance of
49  * this class is not guaranteed to work.
50  *
51  * @par Error Handling
52  * This class uses `StatusOr<T>` to report errors. When an operation fails to
53  * perform its work the returned `StatusOr<T>` contains the error details. If
54  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
55  * contains the expected result. Please consult the [`StatusOr<T>`
56  * documentation](#google::cloud::StatusOr) for more details.
57  *
58  * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs
59  */
61  public:
63  std::shared_ptr<SubscriptionAdminConnection> connection,
64  Options opts = {});
65 
66  /**
67  * The default constructor is deleted.
68  *
69  * Use `SubscriberClient(std::shared_ptr<SubscriberConnection>)`
70  */
72 
73  /**
74  * Creates a new subscription in Cloud Pub/Sub.
75  *
76  * @par Idempotency
77  * This operation is idempotent, the state of the system is the same after one
78  * or several calls, and therefore it is always retried. It might return a
79  * status code of `kAlreadyExists` as a consequence of retrying a successful
80  * (but reported as failed) request.
81  *
82  * @par Example: Create a Pull Subscription
83  * @snippet samples.cc create-subscription
84  *
85  * @par Example: Create a Push Subscription
86  * @snippet samples.cc create-push-subscription
87  *
88  * @par Example: Create a BigQuery Subscription
89  * @snippet samples.cc create-bigquery-subscription
90  *
91  * @param topic the topic that the subscription will attach to
92  * @param subscription the name for the subscription
93  * @param builder any additional configuration for the subscription
94  * @param opts Override the class-level options, such as retry and backoff
95  * policies.
96  */
97  StatusOr<google::pubsub::v1::Subscription> CreateSubscription(
98  Topic const& topic, Subscription const& subscription,
99  SubscriptionBuilder builder = {}, Options opts = {}) {
100  internal::OptionsSpan span(
101  internal::MergeOptions(std::move(opts), options_));
102  return connection_->CreateSubscription(
103  {std::move(builder).BuildCreateRequest(topic, subscription)});
104  }
105 
106  /**
107  * Gets the metadata for an existing Cloud Pub/Sub subscription.
108  *
109  * @par Idempotency
110  * This is a read-only operation and therefore always idempotent and retried.
111  *
112  * @par Example
113  * @snippet samples.cc get-subscription
114  */
115  StatusOr<google::pubsub::v1::Subscription> GetSubscription(
116  Subscription subscription, Options opts = {}) {
117  internal::OptionsSpan span(
118  internal::MergeOptions(std::move(opts), options_));
119  return connection_->GetSubscription({std::move(subscription)});
120  }
121 
122  /**
123  * Updates an existing subscription in Cloud Pub/Sub.
124  *
125  * @par Idempotency
126  * This operation is idempotent, the state of the system is the same after one
127  * or several calls, and therefore it is always retried.
128  *
129  * @par Example
130  * @snippet samples.cc update-subscription
131  *
132  * @param subscription the name for the subscription
133  * @param builder any additional configuration for the subscription
134  * @param opts Override the class-level options, such as retry and backoff
135  * policies.
136  */
137  StatusOr<google::pubsub::v1::Subscription> UpdateSubscription(
138  Subscription const& subscription, SubscriptionBuilder builder,
139  Options opts = {}) {
140  internal::OptionsSpan span(
141  internal::MergeOptions(std::move(opts), options_));
142  return connection_->UpdateSubscription(
143  {std::move(builder).BuildUpdateRequest(subscription)});
144  }
145 
146  /**
147  * Lists all the subscriptions for a given project id.
148  *
149  * @par Idempotency
150  * This is a read-only operation and therefore always idempotent and retried.
151  *
152  * @par Example
153  * @snippet samples.cc list-subscriptions
154  */
155  ListSubscriptionsRange ListSubscriptions(std::string const& project_id,
156  Options opts = {}) {
157  internal::OptionsSpan span(
158  internal::MergeOptions(std::move(opts), options_));
159  return connection_->ListSubscriptions({"projects/" + project_id});
160  }
161 
162  /**
163  * Deletes an existing subscription in Cloud Pub/Sub.
164  *
165  * @par Idempotency
166  * This operation is idempotent, the state of the system is the same after one
167  * or several calls, and therefore it is always retried. It might return a
168  * status code of `kNotFound` as a consequence of retrying a successful
169  * (but reported as failed) request.
170  *
171  * @par Example
172  * @snippet samples.cc delete-subscription
173  *
174  * @param subscription the name of the subscription to be deleted.
175  * @param opts Override the class-level options, such as retry and backoff
176  * policies.
177  */
179  internal::OptionsSpan span(
180  internal::MergeOptions(std::move(opts), options_));
181  return connection_->DeleteSubscription({std::move(subscription)});
182  }
183 
184  /**
185  * Modifies an existing subscription's push configuration.
186  *
187  * This can change a push subscription into a pull subscription (by setting
188  * an empty push config), change the push endpoint, or change a pull
189  * subscription into a push config.
190  *
191  * @par Idempotency
192  * This operation is idempotent, the state of the system is the same after one
193  * or several calls, and therefore it is always retried.
194  *
195  * @par Example
196  * @snippet samples.cc modify-push-config
197  *
198  * @param subscription the name of the subscription to be modified.
199  * @param builder a description of the changes to be made.
200  * @param opts Override the class-level options, such as retry and backoff
201  * policies.
202  */
204  PushConfigBuilder builder, Options opts = {}) {
205  internal::OptionsSpan span(
206  internal::MergeOptions(std::move(opts), options_));
207  return connection_->ModifyPushConfig(
208  {std::move(builder).BuildModifyPushConfig(subscription)});
209  }
210 
211  /**
212  * Creates a new snapshot for a subscription with a server-assigned name.
213  *
214  * @par Idempotency
215  * This is not an idempotent operation, repeated calls would create multiple
216  * snapshots with different names assigned by the service, and therefore
217  * it is never retried.
218  *
219  * @param subscription the name of the subscription
220  * @param builder additional configuration for the snapshot, e.g., labels
221  * @param opts Override the class-level options, such as retry and backoff
222  * policies.
223  */
224  // TODO(#4792) - add missing example once it is testable
225  StatusOr<google::pubsub::v1::Snapshot> CreateSnapshot(
226  Subscription const& subscription, SnapshotBuilder builder = {},
227  Options opts = {}) {
228  internal::OptionsSpan span(
229  internal::MergeOptions(std::move(opts), options_));
230  return connection_->CreateSnapshot(
231  {std::move(builder).BuildCreateRequest(subscription)});
232  }
233 
234  /**
235  * Creates a new snapshot for a subscription with a given name.
236  *
237  * @par Idempotency
238  * This operation is idempotent, the state of the system is the same after one
239  * or several calls, and therefore it is always retried.
240  *
241  * @par Example
242  * @snippet samples.cc create-snapshot-with-name
243  *
244  * @param subscription the name of the subscription
245  * @param snapshot the name of the snapshot
246  * @param builder additional configuration for the snapshot, e.g., labels
247  * @param opts Override the class-level options, such as retry and backoff
248  * policies.
249  *
250  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
251  * description of Cloud Pub/Sub's snapshots.
252  */
253  StatusOr<google::pubsub::v1::Snapshot> CreateSnapshot(
254  Subscription const& subscription, Snapshot const& snapshot,
255  SnapshotBuilder builder = {}, Options opts = {}) {
256  internal::OptionsSpan span(
257  internal::MergeOptions(std::move(opts), options_));
258  return connection_->CreateSnapshot(
259  {std::move(builder).BuildCreateRequest(subscription, snapshot)});
260  }
261 
262  /**
263  * Gets information about an existing snapshot.
264  *
265  * @par Idempotency
266  * This is a read-only operation and therefore always idempotent and retried.
267  *
268  * @par Example
269  * @snippet samples.cc get-snapshot
270  *
271  * @param snapshot the name of the snapshot
272  * @param opts Override the class-level options, such as retry and backoff
273  * policies.
274  *
275  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
276  * description of Cloud Pub/Sub's snapshots.
277  */
278  StatusOr<google::pubsub::v1::Snapshot> GetSnapshot(Snapshot const& snapshot,
279  Options opts = {}) {
280  internal::OptionsSpan span(
281  internal::MergeOptions(std::move(opts), options_));
282  return connection_->GetSnapshot({snapshot});
283  }
284 
285  /**
286  * Updates an existing snapshot.
287  *
288  * @par Idempotency
289  * This operation is idempotent, the state of the system is the same after one
290  * or several calls, and therefore it is always retried.
291  *
292  * @par Example
293  * @snippet samples.cc update-snapshot
294  *
295  * @param snapshot the name of the snapshot
296  * @param builder the changes applied to the snapshot
297  * @param opts Override the class-level options, such as retry and backoff
298  * policies.
299  *
300  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
301  * description of Cloud Pub/Sub's snapshots.
302  */
303  StatusOr<google::pubsub::v1::Snapshot> UpdateSnapshot(
304  Snapshot const& snapshot, SnapshotBuilder builder, Options opts = {}) {
305  internal::OptionsSpan span(
306  internal::MergeOptions(std::move(opts), options_));
307  return connection_->UpdateSnapshot(
308  {std::move(builder).BuildUpdateRequest(snapshot)});
309  }
310 
311  /**
312  * Lists all the snapshots for a given project id.
313  *
314  * @par Idempotency
315  * This is a read-only operation and therefore always idempotent and retried.
316  *
317  * @par Example
318  * @snippet samples.cc list-snapshots
319  *
320  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
321  * description of Cloud Pub/Sub's snapshots.
322  */
323  ListSnapshotsRange ListSnapshots(std::string const& project_id,
324  Options opts = {}) {
325  internal::OptionsSpan span(
326  internal::MergeOptions(std::move(opts), options_));
327  return connection_->ListSnapshots({"projects/" + project_id});
328  }
329 
330  /**
331  * Deletes a snapshot.
332  *
333  * @par Idempotency
334  * This operation is idempotent, the state of the system is the same after one
335  * or several calls, and therefore it is always retried.
336  *
337  * @par Example
338  * @snippet samples.cc create-snapshot-with-name
339  *
340  * @param snapshot the name of the snapshot
341  * @param opts Override the class-level options, such as retry and backoff
342  * policies.
343  *
344  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
345  * description of Cloud Pub/Sub's snapshots.
346  */
347  Status DeleteSnapshot(Snapshot const& snapshot, Options opts = {}) {
348  internal::OptionsSpan span(
349  internal::MergeOptions(std::move(opts), options_));
350  return connection_->DeleteSnapshot({snapshot});
351  }
352 
353  /**
354  * Seeks a subscription to its state at @p timestamp.
355  *
356  * Messages retained in the subscription that were published before
357  * @p timestamp are marked as acknowledged, while messages published after
358  * @p timestamp are marked as unacknowledged.
359  *
360  * @par Idempotency
361  * This operation is idempotent, the state of the system is the same after one
362  * or several calls, and therefore it is always retried.
363  *
364  * @par Example
365  * @snippet samples.cc seek-with-timestamp
366  *
367  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
368  * description of Cloud Pub/Sub's `Seek()` functionality.
369  */
370  StatusOr<google::pubsub::v1::SeekResponse> Seek(
371  Subscription const& subscription,
372  std::chrono::system_clock::time_point timestamp, Options opts = {});
373 
374  /**
375  * Seeks a subscription to its state at @p snapshot.
376  *
377  * @par Idempotency
378  * This operation is idempotent, the state of the system is the same after one
379  * or several calls, and therefore it is always retried.
380  *
381  * @par Example
382  * @snippet samples.cc seek-with-timestamp
383  *
384  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
385  * description of Cloud Pub/Sub's `Seek()` functionality.
386  */
387  StatusOr<google::pubsub::v1::SeekResponse> Seek(
388  Subscription const& subscription, Snapshot const& snapshot,
389  Options opts = {});
390 
391  private:
392  std::shared_ptr<SubscriptionAdminConnection> connection_;
393  Options options_;
394 };
395 
397 } // namespace pubsub
398 } // namespace cloud
399 } // namespace google
400 
401 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIPTION_ADMIN_CLIENT_H