// Copyright 2022 Google LLC

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

// https://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CONNECTION_H

#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CONNECTION_H

#include "google/cloud/bigtable/filters.h"

#include "google/cloud/bigtable/internal/bigtable_stub.h"

#include "google/cloud/bigtable/mutation_branch.h"

#include "google/cloud/bigtable/mutations.h"

#include "google/cloud/bigtable/prepared_query.h"

#include "google/cloud/bigtable/result_source_interface.h"

#include "google/cloud/bigtable/row.h"

#include "google/cloud/bigtable/row_key_sample.h"

#include "google/cloud/bigtable/row_reader.h"

#include "google/cloud/bigtable/row_set.h"

#include "google/cloud/bigtable/row_stream.h"

#include "google/cloud/bigtable/sql_statement.h"

#include "google/cloud/backoff_policy.h"

#include "google/cloud/options.h"

#include "google/cloud/status_or.h"

#include "google/cloud/stream_range.h"

#include "google/cloud/version.h"

#include <memory>

namespace google {

namespace cloud {

namespace bigtable_internal {

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

std::vector<bigtable::FailedMutation> MakeFailedMutations(Status const& status,

std::size_t n);

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END

} // namespace bigtable_internal

namespace bigtable {

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

/// Wrap the arguments to `ReadRows()`.

struct ReadRowsParams {

std::string table_name;

std::string app_profile_id;

RowSet row_set;

std::int64_t rows_limit;

Filter filter = Filter::PassAllFilter();

bool reverse = false;

};

struct PrepareQueryParams {

bigtable::InstanceResource instance;

bigtable::SqlStatement sql_statement;

};

struct ExecuteQueryParams {

bigtable::BoundQuery bound_query;

};

/**

* A connection to the Cloud Bigtable Data API.

*

* This interface defines pure-virtual methods for each of the user-facing

* overload sets in `Table`. This allows users to inject custom behavior (e.g.,

* with a Google Mock object) in a `Table` object for use in their own tests.

*

* To create a concrete instance, see `MakeDataConnection()`.

*

* For mocking, see `bigtable_mocks::MockDataConnection`.

*

* @par Connection Pool

* This class opens a number of [gRPC Channels] upon its construction. These

* channels each initiate a connection to the Cloud Bigtable service. This is a

* relatively slow operation that can take milliseconds, so applications are

* advised to reuse `DataConnection` objects when possible.

*

* The exact number of channels can be configured with the

* `google::cloud::GrpcNumChannelsOption`. If this option is not set, the class

* creates between 1 and 64 channels. The specific algorithm and number of

* channels is an implementation detail, and subject to change without notice.

*

* Each request sent from the client library cycles through the channels in the

* connection pool in a round robin fashion.

*

* Unused gRPC channels can enter an idle state. Refreshing them during a

* request may incur additional latency. To avoid this, the client library keeps

* connections open by refreshing the channels in a background thread. Advanced

* users can configure the frequency of the refreshes, or disable this feature,

* by using `bigtable::MinConnectionRefreshOption` and

* `bigtable::MaxConnectionRefreshOption`.

*

* [gRPC Channels]: https://grpc.io/docs/what-is-grpc/core-concepts/#channels

*/

class DataConnection {

public:

virtual ~DataConnection() = 0;

virtual Options options() { return Options{}; }

virtual Status Apply(std::string const& table_name, SingleRowMutation mut);

virtual future<Status> AsyncApply(std::string const& table_name,

SingleRowMutation mut);

virtual std::vector<FailedMutation> BulkApply(std::string const& table_name,

BulkMutation mut);

virtual future<std::vector<FailedMutation>> AsyncBulkApply(

std::string const& table_name, BulkMutation mut);

/// Prefer to use `ReadRowsFull()` in mocks.

virtual RowReader ReadRows(std::string const& table_name, RowSet row_set,

std::int64_t rows_limit, Filter filter);

virtual RowReader ReadRowsFull(ReadRowsParams params);

virtual StatusOr<std::pair<bool, Row>> ReadRow(std::string const& table_name,

std::string row_key,

Filter filter);

virtual StatusOr<MutationBranch> CheckAndMutateRow(

std::string const& table_name, std::string row_key, Filter filter,

std::vector<Mutation> true_mutations,

std::vector<Mutation> false_mutations);

virtual future<StatusOr<MutationBranch>> AsyncCheckAndMutateRow(

std::string const& table_name, std::string row_key, Filter filter,

std::vector<Mutation> true_mutations,

std::vector<Mutation> false_mutations);

virtual StatusOr<std::vector<RowKeySample>> SampleRows(

std::string const& table_name);

virtual future<StatusOr<std::vector<RowKeySample>>> AsyncSampleRows(

std::string const& table_name);

virtual StatusOr<Row> ReadModifyWriteRow(

google::bigtable::v2::ReadModifyWriteRowRequest request);

virtual future<StatusOr<Row>> AsyncReadModifyWriteRow(

google::bigtable::v2::ReadModifyWriteRowRequest request);

virtual void AsyncReadRows(std::string const& table_name,

std::function<future<bool>(Row)> on_row,

std::function<void(Status)> on_finish,

RowSet row_set, std::int64_t rows_limit,

Filter filter);

virtual future<StatusOr<std::pair<bool, Row>>> AsyncReadRow(

std::string const& table_name, std::string row_key, Filter filter);

virtual StatusOr<bigtable::PreparedQuery> PrepareQuery(

bigtable::PrepareQueryParams const& p);

virtual future<StatusOr<bigtable::PreparedQuery>> AsyncPrepareQuery(

bigtable::PrepareQueryParams const& p);

virtual bigtable::RowStream ExecuteQuery(bigtable::ExecuteQueryParams p);

};

/**

* Returns a `DataConnection` object that can be used for interacting with

* the Cloud Bigtable Data API.

*

* The returned connection object should not be used directly; instead it

* should be given to a `Table` instance, and methods should be invoked on

* `Table`.

*

* The optional @p opts argument may be used to configure aspects of the

* returned `DataConnection`. Expected options are any of the following options

* or types in the option lists.

*

* - `google::cloud::CommonOptionList`

* - `google::cloud::GrpcOptionList`

* - `google::cloud::UnifiedCredentialsOptionList`

* - `google::cloud::bigtable::AppProfileIdOption`

* - `google::cloud::bigtable::DataPolicyOptionList`

*

* @note Unrecognized options will be ignored. To debug issues with options set

* `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and unexpected

* options will be logged.

*

* @param options (optional) Configure the `DataConnection` created by this

* function.

*/

std::shared_ptr<DataConnection> MakeDataConnection(Options options = {});

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END

} // namespace bigtable

} // namespace cloud

} // namespace google

#endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CONNECTION_H