Google Cloud Pub/Sub C++ Client  1.32.1
A C++ Client Library for Google Cloud Pub/Sub
subscription_admin_connection.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_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIPTION_ADMIN_CONNECTION_H
17 
18 #include "google/cloud/pubsub/backoff_policy.h"
19 #include "google/cloud/pubsub/connection_options.h"
20 #include "google/cloud/pubsub/internal/non_constructible.h"
21 #include "google/cloud/pubsub/internal/subscriber_stub.h"
22 #include "google/cloud/pubsub/retry_policy.h"
23 #include "google/cloud/pubsub/snapshot.h"
24 #include "google/cloud/pubsub/subscription.h"
25 #include "google/cloud/pubsub/version.h"
26 #include "google/cloud/internal/pagination_range.h"
27 #include "google/cloud/status_or.h"
28 #include <google/pubsub/v1/pubsub.pb.h>
29 #include <initializer_list>
30 #include <memory>
31 #include <string>
32 
33 namespace google {
34 namespace cloud {
35 namespace pubsub {
36 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
37 
38 /**
39  * An input range to stream Cloud Pub/Sub subscriptions.
40  *
41  * This type models an [input range][cppref-input-range] of
42  * `google::pubsub::v1::Subscription` objects. Applications can make a
43  * single pass through the results.
44  *
45  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
46  */
47 using ListSubscriptionsRange =
48  google::cloud::internal::PaginationRange<google::pubsub::v1::Subscription>;
49 
50 /**
51  * An input range to stream Cloud Pub/Sub snapshots.
52  *
53  * This type models an [input range][cppref-input-range] of
54  * `google::pubsub::v1::Snapshot` objects. Applications can make a
55  * single pass through the results.
56  *
57  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
58  */
59 using ListSnapshotsRange =
60  google::cloud::internal::PaginationRange<google::pubsub::v1::Snapshot>;
61 
62 /**
63  * A connection to Cloud Pub/Sub for subscription-related administrative
64  * operations.
65  *
66  * This interface defines pure-virtual functions for each of the user-facing
67  * overload sets in `SubscriptionAdminClient`. That is, all of
68  * `SubscriptionAdminClient` overloads will forward to the one pure-virtual
69  * function declared in this interface. This allows users to inject custom
70  * behavior (e.g., with a Google Mock object) in a `SubscriptionAdminClient`
71  * object for use in their own tests.
72  *
73  * To create a concrete instance that connects you to the real Cloud Pub/Sub
74  * service, see `MakeSubscriptionAdminConnection()`.
75  *
76  * @par The *Params nested classes
77  * Applications may define classes derived from `SubscriptionAdminConnection`,
78  * for example, because they want to mock the class. To avoid breaking all such
79  * derived classes when we change the number or type of the arguments to the
80  * member functions we define lightweight structures to pass the arguments.
81  */
83  public:
85 
86  /// Wrap the arguments for `CreateSubscription()`
88  google::pubsub::v1::Subscription subscription;
89  };
90 
91  /// Wrap the arguments for `GetSubscription()`
94  };
95 
96  /// Wrap the arguments for `UpdateSubscription()`
98  google::pubsub::v1::UpdateSubscriptionRequest request;
99  };
100 
101  /// Wrap the arguments for `ListSubscriptions()`
103  std::string project_id;
104  };
105 
106  /// Wrap the arguments for `DeleteSubscription()`
109  };
110 
111  /// Wrap the arguments for `ModifyPushConfig()`
113  google::pubsub::v1::ModifyPushConfigRequest request;
114  };
115 
116  /// Wrap the arguments for `CreateSnapshot()`
118  google::pubsub::v1::CreateSnapshotRequest request;
119  };
120 
121  /// Wrap the arguments for `GetSnapshot()`
124  };
125 
126  /// Wrap the arguments for `ListSnapshots()`
128  std::string project_id;
129  };
130 
131  /// Wrap the arguments for `UpdateSnapshot()`
133  google::pubsub::v1::UpdateSnapshotRequest request;
134  };
135 
136  /// Wrap the arguments for `DeleteSnapshot()`
139  };
140 
141  /// Wrap the arguments for `Seek()`
142  struct SeekParams {
143  google::pubsub::v1::SeekRequest request;
144  };
145 
146  /// Defines the interface for `SubscriptionAdminClient::CreateSubscription()`
147  virtual StatusOr<google::pubsub::v1::Subscription> CreateSubscription(
149 
150  /// Defines the interface for `SubscriptionAdminClient::GetSubscription()`
151  virtual StatusOr<google::pubsub::v1::Subscription> GetSubscription(
153 
154  /// Defines the interface for `SubscriptionAdminClient::UpdateSubscription()`
155  virtual StatusOr<google::pubsub::v1::Subscription> UpdateSubscription(
157 
158  /// Defines the interface for `SubscriptionAdminClient::ListSubscriptions()`
159  virtual ListSubscriptionsRange ListSubscriptions(ListSubscriptionsParams);
160 
161  /// Defines the interface for `SubscriptionAdminClient::DeleteSubscription()`
163 
164  /// Defines the interface for `SubscriptionAdminClient::ModifyPushConfig()`
166 
167  /// Defines the interface for `SnapshotAdminClient::CreateSnapshot()`
168  virtual StatusOr<google::pubsub::v1::Snapshot> CreateSnapshot(
170 
171  /// Defines the interface for `SnapshotAdminClient::GetSnapshot()`
172  virtual StatusOr<google::pubsub::v1::Snapshot> GetSnapshot(GetSnapshotParams);
173 
174  /// Defines the interface for `SnapshotAdminClient::UpdateSnapshot()`
175  virtual StatusOr<google::pubsub::v1::Snapshot> UpdateSnapshot(
177 
178  /// Defines the interface for `SubscriptionAdminClient::ListSnapshots()`
179  virtual ListSnapshotsRange ListSnapshots(ListSnapshotsParams);
180 
181  /// Defines the interface for `SnapshotAdminClient::DeleteSnapshot()`
183 
184  /// Defines the interface for `SubscriptionAdminClient::Seek()`
185  virtual StatusOr<google::pubsub::v1::SeekResponse> Seek(SeekParams);
186 };
187 
188 /**
189  * Creates a new `SubscriptionAdminConnection` object to work with
190  * `SubscriptionAdminClient`.
191  *
192  * @note This function exists solely for backwards compatibility. It prevents
193  * existing code that calls `MakeSubscriptionAdminConnection({})` from
194  * breaking, due to ambiguity.
195  *
196  * @deprecated Please use `MakeSubscriptionAdminConnection()` instead.
197  */
199  std::initializer_list<pubsub_internal::NonConstructible>);
200 
201 /**
202  * Creates a new `SubscriptionAdminConnection` object to work with
203  * `SubscriptionAdminClient`.
204  *
205  * The `SubscriptionAdminConnection` class is provided for applications wanting
206  * to mock the `SubscriptionAdminClient` behavior in their tests. It is not
207  * intended for direct use.
208  *
209  * @par Performance
210  * Creating a new `SubscriptionAdminConnection` is relatively expensive. This
211  * typically initiates connections to the service, and therefore these objects
212  * should be shared and reused when possible. Note that gRPC reuses existing OS
213  * resources (sockets) whenever possible, so applications may experience better
214  * performance on the second (and subsequent) calls to this function with the
215  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
216  * behavior is not guaranteed and applications should not rely on it.
217  *
218  * @see `SubscriptionAdminClient`
219  *
220  * @param opts The options to use for this call. Expected options are any of
221  * the types in the following option lists.
222  * - `google::cloud::CommonOptionList`
223  * - `google::cloud::GrpcOptionList`
224  * - `google::cloud::pubsub::PolicyOptionList`
225  */
227  Options opts = {});
228 
229 /**
230  * Creates a new `SubscriptionAdminConnection` object to work with
231  * `SubscriptionAdminClient`.
232  *
233  * The `SubscriptionAdminConnection` class is not intended for direct use in
234  * applications, it is provided for applications wanting to mock the
235  * `SubscriptionAdminClient` behavior in their tests.
236  *
237  * @par Performance
238  * Creating a new `SubscriptionAdminConnection` is relatively expensive. This
239  * typically initiates connections to the service, and therefore these objects
240  * should be shared and reused when possible. Note that gRPC reuses existing OS
241  * resources (sockets) whenever possible, so applications may experience better
242  * performance on the second (and subsequent) calls to this function with the
243  * same `ConnectionOptions` parameters. However, this behavior is not guaranteed
244  * and applications should not rely on it.
245  *
246  * @see `SubscriberConnection`
247  *
248  * @param options (optional) configure the `SubscriptionAdminConnection` created
249  * by this function.
250  * @param retry_policy control for how long (or how many times) are retryable
251  * RPCs attempted.
252  * @param backoff_policy controls the backoff behavior between retry attempts,
253  * typically some form of exponential backoff with jitter.
254  *
255  * @deprecated Please use the `MakeSubscriptionAdminConnection` function that
256  * accepts `google::cloud::Options` instead.
257  */
259  ConnectionOptions const& options,
260  std::unique_ptr<pubsub::RetryPolicy const> retry_policy = {},
261  std::unique_ptr<pubsub::BackoffPolicy const> backoff_policy = {});
262 
263 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
264 } // namespace pubsub
265 
266 namespace pubsub_internal {
267 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
268 
269 std::shared_ptr<pubsub::SubscriptionAdminConnection>
270 MakeSubscriptionAdminConnection(Options const& opts,
271  std::shared_ptr<SubscriberStub> stub);
272 
273 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
274 } // namespace pubsub_internal
275 } // namespace cloud
276 } // namespace google
277 
278 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SUBSCRIPTION_ADMIN_CONNECTION_H