Google Cloud Bigtable C++ Client  1.35.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 namespace bigtable {
29 // Forward declare some classes so we can be friends.
30 class Table;
31 namespace internal {
32 class AsyncRetryBulkApply;
33 class AsyncRowSampler;
34 class BulkMutator;
35 class LoggingDataClient;
36 } // namespace internal
37 
38 /**
39  * Connects to Cloud Bigtable's data manipulation APIs.
40  *
41  * This class is used by the Cloud Bigtable wrappers to access Cloud Bigtable.
42  * Multiple `bigtable::Table` objects may share a connection via a single
43  * `DataClient` object. The `DataClient` object is configured at construction
44  * time, this configuration includes the credentials, access endpoints, default
45  * timeouts, and other gRPC configuration options. This is an interface class
46  * because it is also used as a dependency injection point in some of the tests.
47  *
48  * @par Cost
49  * Applications should avoid unnecessarily creating new objects of type
50  * `DataClient`. Creating a new object of this type typically requires
51  * connecting to the Cloud Bigtable servers, and performing the authentication
52  * workflows with Google Cloud Platform. These operations can take many
53  * milliseconds, therefore applications should try to reuse the same
54  * `DataClient` instances when possible.
55  */
56 class DataClient {
57  public:
58  virtual ~DataClient() = default;
59 
60  virtual std::string const& project_id() const = 0;
61  virtual std::string const& instance_id() const = 0;
62 
63  /**
64  * Return a new channel to handle admin operations.
65  *
66  * Intended to access rarely used services in the same endpoints as the
67  * Bigtable admin interfaces, for example, the google.longrunning.Operations.
68  */
69  virtual std::shared_ptr<grpc::Channel> Channel() = 0;
70 
71  /**
72  * Reset and create new Channels.
73  *
74  * Currently this is only used in testing. In the future, we expect this,
75  * or a similar member function, will be needed to handle errors that require
76  * a new connection, or an explicit refresh of the credentials.
77  */
78  virtual void reset() = 0;
79 
80  /**
81  * The thread factory this client was created with.
82  */
83  virtual google::cloud::BackgroundThreadsFactory
85 
86  // The member functions of this class are not intended for general use by
87  // application developers (they are simply a dependency injection point). Make
88  // them protected, so the mock classes can override them, and then make the
89  // classes that do use them friends.
90  protected:
91  friend class Table;
92  friend class internal::AsyncRetryBulkApply;
93  friend class internal::AsyncRowSampler;
94  friend class internal::BulkMutator;
95  friend class RowReader;
96  template <typename RowFunctor, typename FinishFunctor>
97  friend class AsyncRowReader;
98  friend class internal::LoggingDataClient;
99 
100  //@{
101  /// @name the `google.bigtable.v2.Bigtable` wrappers.
102  virtual grpc::Status MutateRow(
103  grpc::ClientContext* context,
104  google::bigtable::v2::MutateRowRequest const& request,
105  google::bigtable::v2::MutateRowResponse* response) = 0;
106  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
107  google::bigtable::v2::MutateRowResponse>>
108  AsyncMutateRow(grpc::ClientContext* context,
109  google::bigtable::v2::MutateRowRequest const& request,
110  grpc::CompletionQueue* cq) = 0;
111  virtual grpc::Status CheckAndMutateRow(
112  grpc::ClientContext* context,
113  google::bigtable::v2::CheckAndMutateRowRequest const& request,
114  google::bigtable::v2::CheckAndMutateRowResponse* response) = 0;
115  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
116  google::bigtable::v2::CheckAndMutateRowResponse>>
118  grpc::ClientContext* context,
119  google::bigtable::v2::CheckAndMutateRowRequest const& request,
120  grpc::CompletionQueue* cq) = 0;
121  virtual grpc::Status ReadModifyWriteRow(
122  grpc::ClientContext* context,
123  google::bigtable::v2::ReadModifyWriteRowRequest const& request,
124  google::bigtable::v2::ReadModifyWriteRowResponse* response) = 0;
125  virtual std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<
126  google::bigtable::v2::ReadModifyWriteRowResponse>>
128  grpc::ClientContext* context,
129  google::bigtable::v2::ReadModifyWriteRowRequest const& request,
130  grpc::CompletionQueue* cq) = 0;
131  virtual std::unique_ptr<
132  grpc::ClientReaderInterface<google::bigtable::v2::ReadRowsResponse>>
133  ReadRows(grpc::ClientContext* context,
134  google::bigtable::v2::ReadRowsRequest const& request) = 0;
135  virtual std::unique_ptr<
136  grpc::ClientAsyncReaderInterface<google::bigtable::v2::ReadRowsResponse>>
137  AsyncReadRows(grpc::ClientContext* context,
138  google::bigtable::v2::ReadRowsRequest const& request,
139  grpc::CompletionQueue* cq, void* tag) = 0;
140  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
141  google::bigtable::v2::ReadRowsResponse>>
142  PrepareAsyncReadRows(::grpc::ClientContext* context,
143  google::bigtable::v2::ReadRowsRequest const& request,
144  grpc::CompletionQueue* cq) = 0;
145  virtual std::unique_ptr<
146  grpc::ClientReaderInterface<google::bigtable::v2::SampleRowKeysResponse>>
147  SampleRowKeys(grpc::ClientContext* context,
148  google::bigtable::v2::SampleRowKeysRequest const& request) = 0;
149  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
150  google::bigtable::v2::SampleRowKeysResponse>>
151  AsyncSampleRowKeys(grpc::ClientContext* context,
152  google::bigtable::v2::SampleRowKeysRequest const& request,
153  grpc::CompletionQueue* cq, void* tag) = 0;
154  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
155  google::bigtable::v2::SampleRowKeysResponse>>
157  grpc::ClientContext* context,
158  google::bigtable::v2::SampleRowKeysRequest const& request,
159  grpc::CompletionQueue* cq);
160  virtual std::unique_ptr<
161  grpc::ClientReaderInterface<google::bigtable::v2::MutateRowsResponse>>
162  MutateRows(grpc::ClientContext* context,
163  google::bigtable::v2::MutateRowsRequest const& request) = 0;
164  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
165  google::bigtable::v2::MutateRowsResponse>>
166  AsyncMutateRows(::grpc::ClientContext* context,
167  google::bigtable::v2::MutateRowsRequest const& request,
168  grpc::CompletionQueue* cq, void* tag) = 0;
169  virtual std::unique_ptr<::grpc::ClientAsyncReaderInterface<
170  google::bigtable::v2::MutateRowsResponse>>
171  PrepareAsyncMutateRows(grpc::ClientContext* context,
172  google::bigtable::v2::MutateRowsRequest const& request,
173  grpc::CompletionQueue* cq) = 0;
174  //@}
175 };
176 
177 /// Create a new data client configured via @p options.
178 std::shared_ptr<DataClient> MakeDataClient(std::string project_id,
179  std::string instance_id,
180  Options options = {});
181 
182 /**
183  * Create a new data client configured via @p options.
184  *
185  * @deprecated use the `MakeDataClient` method which accepts
186  * `google::cloud::Options` instead.
187  */
188 std::shared_ptr<DataClient> CreateDefaultDataClient(std::string project_id,
189  std::string instance_id,
190  ClientOptions options);
191 
192 /**
193  * Return the fully qualified instance name for the @p client.
194  *
195  * Compute the full path of the instance associated with the client, i.e.,
196  * `projects/instances/<client->project_id()>/instances/<client->instance_id()>`
197  */
198 inline std::string InstanceName(std::shared_ptr<DataClient> const& client) {
199  return "projects/" + client->project_id() + "/instances/" +
200  client->instance_id();
201 }
202 
204 } // namespace bigtable
205 } // namespace cloud
206 } // namespace google
207 
208 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CLIENT_H