hbase.genavro

/*
 * 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.
 */

/**
 * Avro protocol for a "gateway" service
 */
@namespace("org.apache.hadoop.hbase.avro.generated")
protocol HBase {

  //
  // TYPES
  //

  //
  // Cluster metadata
  //
  // TODO(hammer): Best way to represent java.net.InetSocketAddress?
  record AServerAddress {
    string bindAddress;
    string hostname;
    string inetSocketAddress;
    int port;
  }

  record ARegionLoad {
    int memStoreSizeMB;
    bytes name;
    int storefileIndexSizeMB;
    int storefiles;
    int storefileSizeMB;
    int stores;
  }

  record AServerLoad {
    int load;
    int maxHeapMB;
    int memStoreSizeInMB;
    int numberOfRegions;
    int numberOfRequests;
    union { array<ARegionLoad>, null } regionsLoad;
    int storefileIndexSizeInMB;
    int storefiles;
    int storefileSizeInMB;
    int usedHeapMB;
  }

  record AServerInfo {
    int infoPort;
    AServerLoad load;
    AServerAddress serverAddress;
    string serverName;
    long startCode;
  }

  // TODO(hammer): Implement reusable Writable to Avro record converter?
  record AClusterStatus {
    double averageLoad;
    union { array<string>, null} deadServerNames;
    int deadServers;
    string hbaseVersion;
    int regionsCount;
    int requestsCount;
    union { array<AServerInfo>, null } serverInfos;
    int servers;
  }

  //
  // Family metadata
  //
  // TODO(hammer): how to keep in sync with Java Enum?
  enum ACompressionAlgorithm {
    LZO, GZ, NONE
  }

  // TODO(hammer): include COLUMN_DESCRIPTOR_VERSION?
  // TODO(hammer): add new bloomfilter stuff
  record AFamilyDescriptor {
    bytes name;
    union { ACompressionAlgorithm, null } compression;
    union { int, null } maxVersions;
    union { int, null } blocksize;
    union { boolean, null } inMemory;
    union { int, null } timeToLive;
    union { boolean, null } blockCacheEnabled;
  }

  //
  // Table metadata
  //
  // TODO(hammer): include TABLE_DESCRIPTOR_VERSION?
  record ATableDescriptor {
    bytes name;
    union { array<AFamilyDescriptor>, null } families;
    union { long, null } maxFileSize;
    union { long, null } memStoreFlushSize;
    union { boolean, null } rootRegion;
    union { boolean, null } metaRegion;
    union { boolean, null } metaTable;
    union { boolean, null } readOnly;
    union { boolean, null } deferredLogFlush;
  }

  //
  // Single-Row DML (Get)
  //
  record AColumn {
    bytes family;
    union { bytes, null } qualifier;
  }

  record ATimeRange {
    long minStamp;
    long maxStamp;
  }

  // TODO(hammer): Add filter options
  record AGet {
    bytes row;
    union { array<AColumn>, null } columns;
    union { long, null } timestamp;
    union { ATimeRange, null } timerange;
    union { int, null } maxVersions;
  }

  record AResultEntry {
    bytes family;
    bytes qualifier;
    bytes value;
    long timestamp;
  }

  // Avro maps can't use non-string keys, so using an array for now
  record AResult {
    bytes row;
    union { array<AResultEntry>, null } entries;
  }

  //
  // Single-Row DML (Put)
  //
  // TODO(hammer): Reuse a single KeyValue-style record for Get and Put?
  record AColumnValue {
    bytes family;
    bytes qualifier;
    bytes value;
    union { long, null } timestamp;
  }

  record APut {
    bytes row;
    array<AColumnValue> columnValues;
  }

  //
  // Single-Row DML (Delete)
  //
  // TODO(hammer): Add fields when API is rationalized (HBASE-2609)
  record ADelete {
    bytes row;
    union { array<AColumn>, null } columns;
  }

  //
  // Multi-Row DML (Scan)
  //
  record AScan {
    union { bytes, null } startRow;
    union { bytes, null } stopRow;
    union { array<AColumn>, null } columns;
    union { long, null } timestamp;
    union { ATimeRange, null } timerange;
    union { int, null } maxVersions;
  }

  //
  // ERRORS
  //

  /**
   * An AIOError error signals that an error occurred communicating
   * to the HBase master or a HBase region server. Also used to return
   * more general HBase error conditions.
   */
  error AIOError {
    string message;
  }

  /**
   * An AIllegalArgument error indicates an illegal or invalid
   * argument was passed into a procedure.
   */
  error AIllegalArgument {
    string message;
  }

  /**
   * An ATableExists error that a table with the specified
   * name already exists
   */
  error ATableExists {
    string message;
  }

  /**
   * An AMasterNotRunning error means we couldn't reach the Master.
   */
  error AMasterNotRunning {
    string message;
  }

  //
  // MESSAGES
  //

  // TODO(hammer): surgery tools
  // TODO(hammer): getRowOrBefore/checkAndPut/flushCommits
  // TODO(hammer): MultiPut/Get/Delete

  // Cluster metadata
  string getHBaseVersion() throws AIOError;
  AClusterStatus getClusterStatus() throws AIOError;
  array<ATableDescriptor> listTables() throws AIOError;

  // Table metadata
  ATableDescriptor describeTable(bytes table) throws AIOError;
  boolean isTableEnabled(bytes table) throws AIOError;
  boolean tableExists(bytes table) throws AIOError;

  // Family metadata
  AFamilyDescriptor describeFamily(bytes table, bytes family) throws AIOError;

  // Table admin
  void createTable(ATableDescriptor table) throws AIOError, AIllegalArgument, ATableExists, AMasterNotRunning;
  void deleteTable(bytes table) throws AIOError;
  void modifyTable(bytes table, ATableDescriptor tableDescriptor) throws AIOError;
  void enableTable(bytes table) throws AIOError;
  void disableTable(bytes table) throws AIOError;
  void flush(bytes table) throws AIOError;

  // Family admin
  void addFamily(bytes table, AFamilyDescriptor family) throws AIOError;
  void deleteFamily(bytes table, bytes family) throws AIOError;
  void modifyFamily(bytes table, bytes familyName, AFamilyDescriptor familyDescriptor) throws AIOError;

  // Single-row DML
  AResult get(bytes table, AGet get) throws AIOError;
  void put(bytes table, APut put) throws AIOError;
  void delete(bytes table, ADelete delete) throws AIOError;
  long incrementColumnValue(bytes table, bytes row, bytes family, bytes qualifier, long amount, boolean writeToWAL) throws AIOError;

  // Multi-row DML (read-only)
  int scannerOpen(bytes table, AScan scan) throws AIOError;
  void scannerClose(int scannerId) throws AIOError, AIllegalArgument;
  array<AResult> scannerGetRows(int scannerId, int numberOfRows) throws AIOError, AIllegalArgument;
}