Google Cloud Bigtable C++ Client  1.42.0
A C++ Client Library for Google Cloud Bigtable
data_client.h
Go to the documentation of this file.
1 // Copyright 2017 Google Inc.
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_BIGTABLE_DATA_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CLIENT_H
17 
18 #include "google/cloud/bigtable/client_options.h"
19 #include "google/cloud/bigtable/completion_queue.h"
20 #include "google/cloud/bigtable/row.h"
21 #include "google/cloud/bigtable/version.h"
22 #include <google/bigtable/v2/bigtable.grpc.pb.h>
23 #include <string>
24 
25 namespace google {
26 namespace cloud {
27 // Forward declare some classes so we can be friends.
28 namespace bigtable_internal {
30 class LegacyAsyncRowReader;
31 class LegacyRowReader;
33 } // namespace bigtable_internal
34 namespace bigtable {
36 class Table;
37 namespace internal {
38 class AsyncRetryBulkApply;
39 class LegacyAsyncRowSampler;
40 class BulkMutator;
41 class LoggingDataClient;
42 } // namespace internal
43 
44 /**
45  * Connects to Cloud Bigtable's data manipulation APIs.
46  *
47  * This class is used by the Cloud Bigtable wrappers to access Cloud Bigtable.
48  * Multiple `bigtable::Table` objects may share a connection via a single
49  * `DataClient` object. The `DataClient` object is configured at construction
50  * time, this configuration includes the credentials, access endpoints, default
51  * timeouts, and other gRPC configuration options. This is an interface class
52  * because it is also used as a dependency injection point in some of the tests.
53  *
54  * @par Cost
55  * Applications should avoid unnecessarily creating new objects of type
56  * `DataClient`. Creating a new object of this type typically requires
57  * connecting to the Cloud Bigtable servers, and performing the authentication
58  * workflows with Google Cloud Platform. These operations can take many
59  * milliseconds, therefore applications should try to reuse the same
60  * `DataClient` instances when possible.
61  */
62 class DataClient {
63  public:
64  virtual ~DataClient() = default;
65 
66  virtual std::string const& project_id() const = 0;
67  virtual std::string const& instance_id() const = 0;
68 
69  /**
70  * Return a new channel to handle admin operations.
71  *
72  * Intended to access rarely used services in the same endpoints as the
73  * Bigtable admin interfaces, for example, the google.longrunning.Operations.
74  *
75  * @deprecated This member function is scheduled for deletion and `DataClient`
76  * will be marked as `final`. Do not extend this class. Application
77  * developers that need to configure the gRPC Channel can pass any of the
78  * following options into `MakeDataClient(...)`:
79  * * `google::cloud::GrpcChannelArgumentsOption`
80  * * `google::cloud::GrpcChannelArgumentsNativeOption`
81  */
83  virtual std::shared_ptr<grpc::Channel> Channel() = 0;
84 
85  /**
86  * Reset and create new Channels.
87  *
88  * @deprecated This member function is scheduled for deletion and `DataClient`
89  * will be marked as `final`. Do not extend this class. The client library
90  * will handle all interactions with the gRPC channels.
91  */
93  virtual void reset() = 0;
94 
95  /**
96  * The thread factory this client was created with.
97  *
98  * @deprecated This member function is scheduled for deletion and `DataClient`
99  * will be marked as `final`. Do not extend this class. Application
100  * developers that need to configure the background threads can pass any
101  * of the following options into `MakeDataClient(...)`:
102  * * `google::cloud::GrpcBackgroundThreadPoolSizeOption`
103  * * `google::cloud::GrpcCompletionQueueOption`
104  * * `google::cloud::GrpcBackgroundThreadFactoryOption`
105  */
106  virtual google::cloud::BackgroundThreadsFactory
108 
109  // The member functions of this class are not intended for general use by
110  // application developers (they are simply a dependency injection point). Make
111  // them protected, so the mock classes can override them, and then make the
112  // classes that do use them friends.
113  protected:
114  friend class Table;
115  friend class internal::AsyncRetryBulkApply;
116  friend class internal::LegacyAsyncRowSampler;
117  friend class internal::BulkMutator;
118  friend class bigtable_internal::LegacyRowReader;
119  friend class bigtable_internal::LegacyAsyncRowReader;
120  friend class internal::LoggingDataClient;
121 
122  //@{
123  /// @name the `google.bigtable.v2.Bigtable` wrappers.
124  virtual grpc::Status MutateRow(
125  grpc::ClientContext* context,
126  google::bigtable::v2::MutateRowRequest const& request,
127  google::bigtable::v2::MutateRowResponse* response) = 0;
128  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
129  google::bigtable::v2::MutateRowResponse>>
130  AsyncMutateRow(grpc::ClientContext* context,
131  google::bigtable::v2::MutateRowRequest const& request,
132  grpc::CompletionQueue* cq) = 0;
133  virtual grpc::Status CheckAndMutateRow(
134  grpc::ClientContext* context,
135  google::bigtable::v2::CheckAndMutateRowRequest const& request,
136  google::bigtable::v2::CheckAndMutateRowResponse* response) = 0;
137  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
138  google::bigtable::v2::CheckAndMutateRowResponse>>
140  grpc::ClientContext* context,
141  google::bigtable::v2::CheckAndMutateRowRequest const& request,
142  grpc::CompletionQueue* cq) = 0;
143  virtual grpc::Status ReadModifyWriteRow(
144  grpc::ClientContext* context,
145  google::bigtable::v2::ReadModifyWriteRowRequest const& request,
146  google::bigtable::v2::ReadModifyWriteRowResponse* response) = 0;
147  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
148  google::bigtable::v2::ReadModifyWriteRowResponse>>
150  grpc::ClientContext* context,
151  google::bigtable::v2::ReadModifyWriteRowRequest const& request,
152  grpc::CompletionQueue* cq) = 0;
153  virtual std::unique_ptr<
154  grpc::ClientReaderInterface<google::bigtable::v2::ReadRowsResponse>>
155  ReadRows(grpc::ClientContext* context,
156  google::bigtable::v2::ReadRowsRequest const& request) = 0;
157  virtual std::unique_ptr<
158  grpc::ClientAsyncReaderInterface<google::bigtable::v2::ReadRowsResponse>>
159  AsyncReadRows(grpc::ClientContext* context,
160  google::bigtable::v2::ReadRowsRequest const& request,
161  grpc::CompletionQueue* cq, void* tag) = 0;
162  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
163  google::bigtable::v2::ReadRowsResponse>>
164  PrepareAsyncReadRows(::grpc::ClientContext* context,
165  google::bigtable::v2::ReadRowsRequest const& request,
166  grpc::CompletionQueue* cq) = 0;
167  virtual std::unique_ptr<
168  grpc::ClientReaderInterface<google::bigtable::v2::SampleRowKeysResponse>>
169  SampleRowKeys(grpc::ClientContext* context,
170  google::bigtable::v2::SampleRowKeysRequest const& request) = 0;
171  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
172  google::bigtable::v2::SampleRowKeysResponse>>
173  AsyncSampleRowKeys(grpc::ClientContext* context,
174  google::bigtable::v2::SampleRowKeysRequest const& request,
175  grpc::CompletionQueue* cq, void* tag) = 0;
176  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
177  google::bigtable::v2::SampleRowKeysResponse>>
179  grpc::ClientContext* context,
180  google::bigtable::v2::SampleRowKeysRequest const& request,
181  grpc::CompletionQueue* cq);
182  virtual std::unique_ptr<
183  grpc::ClientReaderInterface<google::bigtable::v2::MutateRowsResponse>>
184  MutateRows(grpc::ClientContext* context,
185  google::bigtable::v2::MutateRowsRequest const& request) = 0;
186  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
187  google::bigtable::v2::MutateRowsResponse>>
188  AsyncMutateRows(::grpc::ClientContext* context,
189  google::bigtable::v2::MutateRowsRequest const& request,
190  grpc::CompletionQueue* cq, void* tag) = 0;
191  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
192  google::bigtable::v2::MutateRowsResponse>>
193  PrepareAsyncMutateRows(grpc::ClientContext* context,
194  google::bigtable::v2::MutateRowsRequest const& request,
195  grpc::CompletionQueue* cq) = 0;
196  //@}
197 };
198 
199 /// Create a new data client configured via @p options.
200 std::shared_ptr<DataClient> MakeDataClient(std::string project_id,
201  std::string instance_id,
202  Options options = {});
203 
204 /**
205  * Create a new data client configured via @p options.
206  *
207  * @deprecated use the `MakeDataClient` method which accepts
208  * `google::cloud::Options` instead.
209  */
210 GOOGLE_CLOUD_CPP_DEPRECATED("use `MakeDataClient` instead")
211 std::shared_ptr<DataClient> CreateDefaultDataClient(std::string project_id,
212  std::string instance_id,
213  ClientOptions options);
214 
215 /**
216  * Return the fully qualified instance name for the @p client.
217  *
218  * Compute the full path of the instance associated with the client, i.e.,
219  * `projects/instances/<client->project_id()>/instances/<client->instance_id()>`
220  */
221 inline std::string InstanceName(std::shared_ptr<DataClient> const& client) {
222  return "projects/" + client->project_id() + "/instances/" +
223  client->instance_id();
224 }
225 
227 } // namespace bigtable
228 } // namespace cloud
229 } // namespace google
230 
231 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CLIENT_H