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