Google Cloud Pub/Sub C++ Client  1.32.1
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 // 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_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 {
29 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
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
56  * [`StatusOr<T>` documentation](#google::cloud::v1::StatusOr) for more details.
57  *
58  * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs
59  */
61  public:
62  explicit SubscriptionAdminClient(
63  std::shared_ptr<SubscriptionAdminConnection> connection);
64 
65  /**
66  * The default constructor is deleted.
67  *
68  * Use `SubscriberClient(std::shared_ptr<SubscriberConnection>)`
69  */
71 
72  /**
73  * Creates a new subscription in Cloud Pub/Sub.
74  *
75  * @par Idempotency
76  * This operation is idempotent, the state of the system is the same after one
77  * or several calls, and therefore it is always retried. It might return a
78  * status code of `kAlreadyExists` as a consequence of retrying a successful
79  * (but reported as failed) request.
80  *
81  * @par Example: Create a Pull Subscription
82  * @snippet samples.cc create-subscription
83  *
84  * @par Example: Create a Push Subscription
85  * @snippet samples.cc create-push-subscription
86  *
87  * @param topic the topic that the subscription will attach to
88  * @param subscription the name for the subscription
89  * @param builder any additional configuration for the subscription
90  */
91  StatusOr<google::pubsub::v1::Subscription> CreateSubscription(
92  Topic const& topic, Subscription const& subscription,
93  SubscriptionBuilder builder = {}) {
94  return connection_->CreateSubscription(
95  {std::move(builder).BuildCreateRequest(topic, subscription)});
96  }
97 
98  /**
99  * Gets the metadata for an existing Cloud Pub/Sub subscription.
100  *
101  * @par Idempotency
102  * This is a read-only operation and therefore always idempotent and retried.
103  *
104  * @par Example
105  * @snippet samples.cc get-subscription
106  */
107  StatusOr<google::pubsub::v1::Subscription> GetSubscription(
108  Subscription subscription) {
109  return connection_->GetSubscription({std::move(subscription)});
110  }
111 
112  /**
113  * Updates an existing subscription in Cloud Pub/Sub.
114  *
115  * @par Idempotency
116  * This operation is idempotent, the state of the system is the same after one
117  * or several calls, and therefore it is always retried.
118  *
119  * @par Example
120  * @snippet samples.cc update-subscription
121  *
122  * @param subscription the name for the subscription
123  * @param builder any additional configuration for the subscription
124  */
125  StatusOr<google::pubsub::v1::Subscription> UpdateSubscription(
126  Subscription const& subscription, SubscriptionBuilder builder) {
127  return connection_->UpdateSubscription(
128  {std::move(builder).BuildUpdateRequest(subscription)});
129  }
130 
131  /**
132  * Lists all the subscriptions for a given project id.
133  *
134  * @par Idempotency
135  * This is a read-only operation and therefore always idempotent and retried.
136  *
137  * @par Example
138  * @snippet samples.cc list-subscriptions
139  */
140  ListSubscriptionsRange ListSubscriptions(std::string const& project_id) {
141  return connection_->ListSubscriptions({"projects/" + project_id});
142  }
143 
144  /**
145  * Deletes an existing subscription in Cloud Pub/Sub.
146  *
147  * @par Idempotency
148  * This operation is idempotent, the state of the system is the same after one
149  * or several calls, and therefore it is always retried. It might return a
150  * status code of `kNotFound` as a consequence of retrying a successful
151  * (but reported as failed) request.
152  *
153  * @par Example
154  * @snippet samples.cc delete-subscription
155  *
156  * @param subscription the name of the subscription to be deleted.
157  */
159  return connection_->DeleteSubscription({std::move(subscription)});
160  }
161 
162  /**
163  * Modifies an existing subscription's push configuration.
164  *
165  * This can change a push subscription into a pull subscription (by setting
166  * an empty push config), change the push endpoint, or change a pull
167  * subscription into a push config.
168  *
169  * @par Idempotency
170  * This operation is idempotent, the state of the system is the same after one
171  * or several calls, and therefore it is always retried.
172  *
173  * @par Example
174  * @snippet samples.cc modify-push-config
175  *
176  * @param subscription the name of the subscription to be modified.
177  * @param builder a description of the changes to be made.
178  */
180  PushConfigBuilder builder) {
181  return connection_->ModifyPushConfig(
182  {std::move(builder).BuildModifyPushConfig(subscription)});
183  }
184 
185  /**
186  * Creates a new snapshot for a subscription with a server-assigned name.
187  *
188  * @par Idempotency
189  * This is not an idempotent operation, repeated calls would create multiple
190  * snapshots with different names assigned by the service, and therefore
191  * it is never retried.
192  *
193  * @param subscription the name of the subscription
194  * @param builder additional configuration for the snapshot, e.g., labels
195  */
196  // TODO(#4792) - add missing example once it is testable
197  StatusOr<google::pubsub::v1::Snapshot> CreateSnapshot(
198  Subscription const& subscription, SnapshotBuilder builder = {}) {
199  return connection_->CreateSnapshot(
200  {std::move(builder).BuildCreateRequest(subscription)});
201  }
202 
203  /**
204  * Creates a new snapshot for a subscription with a given name.
205  *
206  * @par Idempotency
207  * This operation is idempotent, the state of the system is the same after one
208  * or several calls, and therefore it is always retried.
209  *
210  * @par Example
211  * @snippet samples.cc create-snapshot-with-name
212  *
213  * @param subscription the name of the subscription
214  * @param snapshot the name of the snapshot
215  * @param builder additional configuration for the snapshot, e.g., labels
216  *
217  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
218  * description of Cloud Pub/Sub's snapshots.
219  */
220  StatusOr<google::pubsub::v1::Snapshot> CreateSnapshot(
221  Subscription const& subscription, Snapshot const& snapshot,
222  SnapshotBuilder builder = {}) {
223  return connection_->CreateSnapshot(
224  {std::move(builder).BuildCreateRequest(subscription, snapshot)});
225  }
226 
227  /**
228  * Gets information about an existing snapshot.
229  *
230  * @par Idempotency
231  * This is a read-only operation and therefore always idempotent and retried.
232  *
233  * @par Example
234  * @snippet samples.cc get-snapshot
235  *
236  * @param snapshot the name of the snapshot
237  *
238  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
239  * description of Cloud Pub/Sub's snapshots.
240  */
241  StatusOr<google::pubsub::v1::Snapshot> GetSnapshot(Snapshot const& snapshot) {
242  return connection_->GetSnapshot({snapshot});
243  }
244 
245  /**
246  * Updates an existing snapshot.
247  *
248  * @par Idempotency
249  * This operation is idempotent, the state of the system is the same after one
250  * or several calls, and therefore it is always retried.
251  *
252  * @par Example
253  * @snippet samples.cc update-snapshot
254  *
255  * @param snapshot the name of the snapshot
256  * @param builder the changes applied to the snapshot
257  *
258  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
259  * description of Cloud Pub/Sub's snapshots.
260  */
261  StatusOr<google::pubsub::v1::Snapshot> UpdateSnapshot(
262  Snapshot const& snapshot, SnapshotBuilder builder) {
263  return connection_->UpdateSnapshot(
264  {std::move(builder).BuildUpdateRequest(snapshot)});
265  }
266 
267  /**
268  * Lists all the snapshots for a given project id.
269  *
270  * @par Idempotency
271  * This is a read-only operation and therefore always idempotent and retried.
272  *
273  * @par Example
274  * @snippet samples.cc list-snapshots
275  *
276  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
277  * description of Cloud Pub/Sub's snapshots.
278  */
279  ListSnapshotsRange ListSnapshots(std::string const& project_id) {
280  return connection_->ListSnapshots({"projects/" + project_id});
281  }
282 
283  /**
284  * Deletes a snapshot.
285  *
286  * @par Idempotency
287  * This operation is idempotent, the state of the system is the same after one
288  * or several calls, and therefore it is always retried.
289  *
290  * @par Example
291  * @snippet samples.cc create-snapshot-with-name
292  *
293  * @param snapshot the name of the snapshot
294  *
295  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
296  * description of Cloud Pub/Sub's snapshots.
297  */
298  Status DeleteSnapshot(Snapshot const& snapshot) {
299  return connection_->DeleteSnapshot({snapshot});
300  }
301 
302  /**
303  * Seeks a subscription to its state at @p timestamp.
304  *
305  * Messages retained in the subscription that were published before
306  * @p timestamp are marked as acknowledged, while messages published after
307  * @p timestamp are marked as unacknowledged.
308  *
309  * @par Idempotency
310  * This operation is idempotent, the state of the system is the same after one
311  * or several calls, and therefore it is always retried.
312  *
313  * @par Example
314  * @snippet samples.cc seek-with-timestamp
315  *
316  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
317  * description of Cloud Pub/Sub's `Seek()` functionality.
318  */
319  StatusOr<google::pubsub::v1::SeekResponse> Seek(
320  Subscription const& subscription,
321  std::chrono::system_clock::time_point timestamp);
322 
323  /**
324  * Seeks a subscription to its state at @p snapshot.
325  *
326  * @par Idempotency
327  * This operation is idempotent, the state of the system is the same after one
328  * or several calls, and therefore it is always retried.
329  *
330  * @par Example
331  * @snippet samples.cc seek-with-timestamp
332  *
333  * @see https://cloud.google.com/pubsub/docs/replay-overview for a detailed
334  * description of Cloud Pub/Sub's `Seek()` functionality.
335  */
336  StatusOr<google::pubsub::v1::SeekResponse> Seek(
337  Subscription const& subscription, Snapshot const& snapshot);
338 
339  private:
340  std::shared_ptr<SubscriptionAdminConnection> connection_;
341 };
342 
343 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
344 } // namespace pubsub
345 } // namespace cloud
346 } // namespace google
347 
348 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIPTION_ADMIN_CLIENT_H