Google Cloud Pub/Sub C++ Client  2.5.0
A C++ Client Library for Google Cloud Pub/Sub
schema_admin_connection.h
Go to the documentation of this file.
1 // Copyright 2021 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_SCHEMA_ADMIN_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SCHEMA_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/schema_stub.h"
21 #include "google/cloud/pubsub/retry_policy.h"
22 #include "google/cloud/pubsub/version.h"
23 #include "google/cloud/internal/non_constructible.h"
24 #include "google/cloud/internal/pagination_range.h"
25 #include "google/cloud/status_or.h"
26 #include <google/pubsub/v1/schema.pb.h>
27 #include <initializer_list>
28 #include <memory>
29 
30 namespace google {
31 namespace cloud {
32 namespace pubsub {
34 
35 /**
36  * An input range to stream Cloud Pub/Sub schemas.
37  *
38  * This type models an [input range][cppref-input-range] of
39  * `google::pubsub::v1::Schema` objects. Applications can make a
40  * single pass through the results.
41  *
42  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
43  */
44 using ListSchemasRange =
45  google::cloud::internal::PaginationRange<google::pubsub::v1::Schema>;
46 
47 /**
48  * A connection to Cloud Pub/Sub for schema-related administrative operations.
49  *
50  * This interface defines pure-virtual functions for each of the user-facing
51  * overload sets in `SchemaAdminClient`. That is, all of `SchemaAdminClient`'s
52  * overloads will forward to the one pure-virtual function declared in this
53  * interface. This allows users to inject custom behavior (e.g., with a Google
54  * Mock object) in a `SchemaAdminClient` object for use in their own tests.
55  *
56  * To create a concrete instance that connects you to the real Cloud Pub/Sub
57  * service, see `MakeSchemaAdminConnection()`.
58  *
59  * @par The *Params nested classes
60  * Applications may define classes derived from `SchemaAdminConnection`, for
61  * example, because they want to mock the class. To avoid breaking all such
62  * derived classes when we change the number or type of the arguments to the
63  * member functions we define lightweight structures to pass the arguments.
64  */
66  public:
67  virtual ~SchemaAdminConnection() = 0;
68 
69  /// Defines the interface for `SchemaAdminClient::CreateSchema()`
70  virtual StatusOr<google::pubsub::v1::Schema> CreateSchema(
71  google::pubsub::v1::CreateSchemaRequest const&) = 0;
72 
73  /// Defines the interface for `SchemaAdminClient::GetSchema()`
74  virtual StatusOr<google::pubsub::v1::Schema> GetSchema(
75  google::pubsub::v1::GetSchemaRequest const&) = 0;
76 
77  /// Defines the interface for `SchemaAdminClient::ListSchemas()`
78  virtual ListSchemasRange ListSchemas(
79  google::pubsub::v1::ListSchemasRequest const&) = 0;
80 
81  /// Defines the interface for `SchemaAdminClient::DeleteSchema()`
83  google::pubsub::v1::DeleteSchemaRequest const&) = 0;
84 
85  /// Defines the interface for `SchemaAdminClient::ValidateSchema()`
86  virtual StatusOr<google::pubsub::v1::ValidateSchemaResponse> ValidateSchema(
87  google::pubsub::v1::ValidateSchemaRequest const&) = 0;
88 
89  /// Defines the interface for `SchemaAdminClient::ValidateMessage()`
90  virtual StatusOr<google::pubsub::v1::ValidateMessageResponse> ValidateMessage(
91  google::pubsub::v1::ValidateMessageRequest const&) = 0;
92 
93  /// Return the options used to create the connection.
94  virtual Options options() const { return Options{}; }
95 };
96 
97 /**
98  * Creates a new `SchemaAdminConnection` object to work with
99  * `SchemaAdminClient`.
100  *
101  * @note This function exists solely for backwards compatibility. It prevents
102  * existing code that calls `MakeSchemaAdminConnection({})` from breaking,
103  * due to ambiguity.
104  *
105  * @deprecated Please use `MakeSchemaAdminConnection()` instead.
106  */
107 GOOGLE_CLOUD_CPP_DEPRECATED("use `MakeSchemaAdminConnection()` instead")
109  std::initializer_list<internal::NonConstructible>);
110 
111 /**
112  * Creates a new `SchemaAdminConnection` object to work with
113  * `SchemaAdminClient`.
114  *
115  * The `SchemaAdminConnection` class is provided for applications wanting to
116  * mock the `SchemaAdminClient` behavior in their tests. It is not intended for
117  * direct use.
118  *
119  * @par Performance
120  * Creating a new `SchemaAdminConnection` is relatively expensive. This
121  * typically initiates connections to the service, and therefore these objects
122  * should be shared and reused when possible. Note that gRPC reuses existing OS
123  * resources (sockets) whenever possible, so applications may experience better
124  * performance on the second (and subsequent) calls to this function with the
125  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
126  * behavior is not guaranteed and applications should not rely on it.
127  *
128  * @see `SchemaAdminClient`
129  *
130  * @param opts The options to use for this call. Expected options are any of
131  * the types in the following option lists.
132  * - `google::cloud::CommonOptionList`
133  * - `google::cloud::GrpcOptionList`
134  * - `google::cloud::pubsub::PolicyOptionList`
135  */
137  Options opts = {});
138 
139 /**
140  * Creates a new `SchemaAdminConnection` object to work with
141  * `SchemaAdminClient`.
142  *
143  * The `SchemaAdminConnection` class is provided for applications wanting to
144  * mock the `SchemaAdminClient` behavior in their tests. It is not intended for
145  * direct use.
146  *
147  * @par Performance
148  * Creating a new `SchemaAdminConnection` is relatively expensive. This
149  * typically initiate connections to the service, and therefore these objects
150  * should be shared and reused when possible. Note that gRPC reuses existing OS
151  * resources (sockets) whenever possible, so applications may experience better
152  * performance on the second (and subsequent) calls to this function with the
153  * identical values for @p options. However, this behavior is not guaranteed
154  * and applications should not rely on it.
155  *
156  * @see `SchemaAdminClient`
157  *
158  * @param options (optional) configure the `PublisherConnection` created by
159  * this function.
160  * @param retry_policy control for how long (or how many times) are retryable
161  * RPCs attempted.
162  * @param backoff_policy controls the backoff behavior between retry attempts,
163  * typically some form of exponential backoff with jitter.
164  *
165  * @deprecated Please use the `MakeSchemaAdminConnection` function that accepts
166  * `google::cloud::Options` instead.
167  */
168 GOOGLE_CLOUD_CPP_DEPRECATED(
169  "use the overload consuming google::cloud::Options instead")
171  pubsub::ConnectionOptions const& options,
172  std::unique_ptr<pubsub::RetryPolicy const> retry_policy = {},
173  std::unique_ptr<pubsub::BackoffPolicy const> backoff_policy = {});
174 
176 } // namespace pubsub
177 
178 namespace pubsub_internal {
180 
181 std::shared_ptr<pubsub::SchemaAdminConnection> MakeTestSchemaAdminConnection(
182  Options const& opts, std::shared_ptr<SchemaServiceStub> stub);
183 
185 } // namespace pubsub_internal
186 } // namespace cloud
187 } // namespace google
188 
189 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SCHEMA_ADMIN_CONNECTION_H