*

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

*/

* <p>Used to communicate with a single HBase table.  An implementation of

* {@link HTableInterface}.  Instances of this class can be constructed directly but it is

* encouraged that users get instances via {@link HConnection} and {@link HConnectionManager}.

* See {@link HConnectionManager} class comment for an example.

*

* <p>This class is not thread safe for reads nor write.

*

* <p>In case of writes (Put, Delete), the underlying write buffer can

* be corrupted if multiple threads contend over a single HTable instance.

*

* <p>In case of reads, some fields used by a Scan are shared among all threads.

* The HTable implementation can either not contract to be safe in case of a Get

*

* <p>Instances of HTable passed the same {@link Configuration} instance will

* share connections to servers out on the cluster and to the zookeeper ensemble

* as well as caches of region locations.  This is usually a *good* thing and it

* is recommended to reuse the same configuration object for all your tables.

* This happens because they will all share the same underlying

* {@link HConnection} instance. See {@link HConnectionManager} for more on

* how this mechanism works.

*

* <p>{@link HConnection} will read most of the

* configuration it needs from the passed {@link Configuration} on initial

* construction.  Thereafter, for settings such as

* <code>hbase.client.pause</code>, <code>hbase.client.retries.number</code>,

* and <code>hbase.client.rpc.maxattempts</code> updating their values in the

* passed {@link Configuration} subsequent to {@link HConnection} construction

* will go unnoticed.  To run with changed values, make a new

* {@link HTable} passing a new {@link Configuration} instance that has the

* new configuration.

*

* <p>Note that this class implements the {@link Closeable} interface. When a

* HTable instance is no longer required, it *should* be closed in order to ensure

* that the underlying resources are promptly released. Please note that the close

* method can throw java.io.IOException that must be handled.

*

* @see HBaseAdmin for create, drop, list, enable and disable of tables.

* @see HConnection

* @see HConnectionManager

*/

@InterfaceStability.Stable

  private static final Log LOG = LogFactory.getLog(HTable.class);

  protected ClusterConnection connection;

  private final TableName tableName;

  private volatile Configuration configuration;

  protected List<Row> writeAsyncBuffer = new LinkedList<Row>();

  private long writeBufferSize;

  private boolean clearBufferOnFail;

  private boolean autoFlush;

  protected long currentWriteBufferSize;

  protected int scannerCaching;

  private int maxKeyValueSize;

  private ExecutorService pool;  // For Multi & Scan

  private boolean closed;

  private int operationTimeout;

  private int retries;

  private final boolean cleanupPoolOnClose; // shutdown the pool in close()

  private final boolean cleanupConnectionOnClose; // close the connection in close()

  private Consistency defaultConsistency = Consistency.STRONG;

  private int primaryCallTimeoutMicroSecond;

  private int replicaCallTimeoutMicroSecondScan;

  /** The Async process for puts with autoflush set to false or multiputs */

  protected AsyncProcess ap;

  /** The Async process for batch */

  protected AsyncProcess multiAp;

  private RpcRetryingCallerFactory rpcCallerFactory;

  private RpcControllerFactory rpcControllerFactory;

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>conf</code> instance.  Uses already-populated

   * region cache if one is available, populated by any other HTable instances

   * sharing this <code>conf</code> instance.  Recommended.

   * @param conf Configuration object to use.

   * @param tableName Name of the table.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Constructing HTable objects manually has been deprecated. Please use

   * {@link Connection} to instantiate a {@link Table} instead.

   */

  @Deprecated

  public HTable(Configuration conf, final String tableName)

  throws IOException {

    this(conf, TableName.valueOf(tableName));

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>conf</code> instance.  Uses already-populated

   * region cache if one is available, populated by any other HTable instances

   * sharing this <code>conf</code> instance.  Recommended.

   * @param conf Configuration object to use.

   * @param tableName Name of the table.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Constructing HTable objects manually has been deprecated. Please use

   * {@link Connection} to instantiate a {@link Table} instead.

   */

  @Deprecated

  public HTable(Configuration conf, final byte[] tableName)

  throws IOException {

    this(conf, TableName.valueOf(tableName));

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>conf</code> instance.  Uses already-populated

   * region cache if one is available, populated by any other HTable instances

   * sharing this <code>conf</code> instance.  Recommended.

   * @param conf Configuration object to use.

   * @param tableName table name pojo

   * @throws IOException if a remote or network exception occurs

   * @deprecated Constructing HTable objects manually has been deprecated. Please use

   * {@link Connection} to instantiate a {@link Table} instead.

   */

  @Deprecated

  public HTable(Configuration conf, final TableName tableName)

  throws IOException {

    this.tableName = tableName;

    this.cleanupPoolOnClose = this.cleanupConnectionOnClose = true;

    if (conf == null) {

      this.connection = null;

      return;

    }

    this.connection = ConnectionManager.getConnectionInternal(conf);

    this.configuration = conf;

    this.pool = getDefaultExecutor(conf);

    this.finishSetup();

  }

  /**

   * Creates an object to access a HBase table. Shares zookeeper connection and other resources with

   * other HTable instances created with the same <code>connection</code> instance. Use this

   * constructor when the Connection instance is externally managed.

   * @param tableName Name of the table.

   * @param connection HConnection to be used.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Do not use.

   */

  @Deprecated

  public HTable(TableName tableName, Connection connection) throws IOException {

    this.tableName = tableName;

    this.cleanupPoolOnClose = true;

    this.cleanupConnectionOnClose = false;

    this.connection = (ClusterConnection)connection;

    this.configuration = connection.getConfiguration();

    this.pool = getDefaultExecutor(this.configuration);

    this.finishSetup();

  }

  public static ThreadPoolExecutor getDefaultExecutor(Configuration conf) {

    int maxThreads = conf.getInt("hbase.htable.threads.max", Integer.MAX_VALUE);

    if (maxThreads == 0) {

      maxThreads = 1; // is there a better default?

    }

    long keepAliveTime = conf.getLong("hbase.htable.threads.keepalivetime", 60);

    // Using the "direct handoff" approach, new threads will only be created

    // if it is necessary and will grow unbounded. This could be bad but in HCM

    // we only create as many Runnables as there are region servers. It means

    // it also scales when new region servers are added.

    ThreadPoolExecutor pool = new ThreadPoolExecutor(1, maxThreads, keepAliveTime, TimeUnit.SECONDS,

        new SynchronousQueue<Runnable>(), Threads.newDaemonThreadFactory("htable"));

    ((ThreadPoolExecutor) pool).allowCoreThreadTimeOut(true);

    return pool;

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>conf</code> instance.  Uses already-populated

   * region cache if one is available, populated by any other HTable instances

   * sharing this <code>conf</code> instance.

   * Use this constructor when the ExecutorService is externally managed.

   * @param conf Configuration object to use.

   * @param tableName Name of the table.

   * @param pool ExecutorService to be used.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Constructing HTable objects manually has been deprecated. Please use

   * {@link Connection} to instantiate a {@link Table} instead.

   */

  @Deprecated

  public HTable(Configuration conf, final byte[] tableName, final ExecutorService pool)

      throws IOException {

    this(conf, TableName.valueOf(tableName), pool);

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>conf</code> instance.  Uses already-populated

   * region cache if one is available, populated by any other HTable instances

   * sharing this <code>conf</code> instance.

   * Use this constructor when the ExecutorService is externally managed.

   * @param conf Configuration object to use.

   * @param tableName Name of the table.

   * @param pool ExecutorService to be used.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Constructing HTable objects manually has been deprecated. Please use

   * {@link Connection} to instantiate a {@link Table} instead.

   */

  @Deprecated

  public HTable(Configuration conf, final TableName tableName, final ExecutorService pool)

      throws IOException {

    this.connection = ConnectionManager.getConnectionInternal(conf);

    this.configuration = conf;

    this.pool = pool;

    if (pool == null) {

      this.pool = getDefaultExecutor(conf);

      this.cleanupPoolOnClose = true;

    } else {

      this.cleanupPoolOnClose = false;

    }

    this.tableName = tableName;

    this.cleanupConnectionOnClose = true;

    this.finishSetup();

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>connection</code> instance.

   * Use this constructor when the ExecutorService and HConnection instance are

   * externally managed.

   * @param tableName Name of the table.

   * @param connection HConnection to be used.

   * @param pool ExecutorService to be used.

   * @throws IOException if a remote or network exception occurs.

   * @deprecated Do not use, internal ctor.

   */

  @Deprecated

  public HTable(final byte[] tableName, final HConnection connection,

      final ExecutorService pool) throws IOException {

    this(TableName.valueOf(tableName), connection, pool);

  }

  /** @deprecated Do not use, internal ctor. */

  @Deprecated

  public HTable(TableName tableName, final HConnection connection,

      final ExecutorService pool) throws IOException {

    this(tableName, (ClusterConnection)connection, pool);

  }

  /**

   * Creates an object to access a HBase table.

   * Shares zookeeper connection and other resources with other HTable instances

   * created with the same <code>connection</code> instance.

   * Visible only for HTableWrapper which is in different package.

   * Should not be used by exernal code.

   * @param tableName Name of the table.

   * @param connection HConnection to be used.

   * @param pool ExecutorService to be used.

   * @throws IOException if a remote or network exception occurs

   */

  @InterfaceAudience.Private

  public HTable(TableName tableName, final ClusterConnection connection,

      final ExecutorService pool) throws IOException {

    if (connection == null || connection.isClosed()) {

      throw new IllegalArgumentException("Connection is null or closed.");

    }

    this.tableName = tableName;

    this.cleanupConnectionOnClose = false;

    this.connection = connection;

    this.configuration = connection.getConfiguration();

    this.pool = pool;

    if (pool == null) {

      this.pool = getDefaultExecutor(this.configuration);

      this.cleanupPoolOnClose = true;

    } else {

      this.cleanupPoolOnClose = false;

    }

    this.finishSetup();

  }

  /**

   * For internal testing.

   */

  protected HTable() {

    tableName = null;

    cleanupPoolOnClose = false;

    cleanupConnectionOnClose = false;

  }

  /**

   * setup this HTable's parameter based on the passed configuration

   */

  private void finishSetup() throws IOException {

    this.operationTimeout = tableName.isSystemTable() ?

      this.configuration.getInt(HConstants.HBASE_CLIENT_META_OPERATION_TIMEOUT,

        HConstants.DEFAULT_HBASE_CLIENT_OPERATION_TIMEOUT):

      this.configuration.getInt(HConstants.HBASE_CLIENT_OPERATION_TIMEOUT,

        HConstants.DEFAULT_HBASE_CLIENT_OPERATION_TIMEOUT);

    this.writeBufferSize = this.configuration.getLong(

        "hbase.client.write.buffer", 2097152);

    this.clearBufferOnFail = true;

    this.autoFlush = true;

    this.currentWriteBufferSize = 0;

    this.scannerCaching = this.configuration.getInt(

        HConstants.HBASE_CLIENT_SCANNER_CACHING,

        HConstants.DEFAULT_HBASE_CLIENT_SCANNER_CACHING);

    this.primaryCallTimeoutMicroSecond =

        this.configuration.getInt("hbase.client.primaryCallTimeout.get", 10000); // 10 ms

    this.replicaCallTimeoutMicroSecondScan =

        this.configuration.getInt("hbase.client.replicaCallTimeout.scan", 1000000); // 1000 ms

    this.retries = configuration.getInt(HConstants.HBASE_CLIENT_RETRIES_NUMBER,

            HConstants.DEFAULT_HBASE_CLIENT_RETRIES_NUMBER);

    this.rpcCallerFactory = RpcRetryingCallerFactory.instantiate(configuration);

    this.rpcControllerFactory = RpcControllerFactory.instantiate(configuration);

    // puts need to track errors globally due to how the APIs currently work.

    ap = new AsyncProcess(connection, configuration, pool, rpcCallerFactory, true, rpcControllerFactory);

    multiAp = this.connection.getAsyncProcess();

    this.maxKeyValueSize = this.configuration.getInt(

        "hbase.client.keyvalue.maxsize", -1);

    this.closed = false;

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public Configuration getConfiguration() {

    return configuration;

  }

  /**

   * Tells whether or not a table is enabled or not. This method creates a

   * new HBase configuration, so it might make your unit tests fail due to

   * incorrect ZK client port.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

  * @deprecated use {@link HBaseAdmin#isTableEnabled(byte[])}

   */

  @Deprecated

  public static boolean isTableEnabled(String tableName) throws IOException {

    return isTableEnabled(TableName.valueOf(tableName));

  }

  /**

   * Tells whether or not a table is enabled or not. This method creates a

   * new HBase configuration, so it might make your unit tests fail due to

   * incorrect ZK client port.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

  * @deprecated use {@link HBaseAdmin#isTableEnabled(byte[])}

   */

  @Deprecated

  public static boolean isTableEnabled(byte[] tableName) throws IOException {

    return isTableEnabled(TableName.valueOf(tableName));

  }

  /**

   * Tells whether or not a table is enabled or not. This method creates a

   * new HBase configuration, so it might make your unit tests fail due to

   * incorrect ZK client port.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

   * @deprecated use {@link HBaseAdmin#isTableEnabled(byte[])}

   */

  @Deprecated

  public static boolean isTableEnabled(TableName tableName) throws IOException {

    return isTableEnabled(HBaseConfiguration.create(), tableName);

  }

  /**

   * Tells whether or not a table is enabled or not.

   * @param conf The Configuration object to use.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

   * @deprecated use {@link HBaseAdmin#isTableEnabled(byte[])}

   */

  @Deprecated

  public static boolean isTableEnabled(Configuration conf, String tableName)

  throws IOException {

    return isTableEnabled(conf, TableName.valueOf(tableName));

  }

  /**

   * Tells whether or not a table is enabled or not.

   * @param conf The Configuration object to use.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

   * @deprecated use {@link HBaseAdmin#isTableEnabled(byte[])}

   */

  @Deprecated

  public static boolean isTableEnabled(Configuration conf, byte[] tableName)

  throws IOException {

    return isTableEnabled(conf, TableName.valueOf(tableName));

  }

  /**

   * Tells whether or not a table is enabled or not.

   * @param conf The Configuration object to use.

   * @param tableName Name of table to check.

   * @return {@code true} if table is online.

   * @throws IOException if a remote or network exception occurs

   * @deprecated use {@link HBaseAdmin#isTableEnabled(org.apache.hadoop.hbase.TableName tableName)}

   */

  @Deprecated

  public static boolean isTableEnabled(Configuration conf,

      final TableName tableName) throws IOException {

    return HConnectionManager.execute(new HConnectable<Boolean>(conf) {

      @Override

      public Boolean connect(HConnection connection) throws IOException {

        return connection.isTableEnabled(tableName);

      }

    });

  }

  /**

   * Find region location hosting passed row using cached info

   * @param row Row to find.

   * @return The location of the given row.

   * @throws IOException if a remote or network exception occurs

   * @deprecated Use {@link RegionLocator#getRegionLocation(byte[])}

   */

  @Deprecated

  public HRegionLocation getRegionLocation(final String row)

  throws IOException {

    return connection.getRegionLocation(tableName, Bytes.toBytes(row), false);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public HRegionLocation getRegionLocation(final byte [] row)

  throws IOException {

    return connection.getRegionLocation(tableName, row, false);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public HRegionLocation getRegionLocation(final byte [] row, boolean reload)

  throws IOException {

    return connection.getRegionLocation(tableName, row, reload);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public byte [] getTableName() {

    return this.tableName.getName();

  }

  @Override

  public TableName getName() {

    return tableName;

  }

  /**

   * <em>INTERNAL</em> Used by unit tests and tools to do low-level

   * manipulations.

   * @return An HConnection instance.

   * @deprecated This method will be changed from public to package protected.

   */

  // TODO(tsuna): Remove this.  Unit tests shouldn't require public helpers.

  @Deprecated

  @VisibleForTesting

  public HConnection getConnection() {

    return this.connection;

  }

  /**

   * Gets the number of rows that a scanner will fetch at once.

   * <p>

   * The default value comes from {@code hbase.client.scanner.caching}.

   * @deprecated Use {@link Scan#setCaching(int)} and {@link Scan#getCaching()}

   */

  @Deprecated

  public int getScannerCaching() {

    return scannerCaching;

  }

  /**

   * Kept in 0.96 for backward compatibility

   * @deprecated  since 0.96. This is an internal buffer that should not be read nor write.

   */

  @Deprecated

  public List<Row> getWriteBuffer() {

    return writeAsyncBuffer;

  }

  /**

   * Sets the number of rows that a scanner will fetch at once.

   * <p>

   * This will override the value specified by

   * {@code hbase.client.scanner.caching}.

   * Increasing this value will reduce the amount of work needed each time

   * {@code next()} is called on a scanner, at the expense of memory use

   * (since more rows will need to be maintained in memory by the scanners).

   * @param scannerCaching the number of rows a scanner will fetch at once.

   * @deprecated Use {@link Scan#setCaching(int)}

   */

  @Deprecated

  public void setScannerCaching(int scannerCaching) {

    this.scannerCaching = scannerCaching;

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public HTableDescriptor getTableDescriptor() throws IOException {

    return new UnmodifyableHTableDescriptor(

      this.connection.getHTableDescriptor(this.tableName));

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public byte [][] getStartKeys() throws IOException {

    return getStartEndKeys().getFirst();

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public byte[][] getEndKeys() throws IOException {

    return getStartEndKeys().getSecond();

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public Pair<byte[][],byte[][]> getStartEndKeys() throws IOException {

    List<RegionLocations> regions = listRegionLocations();

    final List<byte[]> startKeyList = new ArrayList<byte[]>(regions.size());

    final List<byte[]> endKeyList = new ArrayList<byte[]>(regions.size());

    for (RegionLocations locations : regions) {

      HRegionInfo region = locations.getRegionLocation().getRegionInfo();

      startKeyList.add(region.getStartKey());

      endKeyList.add(region.getEndKey());

    }

    return new Pair<byte [][], byte [][]>(

      startKeyList.toArray(new byte[startKeyList.size()][]),

      endKeyList.toArray(new byte[endKeyList.size()][]));

  }

  @VisibleForTesting

  List<RegionLocations> listRegionLocations() throws IOException {

    return MetaScanner.listTableRegionLocations(getConfiguration(), this.connection, getName());

  }

  /**

   * Gets all the regions and their address for this table.

   * <p>

   * This is mainly useful for the MapReduce integration.

   * @return A map of HRegionInfo with it's server address

   * @throws IOException if a remote or network exception occurs

   * @deprecated This is no longer a public API

   */

  @Deprecated

  public NavigableMap<HRegionInfo, ServerName> getRegionLocations() throws IOException {

    // TODO: Odd that this returns a Map of HRI to SN whereas getRegionLocator, singular, returns an HRegionLocation.

    return MetaScanner.allTableRegions(getConfiguration(), this.connection, getName(), false);

  }

  /**

   * Get the corresponding regions for an arbitrary range of keys.

   * <p>

   * @param startKey Starting row in range, inclusive

   * @param endKey Ending row in range, exclusive

   * @return A list of HRegionLocations corresponding to the regions that

   * contain the specified range

   * @throws IOException if a remote or network exception occurs

   * @deprecated This is no longer a public API

   */

  @Deprecated

  public List<HRegionLocation> getRegionsInRange(final byte [] startKey,

    final byte [] endKey) throws IOException {

    return getRegionsInRange(startKey, endKey, false);

  }

  /**

   * Get the corresponding regions for an arbitrary range of keys.

   * <p>

   * @param startKey Starting row in range, inclusive

   * @param endKey Ending row in range, exclusive

   * @param reload true to reload information or false to use cached information

   * @return A list of HRegionLocations corresponding to the regions that

   * contain the specified range

   * @throws IOException if a remote or network exception occurs

   * @deprecated This is no longer a public API

   */

  @Deprecated

  public List<HRegionLocation> getRegionsInRange(final byte [] startKey,

      final byte [] endKey, final boolean reload) throws IOException {

    return getKeysAndRegionsInRange(startKey, endKey, false, reload).getSecond();

  }

  /**

   * Get the corresponding start keys and regions for an arbitrary range of

   * keys.

   * <p>

   * @param startKey Starting row in range, inclusive

   * @param endKey Ending row in range

   * @param includeEndKey true if endRow is inclusive, false if exclusive

   * @return A pair of list of start keys and list of HRegionLocations that

   *         contain the specified range

   * @throws IOException if a remote or network exception occurs

   * @deprecated This is no longer a public API

   */

  @Deprecated

  private Pair<List<byte[]>, List<HRegionLocation>> getKeysAndRegionsInRange(

      final byte[] startKey, final byte[] endKey, final boolean includeEndKey)

      throws IOException {

    return getKeysAndRegionsInRange(startKey, endKey, includeEndKey, false);

  }

  /**

   * Get the corresponding start keys and regions for an arbitrary range of

   * keys.

   * <p>

   * @param startKey Starting row in range, inclusive

   * @param endKey Ending row in range

   * @param includeEndKey true if endRow is inclusive, false if exclusive

   * @param reload true to reload information or false to use cached information

   * @return A pair of list of start keys and list of HRegionLocations that

   *         contain the specified range

   * @throws IOException if a remote or network exception occurs

   * @deprecated This is no longer a public API

   */

  @Deprecated

  private Pair<List<byte[]>, List<HRegionLocation>> getKeysAndRegionsInRange(

      final byte[] startKey, final byte[] endKey, final boolean includeEndKey,

      final boolean reload) throws IOException {

    final boolean endKeyIsEndOfTable = Bytes.equals(endKey,HConstants.EMPTY_END_ROW);

    if ((Bytes.compareTo(startKey, endKey) > 0) && !endKeyIsEndOfTable) {

      throw new IllegalArgumentException(

        "Invalid range: " + Bytes.toStringBinary(startKey) +

        " > " + Bytes.toStringBinary(endKey));

    }

    List<byte[]> keysInRange = new ArrayList<byte[]>();

    List<HRegionLocation> regionsInRange = new ArrayList<HRegionLocation>();

    byte[] currentKey = startKey;

    do {

      HRegionLocation regionLocation = getRegionLocation(currentKey, reload);

      keysInRange.add(currentKey);

      regionsInRange.add(regionLocation);

      currentKey = regionLocation.getRegionInfo().getEndKey();

    } while (!Bytes.equals(currentKey, HConstants.EMPTY_END_ROW)

        && (endKeyIsEndOfTable || Bytes.compareTo(currentKey, endKey) < 0

            || (includeEndKey && Bytes.compareTo(currentKey, endKey) == 0)));

    return new Pair<List<byte[]>, List<HRegionLocation>>(keysInRange,

        regionsInRange);

  }

  /**

   * {@inheritDoc}

   * @deprecated Use reversed scan instead.

   */

   @Override

   @Deprecated

   public Result getRowOrBefore(final byte[] row, final byte[] family)

       throws IOException {

     RegionServerCallable<Result> callable = new RegionServerCallable<Result>(this.connection,

         tableName, row) {

       @Override

      public Result call(int callTimeout) throws IOException {

         PayloadCarryingRpcController controller = rpcControllerFactory.newController();

         controller.setPriority(tableName);

         controller.setCallTimeout(callTimeout);

         ClientProtos.GetRequest request = RequestConverter.buildGetRowOrBeforeRequest(

             getLocation().getRegionInfo().getRegionName(), row, family);

         try {

           ClientProtos.GetResponse response = getStub().get(controller, request);

           if (!response.hasResult()) return null;

           return ProtobufUtil.toResult(response.getResult());

         } catch (ServiceException se) {

           throw ProtobufUtil.getRemoteException(se);

         }

       }

     };

     return rpcCallerFactory.<Result>newCaller().callWithRetries(callable, this.operationTimeout);

   }

  /**

   * The underlying {@link HTable} must not be closed.

   * {@link HTableInterface#getScanner(Scan)} has other usage details.

   */

  @Override

  public ResultScanner getScanner(final Scan scan) throws IOException {

    if (scan.getCaching() <= 0) {

      scan.setCaching(getScannerCaching());

    }

    if (scan.isReversed()) {

      if (scan.isSmall()) {

        return new ClientSmallReversedScanner(getConfiguration(), scan, getName(),

            this.connection, this.rpcCallerFactory, this.rpcControllerFactory,

            pool, replicaCallTimeoutMicroSecondScan);

      } else {

        return new ReversedClientScanner(getConfiguration(), scan, getName(),

            this.connection, this.rpcCallerFactory, this.rpcControllerFactory,

            pool, replicaCallTimeoutMicroSecondScan);

      }

    }

    if (scan.isSmall()) {

      return new ClientSmallScanner(getConfiguration(), scan, getName(),

          this.connection, this.rpcCallerFactory, this.rpcControllerFactory,

          pool, replicaCallTimeoutMicroSecondScan);

    } else {

      return new ClientScanner(getConfiguration(), scan, getName(), this.connection,

          this.rpcCallerFactory, this.rpcControllerFactory,

          pool, replicaCallTimeoutMicroSecondScan);

    }

  }

  /**

   * The underlying {@link HTable} must not be closed.

   * {@link HTableInterface#getScanner(byte[])} has other usage details.

   */

  @Override

  public ResultScanner getScanner(byte [] family) throws IOException {

    Scan scan = new Scan();

    scan.addFamily(family);

    return getScanner(scan);

  }

  /**

   * The underlying {@link HTable} must not be closed.

   * {@link HTableInterface#getScanner(byte[], byte[])} has other usage details.

   */

  @Override

  public ResultScanner getScanner(byte [] family, byte [] qualifier)

  throws IOException {

    Scan scan = new Scan();

    scan.addColumn(family, qualifier);

    return getScanner(scan);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public Result get(final Get get) throws IOException {

    if (get.getConsistency() == null){

      get.setConsistency(defaultConsistency);

    }

    if (get.getConsistency() == Consistency.STRONG) {

      // Good old call.

      RegionServerCallable<Result> callable = new RegionServerCallable<Result>(this.connection,

          getName(), get.getRow()) {

        @Override

        public Result call(int callTimeout) throws IOException {

          ClientProtos.GetRequest request =

              RequestConverter.buildGetRequest(getLocation().getRegionInfo().getRegionName(), get);

          PayloadCarryingRpcController controller = rpcControllerFactory.newController();

          controller.setPriority(tableName);

          controller.setCallTimeout(callTimeout);

          try {

            ClientProtos.GetResponse response = getStub().get(controller, request);

            if (response == null) return null;

            return ProtobufUtil.toResult(response.getResult());

          } catch (ServiceException se) {

            throw ProtobufUtil.getRemoteException(se);

          }

        }

      };

      return rpcCallerFactory.<Result>newCaller().callWithRetries(callable, this.operationTimeout);

    }

    // Call that takes into account the replica

    RpcRetryingCallerWithReadReplicas callable = new RpcRetryingCallerWithReadReplicas(

      rpcControllerFactory, tableName, this.connection, get, pool, retries,

      operationTimeout, primaryCallTimeoutMicroSecond);

    return callable.call();

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public Result[] get(List<Get> gets) throws IOException {

    if (gets.size() == 1) {

      return new Result[]{get(gets.get(0))};

    }

    try {

      Object [] r1 = batch((List)gets);

      // translate.

      Result [] results = new Result[r1.length];

      int i=0;

      for (Object o : r1) {

        // batch ensures if there is a failure we get an exception instead

        results[i++] = (Result) o;

      }

      return results;

    } catch (InterruptedException e) {

      throw (InterruptedIOException)new InterruptedIOException().initCause(e);

    }

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void batch(final List<? extends Row> actions, final Object[] results)

      throws InterruptedException, IOException {

    AsyncRequestFuture ars = multiAp.submitAll(pool, tableName, actions, null, results);

    ars.waitUntilDone();

    if (ars.hasError()) {

      throw ars.getErrors();

    }

  }

  /**

   * {@inheritDoc}

   * @deprecated If any exception is thrown by one of the actions, there is no way to

   * retrieve the partially executed results. Use {@link #batch(List, Object[])} instead.

   */

  @Deprecated

  @Override

  public Object[] batch(final List<? extends Row> actions)

     throws InterruptedException, IOException {

    Object[] results = new Object[actions.size()];

    batch(actions, results);

    return results;

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public <R> void batchCallback(

      final List<? extends Row> actions, final Object[] results, final Batch.Callback<R> callback)

      throws IOException, InterruptedException {

    connection.processBatchCallback(actions, tableName, pool, results, callback);

  }

  /**

   * {@inheritDoc}

   * @deprecated If any exception is thrown by one of the actions, there is no way to

   * retrieve the partially executed results. Use

   * {@link #batchCallback(List, Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback)}

   * instead.

   */

  @Deprecated

  @Override

  public <R> Object[] batchCallback(

    final List<? extends Row> actions, final Batch.Callback<R> callback) throws IOException,

      InterruptedException {

    Object[] results = new Object[actions.size()];

    batchCallback(actions, results, callback);

    return results;

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void delete(final Delete delete)

  throws IOException {

    RegionServerCallable<Boolean> callable = new RegionServerCallable<Boolean>(connection,

        tableName, delete.getRow()) {

      @Override

      public Boolean call(int callTimeout) throws IOException {

        PayloadCarryingRpcController controller = rpcControllerFactory.newController();

        controller.setPriority(tableName);

        controller.setCallTimeout(callTimeout);

        try {

          MutateRequest request = RequestConverter.buildMutateRequest(

            getLocation().getRegionInfo().getRegionName(), delete);

          MutateResponse response = getStub().mutate(controller, request);

          return Boolean.valueOf(response.getProcessed());

        } catch (ServiceException se) {

          throw ProtobufUtil.getRemoteException(se);

        }

      }

    };

    rpcCallerFactory.<Boolean> newCaller().callWithRetries(callable, this.operationTimeout);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void delete(final List<Delete> deletes)

  throws IOException {

    Object[] results = new Object[deletes.size()];

    try {

      batch(deletes, results);

    } catch (InterruptedException e) {

      throw (InterruptedIOException)new InterruptedIOException().initCause(e);

    } finally {

      // mutate list so that it is empty for complete success, or contains only failed records

      // results are returned in the same order as the requests in list

      // walk the list backwards, so we can remove from list without impacting the indexes of earlier members

      for (int i = results.length - 1; i>=0; i--) {

        // if result is not null, it succeeded

        if (results[i] instanceof Result) {

          deletes.remove(i);

        }

      }

    }

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void put(final Put put)

      throws InterruptedIOException, RetriesExhaustedWithDetailsException {

    doPut(put);

    if (autoFlush) {

      flushCommits();

    }

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void put(final List<Put> puts)

      throws InterruptedIOException, RetriesExhaustedWithDetailsException {

    for (Put put : puts) {

      doPut(put);

    }

    if (autoFlush) {

      flushCommits();

    }

  }

  /**

   * Add the put to the buffer. If the buffer is already too large, sends the buffer to the

   *  cluster.

   * @throws RetriesExhaustedWithDetailsException if there is an error on the cluster.

   * @throws InterruptedIOException if we were interrupted.

   */

  private void doPut(Put put) throws InterruptedIOException, RetriesExhaustedWithDetailsException {

    // This behavior is highly non-intuitive... it does not protect us against

    // 94-incompatible behavior, which is a timing issue because hasError, the below code

    // and setter of hasError are not synchronized. Perhaps it should be removed.

    if (ap.hasError()) {

      writeAsyncBuffer.add(put);

      backgroundFlushCommits(true);

    }

    validatePut(put);

    currentWriteBufferSize += put.heapSize();

    writeAsyncBuffer.add(put);

    while (currentWriteBufferSize > writeBufferSize) {

      backgroundFlushCommits(false);

    }

  }

  /**

   * Send the operations in the buffer to the servers. Does not wait for the server's answer.

   * If the is an error (max retried reach from a previous flush or bad operation), it tries to

   * send all operations in the buffer and sends an exception.

   * @param synchronous - if true, sends all the writes and wait for all of them to finish before

   *                     returning.

   */

  private void backgroundFlushCommits(boolean synchronous) throws

      InterruptedIOException, RetriesExhaustedWithDetailsException {

    try {

      if (!synchronous) {

        ap.submit(tableName, writeAsyncBuffer, true, null, false);

        if (ap.hasError()) {

          LOG.debug(tableName + ": One or more of the operations have failed -" +

              " waiting for all operation in progress to finish (successfully or not)");

        }

      }

      if (synchronous || ap.hasError()) {

        while (!writeAsyncBuffer.isEmpty()) {

          ap.submit(tableName, writeAsyncBuffer, true, null, false);

        }

        List<Row> failedRows = clearBufferOnFail ? null : writeAsyncBuffer;

        RetriesExhaustedWithDetailsException error = ap.waitForAllPreviousOpsAndReset(failedRows);

        if (error != null) {

          throw error;

        }

      }

    } finally {

      currentWriteBufferSize = 0;

      for (Row mut : writeAsyncBuffer) {

        if (mut instanceof Mutation) {

          currentWriteBufferSize += ((Mutation) mut).heapSize();

        }

      }

    }

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void mutateRow(final RowMutations rm) throws IOException {

    RegionServerCallable<Void> callable =

        new RegionServerCallable<Void>(connection, getName(), rm.getRow()) {

      @Override

      public Void call(int callTimeout) throws IOException {

        PayloadCarryingRpcController controller = rpcControllerFactory.newController();

        controller.setPriority(tableName);

        controller.setCallTimeout(callTimeout);

        try {

          RegionAction.Builder regionMutationBuilder = RequestConverter.buildRegionAction(

            getLocation().getRegionInfo().getRegionName(), rm);

          regionMutationBuilder.setAtomic(true);

          MultiRequest request =

            MultiRequest.newBuilder().addRegionAction(regionMutationBuilder.build()).build();

          getStub().multi(controller, request);

        } catch (ServiceException se) {

          throw ProtobufUtil.getRemoteException(se);

        }

        return null;

      }

    };

    rpcCallerFactory.<Void> newCaller().callWithRetries(callable, this.operationTimeout);

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public Result append(final Append append) throws IOException {

    if (append.numFamilies() == 0) {

      throw new IOException(