Google Cloud Pub/Sub C++ Client  1.32.1
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 // 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_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/non_constructible.h"
21 #include "google/cloud/pubsub/internal/schema_stub.h"
22 #include "google/cloud/pubsub/retry_policy.h"
23 #include "google/cloud/pubsub/version.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 {
33 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
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 
94 /**
95  * Creates a new `SchemaAdminConnection` object to work with
96  * `SchemaAdminClient`.
97  *
98  * @note This function exists solely for backwards compatibility. It prevents
99  * existing code that calls `MakeSchemaAdminConnection({})` from breaking,
100  * due to ambiguity.
101  *
102  * @deprecated Please use `MakeSchemaAdminConnection()` instead.
103  */
105  std::initializer_list<pubsub_internal::NonConstructible>);
106 
107 /**
108  * Creates a new `SchemaAdminConnection` object to work with
109  * `SchemaAdminClient`.
110  *
111  * The `SchemaAdminConnection` class is provided for applications wanting to
112  * mock the `SchemaAdminClient` behavior in their tests. It is not intended for
113  * direct use.
114  *
115  * @par Performance
116  * Creating a new `SchemaAdminConnection` is relatively expensive. This
117  * typically initiates connections to the service, and therefore these objects
118  * should be shared and reused when possible. Note that gRPC reuses existing OS
119  * resources (sockets) whenever possible, so applications may experience better
120  * performance on the second (and subsequent) calls to this function with the
121  * same `Options` from `GrpcOptionList` and `CommonOptionList`. However, this
122  * behavior is not guaranteed and applications should not rely on it.
123  *
124  * @see `SchemaAdminClient`
125  *
126  * @param opts The options to use for this call. Expected options are any of
127  * the types in the following option lists.
128  * - `google::cloud::CommonOptionList`
129  * - `google::cloud::GrpcOptionList`
130  * - `google::cloud::pubsub::PolicyOptionList`
131  */
133  Options opts = {});
134 
135 /**
136  * Creates a new `SchemaAdminConnection` object to work with
137  * `SchemaAdminClient`.
138  *
139  * The `SchemaAdminConnection` class is provided for applications wanting to
140  * mock the `SchemaAdminClient` behavior in their tests. It is not intended for
141  * direct use.
142  *
143  * @par Performance
144  * Creating a new `SchemaAdminConnection` is relatively expensive. This
145  * typically initiate connections to the service, and therefore these objects
146  * should be shared and reused when possible. Note that gRPC reuses existing OS
147  * resources (sockets) whenever possible, so applications may experience better
148  * performance on the second (and subsequent) calls to this function with the
149  * same `ConnectionOptions` parameters. However, this behavior is not guaranteed
150  * and applications should not rely on it.
151  *
152  * @see `SchemaAdminClient`
153  *
154  * @param options (optional) configure the `PublisherConnection` created by
155  * this function.
156  * @param retry_policy control for how long (or how many times) are retryable
157  * RPCs attempted.
158  * @param backoff_policy controls the backoff behavior between retry attempts,
159  * typically some form of exponential backoff with jitter.
160  *
161  * @deprecated Please use the `MakeSchemaAdminConnection` function that accepts
162  * `google::cloud::Options` instead.
163  */
165  pubsub::ConnectionOptions const& options,
166  std::unique_ptr<pubsub::RetryPolicy const> retry_policy = {},
167  std::unique_ptr<pubsub::BackoffPolicy const> backoff_policy = {});
168 
169 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
170 } // namespace pubsub
171 
172 namespace pubsub_internal {
173 inline namespace GOOGLE_CLOUD_CPP_PUBSUB_NS {
174 
175 std::shared_ptr<pubsub::SchemaAdminConnection> MakeSchemaAdminConnection(
176  Options const& opts, std::shared_ptr<SchemaStub> stub);
177 
178 } // namespace GOOGLE_CLOUD_CPP_PUBSUB_NS
179 } // namespace pubsub_internal
180 } // namespace cloud
181 } // namespace google
182 
183 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SCHEMA_ADMIN_CONNECTION_H