Google Cloud Pub/Sub C++ Client  1.32.1
A C++ Client Library for Google Cloud Pub/Sub
topic_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_TOPIC_ADMIN_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_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/publisher_stub.h"
22 #include "google/cloud/pubsub/retry_policy.h"
23 #include "google/cloud/pubsub/subscription.h"
24 #include "google/cloud/pubsub/topic.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 <memory>
30 #include <string>
31 
32 namespace google {
33 namespace cloud {
34 namespace pubsub {
35 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
36 
37 /**
38  * An input range to stream Cloud Pub/Sub topics.
39  *
40  * This type models an [input range][cppref-input-range] of
41  * `google::pubsub::v1::Topic` objects. Applications can make a
42  * single pass through the results.
43  *
44  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
45  */
46 using ListTopicsRange =
47  google::cloud::internal::PaginationRange<google::pubsub::v1::Topic>;
48 
49 /**
50  * An input range to stream the Cloud Pub/Sub subscriptions of a topic.
51  *
52  * This type models an [input range][cppref-input-range] of
53  * `std::string` objects. Applications can make a
54  * single pass through the results.
55  *
56  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
57  */
58 using ListTopicSubscriptionsRange =
59  google::cloud::internal::PaginationRange<std::string>;
60 
61 /**
62  * An input range to stream the Cloud Pub/Sub snapshots of a topic.
63  *
64  * This type models an [input range][cppref-input-range] of
65  * `std::string` objects. Applications can make a
66  * single pass through the results.
67  *
68  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
69  */
70 using ListTopicSnapshotsRange =
71  google::cloud::internal::PaginationRange<std::string>;
72 
73 /**
74  * A connection to Cloud Pub/Sub for topic-related administrative operations.
75  *
76  * This interface defines pure-virtual functions for each of the user-facing
77  * overload sets in `TopicAdminClient`. That is, all of `TopicAdminClient`'s
78  * overloads will forward to the one pure-virtual function declared in this
79  * interface. This allows users to inject custom behavior (e.g., with a Google
80  * Mock object) in a `TopicAdminClient` object for use in their own tests.
81  *
82  * To create a concrete instance that connects you to the real Cloud Pub/Sub
83  * service, see `MakeTopicAdminConnection()`.
84  *
85  * @par The *Params nested classes
86  * Applications may define classes derived from `TopicAdminConnection`, for
87  * example, because they want to mock the class. To avoid breaking all such
88  * derived classes when we change the number or type of the arguments to the
89  * member functions we define lightweight structures to pass the arguments.
90  */
92  public:
93  virtual ~TopicAdminConnection() = 0;
94 
95  /// Wrap the arguments for `CreateTopic()`
97  google::pubsub::v1::Topic topic;
98  };
99 
100  /// Wrap the arguments for `GetTopic()`
101  struct GetTopicParams {
103  };
104 
105  /// Wrap the arguments for `UpdateTopic()`
107  google::pubsub::v1::UpdateTopicRequest request;
108  };
109 
110  /// Wrap the arguments for `ListTopics()`
112  std::string project_id;
113  };
114 
115  /// Wrap the arguments for `DeleteTopic()`
118  };
119 
120  /// Wrap the arguments for `DetachSubscription()`
123  };
124 
125  /// Wrap the arguments for `ListTopicSubscriptions()`
127  std::string topic_full_name;
128  };
129 
130  /// Wrap the arguments for `ListTopicSnapshots()`
132  std::string topic_full_name;
133  };
134 
135  /// Defines the interface for `TopicAdminClient::CreateTopic()`
136  virtual StatusOr<google::pubsub::v1::Topic> CreateTopic(CreateTopicParams);
137 
138  /// Defines the interface for `TopicAdminClient::GetTopic()`
139  virtual StatusOr<google::pubsub::v1::Topic> GetTopic(GetTopicParams);
140 
141  /// Defines the interface for `TopicAdminClient::UpdateTopic()`
142  virtual StatusOr<google::pubsub::v1::Topic> UpdateTopic(UpdateTopicParams);
143 
144  /// Defines the interface for `TopicAdminClient::ListTopics()`
145  virtual ListTopicsRange ListTopics(ListTopicsParams);
146 
147  /// Defines the interface for `TopicAdminClient::DeleteTopic()`
149 
150  /// Defines the interface for `TopicAdminClient::DetachSubscriptions()`
151  virtual StatusOr<google::pubsub::v1::DetachSubscriptionResponse>
153 
154  /// Defines the interface for `TopicAdminClient::ListTopicSubscriptions()`
155  virtual ListTopicSubscriptionsRange ListTopicSubscriptions(
157 
158  /// Defines the interface for `TopicAdminClient::ListTopicSnapshots()`
159  virtual ListTopicSnapshotsRange ListTopicSnapshots(ListTopicSnapshotsParams);
160 };
161 
162 /**
163  * Creates a new `TopicAdminConnection` object to work with `TopicAdminClient`.
164  *
165  * @note This function exists solely for backwards compatibility. It prevents
166  * existing code that calls `MakeTopicAdminConnection({})` from breaking,
167  * due to ambiguity.
168  *
169  * @deprecated Please use `MakeTopicAdminConnection()` instead.
170  */
172  std::initializer_list<pubsub_internal::NonConstructible>);
173 
174 /**
175  * Creates a new `TopicAdminConnection` object to work with `TopicAdminClient`.
176  *
177  * The `TopicAdminConnection` class is provided for applications wanting to mock
178  * the `TopicAdminClient` behavior in their tests. It is not intended for direct
179  * use.
180  *
181  * @par Performance
182  * Creating a new `TopicAdminConnection` is relatively expensive. This typically
183  * initiates connections to the service, and therefore these objects should be
184  * shared and reused when possible. Note that gRPC reuses existing OS resources
185  * (sockets) whenever possible, so applications may experience better
186  * performance on the second (and subsequent) calls to this function with the
187  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
188  * behavior is not guaranteed and applications should not rely on it.
189  *
190  * @see `TopicAdminClient`
191  *
192  * @param opts The options to use for this call. Expected options are any
193  * of the types in the following option lists.
194  * - `google::cloud::CommonOptionList`
195  * - `google::cloud::GrpcOptionList`
196  * - `google::cloud::pubsub::PolicyOptionList`
197  */
199  Options opts = {});
200 
201 /**
202  * Creates a new `TopicAdminConnection` object to work with `TopicAdminClient`.
203  *
204  * The `TopicAdminConnection` class is provided for applications wanting to mock
205  * the `TopicAdminClient` behavior in their tests. It is not intended for direct
206  * use.
207  *
208  * @par Performance
209  * Creating a new `TopicAdminConnection` is relatively expensive. This typically
210  * initiate connections to the service, and therefore these objects should be
211  * shared and reused when possible. Note that gRPC reuses existing OS resources
212  * (sockets) whenever possible, so applications may experience better
213  * performance on the second (and subsequent) calls to this function with the
214  * same `ConnectionOptions` parameters. However, this behavior is not guaranteed
215  * and applications should not rely on it.
216  *
217  * @see `TopicAdminClient`
218  *
219  * @param options (optional) configure the `TopicAdminConnection` created by
220  * this function.
221  * @param retry_policy control for how long (or how many times) are retryable
222  * RPCs attempted.
223  * @param backoff_policy controls the backoff behavior between retry attempts,
224  * typically some form of exponential backoff with jitter.
225  *
226  * @deprecated Please use the `MakeTopicAdminConnection` function that accepts
227  * `google::cloud::Options` instead.
228  */
230  ConnectionOptions const& options,
231  std::unique_ptr<pubsub::RetryPolicy const> retry_policy = {},
232  std::unique_ptr<pubsub::BackoffPolicy const> backoff_policy = {});
233 
234 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
235 } // namespace pubsub
236 
237 namespace pubsub_internal {
238 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
239 
240 std::shared_ptr<pubsub::TopicAdminConnection> MakeTopicAdminConnection(
241  Options const& opts, std::shared_ptr<PublisherStub> stub);
242 
243 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
244 } // namespace pubsub_internal
245 } // namespace cloud
246 } // namespace google
247 
248 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_TOPIC_ADMIN_CONNECTION_H