Google Cloud Pub/Sub C++ Client  2.1.0
A C++ Client Library for Google Cloud Pub/Sub
schema_admin_client.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_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SCHEMA_ADMIN_CLIENT_H
17 
18 #include "google/cloud/pubsub/schema.h"
19 #include "google/cloud/pubsub/schema_admin_connection.h"
20 #include "google/cloud/pubsub/version.h"
21 #include <memory>
22 #include <string>
23 
24 namespace google {
25 namespace cloud {
26 namespace pubsub {
28 
29 /**
30  * Performs schema admin operations in Cloud Pub/Sub.
31  *
32  * Applications use this class to perform operations on
33  * [Cloud Pub/Sub][pubsub-doc-link].
34  *
35  * @warning The Cloud Pub/Sub schema API and the C++ client library for the
36  * Cloud Pub/Sub schema APIs are experimental. They are subject to change,
37  * including complete removal, without notice.
38  *
39  * @par Performance
40  * `SchemaAdminClient` objects are cheap to create, copy, and move. However,
41  * each `SchemaAdminClient` object must be created with a
42  * `std::shared_ptr<SchemaAdminConnection>`, which itself is relatively
43  * expensive to create. Therefore, connection instances should be shared when
44  * possible. See the `MakeSchemaAdminConnection()` function and the
45  * `SchemaAdminConnection` interface for more details.
46  *
47  * @par Thread Safety
48  * Instances of this class created via copy-construction or copy-assignment
49  * share the underlying pool of connections. Access to these copies via multiple
50  * threads is guaranteed to work. Two threads operating on the same instance of
51  * this class is not guaranteed to work.
52  *
53  * @par Error Handling
54  * This class uses `StatusOr<T>` to report errors. When an operation fails to
55  * perform its work the returned `StatusOr<T>` contains the error details. If
56  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
57  * contains the expected result. Please consult the [`StatusOr<T>`
58  * documentation](#google::cloud::StatusOr) for more details.
59  *
60  * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs
61  */
63  public:
64  explicit SchemaAdminClient(std::shared_ptr<SchemaAdminConnection> connection,
65  Options opts = {});
66 
67  /**
68  * The default constructor is deleted.
69  *
70  * Use `PublisherClient(std::shared_ptr<PublisherConnection>)`
71  */
72  SchemaAdminClient() = delete;
73 
74  /**
75  * @copydoc CreateSchema(google::pubsub::v1::CreateSchemaRequest const&,Options)
76  *
77  * @par Example
78  * @snippet samples.cc create-avro-schema
79  */
80  StatusOr<google::pubsub::v1::Schema> CreateAvroSchema(
81  Schema const& schema, std::string schema_definition, Options opts = {});
82 
83  /**
84  * @copydoc CreateSchema(google::pubsub::v1::CreateSchemaRequest const&,Options)
85  *
86  * @par Example
87  * @snippet samples.cc create-protobuf-schema
88  */
89  StatusOr<google::pubsub::v1::Schema> CreateProtobufSchema(
90  Schema const& schema, std::string schema_definition, Options opts = {});
91 
92  /**
93  * Creates a new Cloud Pub/Sub schema.
94  *
95  * @par Idempotency
96  * This operation is idempotent, as it succeeds only once, therefore the
97  * library retries the call. It might return a status code of`kAlreadyExists`
98  * as a consequence of retrying a successful (but reported as failed) request.
99  */
100  StatusOr<google::pubsub::v1::Schema> CreateSchema(
101  google::pubsub::v1::CreateSchemaRequest const& request,
102  Options opts = {});
103 
104  /**
105  * Gets information about an existing Cloud Pub/Sub schema.
106  *
107  * @par Idempotency
108  * This is a read-only operation and therefore always idempotent and retried.
109  *
110  * @par Example
111  * @snippet samples.cc get-schema
112  *
113  * @param schema the full name of the schema
114  * @param view Use `BASIC` to include the name and type of the schema, but not
115  * the definition. Use `FULL` to include the definition.
116  * @param opts Override the class-level options, such as retry and backoff
117  * policies.
118  */
119  StatusOr<google::pubsub::v1::Schema> GetSchema(
120  Schema const& schema,
121  google::pubsub::v1::SchemaView view = google::pubsub::v1::BASIC,
122  Options opts = {});
123 
124  /**
125  * Lists all the schemas for a given project id.
126  *
127  * @par Idempotency
128  * This is a read-only operation and therefore always idempotent and retried.
129  *
130  * @par Example
131  * @snippet samples.cc list-schemas
132  *
133  * @param project_id lists the schemas in this project
134  * @param view Use `BASIC` to include the name and type of each schema, but
135  * not the definition. Use `FULL` to include the definition.
136  * @param opts Override the class-level options, such as retry and backoff
137  * policies.
138  */
139  ListSchemasRange ListSchemas(
140  std::string const& project_id,
141  google::pubsub::v1::SchemaView view = google::pubsub::v1::BASIC,
142  Options opts = {});
143 
144  /**
145  * Deletes an existing schema 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-schema
155  *
156  * @param schema the name of the schema to be deleted.
157  * @param opts Override the class-level options, such as retry and backoff
158  * policies.
159  */
160  Status DeleteSchema(Schema const& schema, Options opts = {});
161 
162  /**
163  * Validates a schema definition.
164  *
165  * @par Idempotency
166  * This is a read-only operation and therefore always idempotent and retried.
167  *
168  * @par Example
169  * @snippet samples.cc validate-avro-schema
170  */
171  StatusOr<google::pubsub::v1::ValidateSchemaResponse> ValidateAvroSchema(
172  std::string const& project_id, std::string schema_definition,
173  Options opts = {});
174 
175  /**
176  * Validates a schema definition.
177  *
178  * @par Idempotency
179  * This is a read-only operation and therefore always idempotent and retried.
180  *
181  * @par Example
182  * @snippet samples.cc validate-protobuf-schema
183  */
184  StatusOr<google::pubsub::v1::ValidateSchemaResponse> ValidateProtobufSchema(
185  std::string const& project_id, std::string schema_definition,
186  Options opts = {});
187 
188  /**
189  * Validates a schema definition.
190  *
191  * @par Idempotency
192  * This is a read-only operation and therefore always idempotent and retried.
193  */
194  StatusOr<google::pubsub::v1::ValidateSchemaResponse> ValidateSchema(
195  std::string const& project_id, google::pubsub::v1::Schema schema,
196  Options opts = {});
197 
198  /**
199  * @copydoc ValidateMessage(google::pubsub::v1::ValidateMessageRequest const&,Options)
200  *
201  * @par Example
202  * @snippet samples.cc validate-message-named-schema
203  *
204  * @param encoding the message encoding, note that some schemas may not
205  * support some encodings.
206  * @param message the message to validate
207  * @param named_schema the name of an existing schema to validate against
208  * @param opts Override the class-level options, such as retry and backoff
209  * policies.
210  */
211  StatusOr<google::pubsub::v1::ValidateMessageResponse>
212  ValidateMessageWithNamedSchema(google::pubsub::v1::Encoding encoding,
213  std::string message,
214  Schema const& named_schema, Options opts = {});
215 
216  /**
217  * @copydoc ValidateMessage(google::pubsub::v1::ValidateMessageRequest const&,Options)
218  *
219  * @par Example
220  * @snippet samples.cc validate-message-avro
221  *
222  * @param encoding the message encoding, note that some schemas may not
223  * support some encodings.
224  * @param message the message to validate
225  * @param project_id the project used to perform the validation
226  * @param schema_definition the schema definition, in AVRO format
227  * @param opts Override the class-level options, such as retry and backoff
228  * policies.
229  */
230  StatusOr<google::pubsub::v1::ValidateMessageResponse> ValidateMessageWithAvro(
231  google::pubsub::v1::Encoding encoding, std::string message,
232  std::string project_id, std::string schema_definition, Options opts = {});
233 
234  /**
235  * @copydoc ValidateMessage(google::pubsub::v1::ValidateMessageRequest const&,Options)
236  *
237  * @par Example
238  * @snippet samples.cc validate-message-protobuf
239  *
240  * @param encoding the message encoding, note that some schemas may not
241  * support some encodings.
242  * @param message the message to validate
243  * @param project_id the project used to perform the validation
244  * @param schema_definition the schema definition, in protocol buffers format
245  * @param opts Override the class-level options, such as retry and backoff
246  * policies.
247  */
248  StatusOr<google::pubsub::v1::ValidateMessageResponse>
249  ValidateMessageWithProtobuf(google::pubsub::v1::Encoding encoding,
250  std::string message, std::string project_id,
251  std::string schema_definition, Options opts = {});
252 
253  /**
254  * Validates a message against a schema.
255  *
256  * @par Idempotency
257  * This is a read-only operation and therefore always idempotent and retried.
258  */
259  StatusOr<google::pubsub::v1::ValidateMessageResponse> ValidateMessage(
260  google::pubsub::v1::ValidateMessageRequest const& request,
261  Options opts = {});
262 
263  private:
264  std::shared_ptr<SchemaAdminConnection> connection_;
265  Options options_;
266 };
267 
269 } // namespace pubsub
270 } // namespace cloud
271 } // namespace google
272 
273 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_SCHEMA_ADMIN_CLIENT_H