HBASE-11657 Put HTable region methods in an interface (Carter Page)

hbase-client/src/main/java/org/apache/hadoop/hbase/HRegionLocation.java

@@ -19,6 +19,7 @@
 package org.apache.hadoop.hbase;
 
 import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceStability;
 import org.apache.hadoop.hbase.util.Addressing;
 
 /**
@@ -31,10 +32,11 @@ import org.apache.hadoop.hbase.util.Addressing;
  * On a big cluster, each client will have thousands of instances of this object, often
  *  100 000 of them if not million. It's important to keep the object size as small
  *  as possible.
- * <br>This interface has been marked InterfaceAudience.Public in 0.96 and 0.98, it is
+ *
- * no longer the case.
+ * <br>This interface has been marked InterfaceAudience.Public in 0.96 and 0.98.
  */
-@InterfaceAudience.Private
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
 public class HRegionLocation implements Comparable<HRegionLocation> {
   private final HRegionInfo regionInfo;
   private final ServerName serverName;

hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionAdapter.java

@@ -111,6 +111,11 @@ class ConnectionAdapter implements ClusterConnection {
     return wrappedConnection.getTable(tableName, pool);
   }
 
+  @Override
+  public RegionLocator getRegionLocator(TableName tableName) throws IOException {
+    return wrappedConnection.getRegionLocator(tableName);
+  }
+
   @Override
   public Admin getAdmin() throws IOException {
     return wrappedConnection.getAdmin();

hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionManager.java

@@ -713,6 +713,14 @@ class ConnectionManager {
       return new HTable(tableName, this, pool);
     }
 
+    @Override
+    public RegionLocator getRegionLocator(TableName tableName) throws IOException {
+      if (managed) {
+        throw new IOException("The connection has to be unmanaged.");
+      }
+      return new HTable(tableName, this, getBatchPool());
+    }
+
     @Override
     public Admin getAdmin() throws IOException {
       if (managed) {

hbase-client/src/main/java/org/apache/hadoop/hbase/client/HConnection.java

@@ -153,12 +153,26 @@ public interface HConnection extends Abortable, Closeable {
    */
   public HTableInterface getTable(TableName tableName, ExecutorService pool)  throws IOException;
 
+  /**
+   * Retrieve a RegionLocator implementation to inspect region information on a table. The returned
+   * RegionLocator is not thread-safe, so a new instance should be created for each using thread.
+   *
+   * This is a lightweight operation.  Pooling or caching of the returned RegionLocator is neither
+   * required nor desired.
+   *
+   * RegionLocator needs to be unmanaged
+   * (created with {@link HConnectionManager#createConnection(Configuration)}).
+   *
+   * @param tableName Name of the table who's region is to be examined
+   * @return A RegionLocator instance
+   */
+  public RegionLocator getRegionLocator(TableName tableName) throws IOException;
+
   /**
    * Retrieve an Admin implementation to administer an HBase cluster.
    * The returned Admin is not guaranteed to be thread-safe.  A new instance should be created for
    * each using thread.  This is a lightweight operation.  Pooling or caching of the returned
    * Admin is not recommended.  Note that HConnection needs to be unmanaged
-   * (created with {@link HConnectionManager#createConnection(Configuration)}).
    *
    * @return an Admin instance for cluster administration
    */

hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java

@@ -123,7 +123,7 @@ import com.google.protobuf.ServiceException;
  */
 @InterfaceAudience.Public
 @InterfaceStability.Stable
-public class HTable implements HTableInterface {
+public class HTable implements HTableInterface, RegionLocator {
   private static final Log LOG = LogFactory.getLog(HTable.class);
   protected ClusterConnection connection;
   private final TableName tableName;
@@ -498,30 +498,27 @@ public class HTable implements HTableInterface {
    * @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);
   }
 
   /**
-   * Finds the region on which the given row is being served. Does not reload the cache.
+   * {@inheritDoc}
-   * @param row Row to find.
-   * @return Location of the row.
-   * @throws IOException if a remote or network exception occurs
    */
+  @Override
   public HRegionLocation getRegionLocation(final byte [] row)
   throws IOException {
     return connection.getRegionLocation(tableName, row, false);
   }
 
   /**
-   * Finds the region on which the given row is being served.
+   * {@inheritDoc}
-   * @param row Row to find.
-   * @param reload true to reload information or false to use cached information
-   * @return Location of the row.
-   * @throws IOException if a remote or network exception occurs
    */
+  @Override
   public HRegionLocation getRegionLocation(final byte [] row, boolean reload)
   throws IOException {
     return connection.getRegionLocation(tableName, row, reload);
@@ -599,36 +596,25 @@ public class HTable implements HTableInterface {
   }
 
   /**
-   * Gets the starting row key for every region in the currently open table.
+   * {@inheritDoc}
-   * <p>
-   * This is mainly useful for the MapReduce integration.
-   * @return Array of region starting row keys
-   * @throws IOException if a remote or network exception occurs
    */
+  @Override
   public byte [][] getStartKeys() throws IOException {
     return getStartEndKeys().getFirst();
   }
 
   /**
-   * Gets the ending row key for every region in the currently open table.
+   * {@inheritDoc}
-   * <p>
-   * This is mainly useful for the MapReduce integration.
-   * @return Array of region ending row keys
-   * @throws IOException if a remote or network exception occurs
    */
+  @Override
   public byte[][] getEndKeys() throws IOException {
     return getStartEndKeys().getSecond();
   }
 
   /**
-   * Gets the starting and ending row keys for every region in the currently
+   * {@inheritDoc}
-   * open table.
-   * <p>
-   * This is mainly useful for the MapReduce integration.
-   * @return Pair of arrays of region starting and ending row keys
-   * @throws IOException if a remote or network exception occurs
    */
-  // TODO: these are not in HTableInterface. Should we add them there or move these to HBaseAdmin?
+  @Override
   public Pair<byte[][],byte[][]> getStartEndKeys() throws IOException {
 
     List<RegionLocations> regions = listRegionLocations();
@@ -661,7 +647,7 @@ public class HTable implements HTableInterface {
    */
   @Deprecated
   public NavigableMap<HRegionInfo, ServerName> getRegionLocations() throws IOException {
-    // TODO: Odd that this returns a Map of HRI to SN whereas getRegionLocation, singular, returns an HRegionLocation.
+    // 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);
   }
 

hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java

@@ -0,0 +1,89 @@
+/**
+ *
+ * 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.
+ */
+package org.apache.hadoop.hbase.client;
+
+import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceStability;
+import org.apache.hadoop.hbase.HRegionLocation;
+import org.apache.hadoop.hbase.TableName;
+import org.apache.hadoop.hbase.util.Pair;
+
+import java.io.Closeable;
+import java.io.IOException;
+
+/**
+ * Used to view region location information for a single HBase table.
+ * Obtain an instance from an {@link HConnection}.
+ *
+ * @since 0.99.0
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
+public interface RegionLocator extends Closeable {
+  /**
+   * Finds the region on which the given row is being served. Does not reload the cache.
+   * @param row Row to find.
+   * @return Location of the row.
+   * @throws IOException if a remote or network exception occurs
+   */
+  public HRegionLocation getRegionLocation(final byte [] row) throws IOException;
+
+  /**
+   * Finds the region on which the given row is being served.
+   * @param row Row to find.
+   * @param reload true to reload information or false to use cached information
+   * @return Location of the row.
+   * @throws IOException if a remote or network exception occurs
+   */
+  public HRegionLocation getRegionLocation(final byte [] row, boolean reload)
+    throws IOException;
+
+  /**
+   * Gets the starting row key for every region in the currently open table.
+   * <p>
+   * This is mainly useful for the MapReduce integration.
+   * @return Array of region starting row keys
+   * @throws IOException if a remote or network exception occurs
+   */
+  public byte [][] getStartKeys() throws IOException;
+
+  /**
+   * Gets the ending row key for every region in the currently open table.
+   * <p>
+   * This is mainly useful for the MapReduce integration.
+   * @return Array of region ending row keys
+   * @throws IOException if a remote or network exception occurs
+   */
+  public byte[][] getEndKeys() throws IOException;
+
+  /**
+   * Gets the starting and ending row keys for every region in the currently
+   * open table.
+   * <p>
+   * This is mainly useful for the MapReduce integration.
+   * @return Pair of arrays of region starting and ending row keys
+   * @throws IOException if a remote or network exception occurs
+   */
+  public Pair<byte[][],byte[][]> getStartEndKeys() throws IOException;
+
+  /**
+   * Gets the fully qualified table name instance of this table.
+   */
+  TableName getName();
+}

hbase-server/src/main/java/org/apache/hadoop/hbase/client/CoprocessorHConnection.java

@@ -140,6 +140,11 @@ class CoprocessorHConnection implements ClusterConnection {
     return delegate.getTable(tableName, pool);
   }
 
+  @Override
+  public RegionLocator getRegionLocator(TableName tableName) throws IOException {
+    return delegate.getRegionLocator(tableName);
+  }
+
   @Override
   public Admin getAdmin() throws IOException { return delegate.getAdmin(); }
 

hbase-server/src/test/java/org/apache/hadoop/hbase/client/HConnectionTestingUtility.java

@@ -83,7 +83,7 @@ public class HConnectionTestingUtility {
    * @param sn ServerName to include in the region location returned by this
    * <code>connection</code>
    * @param hri HRegionInfo to include in the location returned when
-   * getRegionLocation is called on the mocked connection
+   * getRegionLocator is called on the mocked connection
    * @return Mock up a connection that returns a {@link Configuration} when
    * {@link HConnection#getConfiguration()} is called, a 'location' when
    * {@link HConnection#getRegionLocation(org.apache.hadoop.hbase.TableName, byte[], boolean)} is called,

hbase-server/src/test/java/org/apache/hadoop/hbase/client/TestFromClientSide.java

@@ -5167,7 +5167,7 @@ public class TestFromClientSide {
 
   @Test
   /**
-   * Tests the non cached version of getRegionLocation by moving a region.
+   * Tests the non cached version of getRegionLocator by moving a region.
    */
   public void testNonCachedGetRegionLocation() throws Exception {
     // Test Initialization.