Google Cloud Spanner C++ Client  1.33.0
A C++ Client Library for Google Cloud Spanner
instance_admin_connection.h
Go to the documentation of this file.
1 // Copyright 2019 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_SPANNER_INSTANCE_ADMIN_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INSTANCE_ADMIN_CONNECTION_H
17 
18 #include "google/cloud/spanner/backoff_policy.h"
19 #include "google/cloud/spanner/internal/instance_admin_stub.h"
20 #include "google/cloud/spanner/polling_policy.h"
21 #include "google/cloud/spanner/retry_policy.h"
22 #include "google/cloud/spanner/version.h"
23 #include "google/cloud/backoff_policy.h"
24 #include "google/cloud/internal/pagination_range.h"
25 #include <google/spanner/admin/instance/v1/spanner_instance_admin.pb.h>
26 #include <map>
27 #include <string>
28 #include <vector>
29 
30 namespace google {
31 namespace cloud {
32 namespace spanner {
34 
35 /**
36  * An input range to stream all the instances in a Cloud project.
37  *
38  * This type models an [input range][cppref-input-range] of
39  * `google::spanner::admin::v1::Instance` 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 ListInstancesRange = ::google::cloud::internal::PaginationRange<
45  google::spanner::admin::instance::v1::Instance>;
46 
47 /**
48  * An input range to stream all the instance configs in a Cloud project.
49  *
50  * This type models an [input range][cppref-input-range] of
51  * `google::spanner::admin::v1::Instance` objects. Applications can make a
52  * single pass through the results.
53  *
54  * [cppref-input-range]: https://en.cppreference.com/w/cpp/ranges/input_range
55  */
56 using ListInstanceConfigsRange = ::google::cloud::internal::PaginationRange<
57  google::spanner::admin::instance::v1::InstanceConfig>;
58 
59 /**
60  * A connection to the Cloud Spanner instance administration service.
61  *
62  * This interface defines pure-virtual methods for each of the user-facing
63  * overload sets in `InstanceAdminClient`. This allows users to inject custom
64  * behavior (e.g., with a Google Mock object) in a `InstanceAdminClient` object
65  * for use in their own tests.
66  *
67  * To create a concrete instance that connects you to a real Cloud Spanner
68  * instance administration service, see `MakeInstanceAdminConnection()`.
69  */
70 class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("InstanceAdminConnection")
72  public:
73  virtual ~InstanceAdminConnection() = 0;
74 
75  //@{
76  /**
77  * @name Define the arguments for each member function.
78  *
79  * Applications may define classes derived from `InstanceAdminConnection`,
80  * for example, because they want to mock the class. To avoid breaking all
81  * such derived classes when we change the number or type of the arguments
82  * to the member functions we define light weight structures to pass the
83  * arguments.
84  */
85  /// Wrap the arguments for `GetInstance()`.
87  /// The full name of the instance in
88  /// `projects/<project-id>/instances/<instance-id>` format.
89  std::string instance_name;
90  };
91 
92  /// Wrap the arguments for `CreateInstance()`.
94  google::spanner::admin::instance::v1::CreateInstanceRequest request;
95  };
96 
97  /// Wrap the arguments for `UpdateInstance()`.
99  google::spanner::admin::instance::v1::UpdateInstanceRequest request;
100  };
101 
102  /// Wrap the arguments for `DeleteInstance()`.
104  std::string instance_name;
105  };
106 
107  /// Wrap the arguments for `GetInstanceConfig()`.
109  std::string instance_config_name;
110  };
111 
112  /// Wrap the arguments for `ListInstanceConfigs()`.
114  std::string project_id;
115  };
116 
117  /**
118  * Wrap the arguments for `ListInstances()`.
119  */
121  /**
122  * Query the instances in this project.
123  *
124  * This is a required value, it must be non-empty.
125  */
126  std::string project_id;
127 
128  /**
129  * A filtering expression to restrict the set of instances included in the
130  * response.
131  *
132  * @see The [RPC reference documentation][1] for the format of the filtering
133  * expression.
134  *
135  * [1]:
136  * https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.ListInstancesRequest
137  */
138  std::string filter;
139  };
140 
141  /// Wrap the arguments for `GetIamPolicy()`.
143  std::string instance_name;
144  };
145 
146  /// Wrap the arguments for `SetIamPolicy()`.
148  std::string instance_name;
149  google::iam::v1::Policy policy;
150  };
151 
152  /// Wrap the arguments for `TestIamPermissions()`.
154  std::string instance_name;
155  std::vector<std::string> permissions;
156  };
157  //@}
158 
159  /// Return the metadata for the given instance.
160  virtual StatusOr<google::spanner::admin::instance::v1::Instance> GetInstance(
161  GetInstanceParams) = 0;
162 
163  virtual future<StatusOr<google::spanner::admin::instance::v1::Instance>>
165 
166  virtual future<StatusOr<google::spanner::admin::instance::v1::Instance>>
168 
170 
171  /// Return the InstanceConfig with the given name.
172  virtual StatusOr<google::spanner::admin::instance::v1::InstanceConfig>
174 
175  /**
176  * Returns a one-pass input range with all the instance configs.
177  */
178  virtual ListInstanceConfigsRange ListInstanceConfigs(
180 
181  /**
182  * Returns a one-pass input range with all the instances meeting the
183  * requirements in @p params
184  */
185  virtual ListInstancesRange ListInstances(ListInstancesParams params) = 0;
186 
187  /// Define the interface for a
188  /// google.spanner.v1.DatabaseAdmin.GetIamPolicy RPC.
189  virtual StatusOr<google::iam::v1::Policy> GetIamPolicy(
190  GetIamPolicyParams) = 0;
191 
192  /// Define the interface for a
193  /// google.spanner.v1.DatabaseAdmin.SetIamPolicy RPC.
194  virtual StatusOr<google::iam::v1::Policy> SetIamPolicy(
195  SetIamPolicyParams) = 0;
196 
197  /// Define the interface for a
198  /// google.spanner.v1.DatabaseAdmin.TestIamPermissions RPC.
199  virtual StatusOr<google::iam::v1::TestIamPermissionsResponse>
201 };
202 
203 /**
204  * Returns an InstanceAdminConnection object that can be used for interacting
205  * with Cloud Spanner's admin APIs.
206  *
207  * The returned connection object should not be used directly; instead it
208  * should be given to a `InstanceAdminClient` instance.
209  *
210  * The optional @p opts argument may be used to configure aspects of the
211  * returned `InstanceAdminConnection`. Expected options are any of the types in
212  * the following option lists.
213  *
214  * - `google::cloud::CommonOptionList`
215  * - `google::cloud::GrpcOptionList`
216  * - `google::cloud::SpannerPolicyOptionList`
217  *
218  * @see `InstanceAdminConnection`
219  *
220  * @param opts (optional) configure the `InstanceAdminConnection` created by
221  * this function.
222  */
223 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
225  Options opts = {});
226 
227 /**
228  * Returns an InstanceAdminConnection object that can be used for interacting
229  * with Cloud Spanner's admin APIs.
230  *
231  * The returned connection object should not be used directly, rather it should
232  * be given to a `InstanceAdminClient` instance.
233  *
234  * @note Prefer using the `MakeInstanceAdminConnection()` overload that accepts
235  * `google::cloud::Options`.
236  *
237  * @see `InstanceAdminConnection`
238  *
239  * @param options configure the `InstanceAdminConnection` created by this
240  * function.
241  */
242 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
244  ConnectionOptions const& options);
245 
246 /**
247  * Returns an InstanceAdminConnection object that can be used for interacting
248  * with Cloud Spanner's admin APIs.
249  *
250  * The returned connection object should not be used directly, rather it should
251  * be given to a `InstanceAdminClient` instance.
252  *
253  * @note Prefer using the `MakeInstanceAdminConnection()` overload that accepts
254  * `google::cloud::Options`.
255  *
256  * @param options configure the `InstanceAdminConnection` created by this
257  * function.
258  * @param retry_policy control for how long (or how many times) are retryable
259  * RPCs attempted
260  * @param backoff_policy controls the backoff behavior between retry attempts,
261  * typically some form of exponential backoff with jitter
262  * @param polling_policy controls for how often, and how quickly, are long
263  * running checked for completion
264  *
265  * @par Example
266  * @snippet samples.cc custom-instance-admin-policies
267  */
268 GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
270  ConnectionOptions const& options, std::unique_ptr<RetryPolicy> retry_policy,
271  std::unique_ptr<BackoffPolicy> backoff_policy,
272  std::unique_ptr<PollingPolicy> polling_policy);
273 
275 } // namespace spanner
276 
277 namespace spanner_internal {
279 
280 /// Internal-only factory that allows us to inject mock stubs for testing.
281 std::shared_ptr<spanner::InstanceAdminConnection>
282 MakeInstanceAdminConnectionForTesting(
283  std::shared_ptr<InstanceAdminStub> base_stub, Options opts);
284 
286 } // namespace spanner_internal
287 
288 } // namespace cloud
289 } // namespace google
290 
291 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INSTANCE_ADMIN_CONNECTION_H