/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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
 *
 *     http://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.
 */

// This file contains protocol buffers that are used for Client service.

option java_package = "org.apache.hadoop.hbase.protobuf.generated";
option java_outer_classname = "ClientProtos";
option java_generic_services = true;
option java_generate_equals_and_hash = true;
option optimize_for = SPEED;

import "hbase.proto";
import "Comparator.proto";

/**
 * Container for a list of column qualifier names of a family.
 */
message Column {
  required bytes family = 1;
  repeated bytes qualifier = 2;
}

/**
 * The protocol buffer version of Get
 */
message Get {
  required bytes row = 1;
  repeated Column column = 2;
  repeated NameBytesPair attribute = 3;
  optional Filter filter = 4;
  optional TimeRange timeRange = 5;
  optional uint32 maxVersions = 6 [default = 1];
  optional bool cacheBlocks = 7 [default = true];
  optional uint32 storeLimit = 8;
  optional uint32 storeOffset = 9;
}

message Result {
  // Result includes the Cells or else it just has a count of Cells
  // that are carried otherwise.
  repeated Cell cell = 1;
  // The below count is set when the associated cells are
  // not part of this protobuf message; they are passed alongside
  // and then this Message is just a placeholder with metadata.
  // The count is needed to know how many to peel off the block of Cells as
  // ours.  NOTE: This is different from the pb managed cellCount of the
  // 'cell' field above which is non-null when the cells are pb'd.
  optional int32 associatedCellCount = 2;
}

/**
 * The get request. Perform a single Get operation.
 * Unless existenceOnly is specified, return all the requested data
 * for the row that matches exactly, or the one that immediately
 * precedes it if closestRowBefore is specified.
 *
 * If existenceOnly is set, only the existence will be returned.
 */
message GetRequest {
  required RegionSpecifier region = 1;
  required Get get = 2;

  // If the row to get doesn't exist, return the
  // closest row before.
  optional bool closestRowBefore = 3;

  // The result isn't asked for, just check for
  // the existence. If closestRowBefore specified,
  // this will be ignored
  optional bool existenceOnly = 4;
}

message MultiGetRequest {
  required RegionSpecifier region = 1;
  repeated Get get = 2;

  // If the row to get doesn't exist, return the
  // closest row before.
  optional bool closestRowBefore = 3;

  // The result isn't asked for, just check for
  // the existence. If closestRowBefore specified,
  // this will be ignored
  optional bool existenceOnly = 4;
}

message GetResponse {
  optional Result result = 1;

  // used for Get to check existence only
  optional bool exists = 2;
}

message MultiGetResponse {
  repeated Result result = 1;

  // used for Get to check existence only
  repeated bool exists = 2;
}

/**
 * Condition to check if the value of a given cell (row,
 * family, qualifier) matches a value via a given comparator.
 *
 * Condition is used in check and mutate operations.
 */
message Condition {
  required bytes row = 1;
  required bytes family = 2;
  required bytes qualifier = 3;
  required CompareType compareType = 4;
  required Comparator comparator = 5;
}


/**
 * A specific mutation inside a mutate request.
 * It can be an append, increment, put or delete based
 * on the mutation type.  It can be fully filled in or
 * only metadata present because data is being carried
 * elsewhere outside of pb.
 */
message MutationProto {
  optional bytes row = 1;
  optional MutationType mutateType = 2;
  repeated ColumnValue columnValue = 3;
  optional uint64 timestamp = 4;
  repeated NameBytesPair attribute = 5;
  optional Durability durability = 6 [default = USE_DEFAULT];

  // For some mutations, a result may be returned, in which case,
  // time range can be specified for potential performance gain
  optional TimeRange timeRange = 7;
  // The below count is set when the associated cells are NOT
  // part of this protobuf message; they are passed alongside
  // and then this Message is a placeholder with metadata.  The
  // count is needed to know how many to peel off the block of Cells as
  // ours.  NOTE: This is different from the pb managed cellCount of the
  // 'cell' field above which is non-null when the cells are pb'd.
  optional int32 associatedCellCount = 8;

  enum Durability {
    USE_DEFAULT  = 0;
    SKIP_WAL     = 1;
    ASYNC_WAL    = 2;
    SYNC_WAL     = 3;
    FSYNC_WAL    = 4;
  }

  enum MutationType {
    APPEND = 0;
    INCREMENT = 1;
    PUT = 2;
    DELETE = 3;
  }

  enum DeleteType {
    DELETE_ONE_VERSION = 0;
    DELETE_MULTIPLE_VERSIONS = 1;
    DELETE_FAMILY = 2;
  }

  message ColumnValue {
    required bytes family = 1;
    repeated QualifierValue qualifierValue = 2;

    message QualifierValue {
      optional bytes qualifier = 1;
      optional bytes value = 2;
      optional uint64 timestamp = 3;
      optional DeleteType deleteType = 4;
    }
  }
}

/**
 * The mutate request. Perform a single Mutate operation.
 *
 * Optionally, you can specify a condition. The mutate
 * will take place only if the condition is met.  Otherwise,
 * the mutate will be ignored.  In the response result,
 * parameter processed is used to indicate if the mutate
 * actually happened.
 */
message MutateRequest {
  required RegionSpecifier region = 1;
  required MutationProto mutation = 2;
  optional Condition condition = 3;
}

message MutateResponse {
  optional Result result = 1;

  // used for mutate to indicate processed only
  optional bool processed = 2;
}

/**
 * Instead of get from a table, you can scan it with optional filters.
 * You can specify the row key range, time range, the columns/families
 * to scan and so on.
 *
 * This scan is used the first time in a scan request. The response of
 * the initial scan will return a scanner id, which should be used to
 * fetch result batches later on before it is closed.
 */
message Scan {
  repeated Column column = 1;
  repeated NameBytesPair attribute = 2;
  optional bytes startRow = 3;
  optional bytes stopRow = 4;
  optional Filter filter = 5;
  optional TimeRange timeRange = 6;
  optional uint32 maxVersions = 7 [default = 1];
  optional bool cacheBlocks = 8 [default = true];
  optional uint32 batchSize = 9;
  optional uint64 maxResultSize = 10;
  optional uint32 storeLimit = 11;
  optional uint32 storeOffset = 12;
  optional bool loadColumnFamiliesOnDemand = 13; /* DO NOT add defaults to loadColumnFamiliesOnDemand. */
  optional uint32 cachingCount = 14;
  optional bool prefetching = 15;
}

/**
 * A scan request. Initially, it should specify a scan. Later on, you
 * can use the scanner id returned to fetch result batches with a different
 * scan request.
 *
 * The scanner will remain open if there are more results, and it's not
 * asked to be closed explicitly.
 *
 * You can fetch the results and ask the scanner to be closed to save
 * a trip if you are not interested in remaining results.
 */
message ScanRequest {
  optional RegionSpecifier region = 1;
  optional Scan scan = 2;
  optional uint64 scannerId = 3;
  optional uint32 numberOfRows = 4;
  optional bool closeScanner = 5;
  optional uint64 nextCallSeq = 6;
}

/**
 * The scan response. If there are no more results, moreResults will
 * be false.  If it is not specified, it means there are more.
 */
message ScanResponse {
  optional ResultCellMeta resultCellMeta = 1;
  optional uint64 scannerId = 2;
  optional bool moreResults = 3;
  optional uint32 ttl = 4;
}

message ResultCellMeta {
  repeated uint32 cellsLength = 1;
}

/**
 * Atomically bulk load multiple HFiles (say from different column families)
 * into an open region.
 */
message BulkLoadHFileRequest {
  required RegionSpecifier region = 1;
  repeated FamilyPath familyPath = 2;
  optional bool assignSeqNum = 3;

  message FamilyPath {
    required bytes family = 1;
    required string path = 2;
  }
}

message BulkLoadHFileResponse {
  required bool loaded = 1;
}

message CoprocessorServiceCall {
  required bytes row = 1;
  required string serviceName = 2;
  required string methodName = 3;
  required bytes request = 4;
}

message CoprocessorServiceRequest {
  required RegionSpecifier region = 1;
  required CoprocessorServiceCall call = 2;
}

message CoprocessorServiceResponse {
  required RegionSpecifier region = 1;
  required NameBytesPair value = 2;
}

/**
 * An action that is part of MultiRequest.
 * This is a union type - exactly one of the fields will be set.
 */
message MultiAction {
  optional MutationProto mutation = 1;
  optional Get get = 2;
}

/**
 * An individual action result. The result will in the
 * same order as the action in the request. If an action
 * returns a value, it is set in value field. If it doesn't
 * return anything, the result will be empty. If an action
 * fails to execute due to any exception, the exception
 * is returned as a stringified parameter.
 */
message ActionResult {
  optional Result value = 1;
  optional NameBytesPair exception = 2;
}

/**
 * You can execute a list of actions on a given region in order.
 *
 * If it is a list of mutate actions, atomic can be set
 * to make sure they can be processed atomically, just like
 * RowMutations.
 */
message MultiRequest {
  required RegionSpecifier region = 1;
  repeated MultiAction action = 2;
  optional bool atomic = 3;
}

message MultiResponse {
  repeated ActionResult result = 1;
}


service ClientService {
  rpc get(GetRequest)
    returns(GetResponse);

  rpc multiGet(MultiGetRequest)
    returns(MultiGetResponse);

  rpc mutate(MutateRequest)
    returns(MutateResponse);

  rpc scan(ScanRequest)
    returns(ScanResponse);

  rpc bulkLoadHFile(BulkLoadHFileRequest)
    returns(BulkLoadHFileResponse);

  rpc execService(CoprocessorServiceRequest)
    returns(CoprocessorServiceResponse);

  rpc multi(MultiRequest)
    returns(MultiResponse);
}