Package org.apache.hadoop.hbase.client

Interface RegionLocator

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
RegionLocatorOverAsyncTableRegionLocator, SnapshotRegionLocator
@Public public interface RegionLocator extends Closeable
Used to view region location information for a single HBase table. Obtain an instance from an Connection.
Since:
0.99.0
See Also:

  • Field Details

  • Method Details

    • getRegionLocation

      default HRegionLocation getRegionLocation(byte[] row) throws IOException
      Finds the region on which the given row is being served. Does not reload the cache.
      Parameters:
      row - Row to find.
      Returns:
      Location of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocation

      default HRegionLocation getRegionLocation(byte[] row, boolean reload) throws IOException
      Finds the region on which the given row is being served.
      Parameters:
      row - Row to find.
      reload - true to reload information or false to use cached information
      Returns:
      Location of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocation

      default HRegionLocation getRegionLocation(byte[] row, int replicaId) throws IOException
      Finds the region with the given replica id on which the given row is being served.
      Parameters:
      row - Row to find.
      replicaId - the replica id
      Returns:
      Location of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocation

      HRegionLocation getRegionLocation(byte[] row, int replicaId, boolean reload) throws IOException
      Finds the region with the given replica id on which the given row is being served.
      Parameters:
      row - Row to find.
      replicaId - the replica id
      reload - true to reload information or false to use cached information
      Returns:
      Location of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocations

      default List<HRegionLocation> getRegionLocations(byte[] row) throws IOException
      Find all the replicas for the region on which the given row is being served.
      Parameters:
      row - Row to find.
      Returns:
      Locations for all the replicas of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocations

      List<HRegionLocation> getRegionLocations(byte[] row, boolean reload) throws IOException
      Find all the replicas for the region on which the given row is being served.
      Parameters:
      row - Row to find.
      reload - true to reload information or false to use cached information
      Returns:
      Locations for all the replicas of the row.
      Throws:
      IOException - if a remote or network exception occurs

    • clearRegionLocationCache

      void clearRegionLocationCache()
      Clear all the entries in the region location cache.

      This may cause performance issue so use it with caution.

    • getAllRegionLocations

      List<HRegionLocation> getAllRegionLocations() throws IOException
      Retrieves all of the regions associated with this table.

      Usually we will go to meta table directly in this method so there is no reload parameter.

      Notice that the location for region replicas other than the default replica are also returned.

      Returns:
      a List of all regions associated with this table.
      Throws:
      IOException - if a remote or network exception occurs

    • getRegionLocationsPage

      default List<HRegionLocation> getRegionLocationsPage(byte[] startKey, int limit) throws IOException
      Bulk lookup of region locations from hbase:meta in a single RPC, starting at startKey (region start-key boundary, inclusive) and returning at most limit regions in start-key order.

      The returned list includes all replicas of each region (matching getAllRegionLocations()), and the result is also written to the connection's region location cache.

      Ordering: regions are returned in ascending region start-key order (the natural order of hbase:meta rows for a single table). Within each region, replicas are returned in ascending replica-id order (replica 0, then 1, then 2, ...). Split parents are filtered out, which may cause a page to contain fewer than limit regions but never disturbs ordering of the survivors.

      To page through all regions of a table, call repeatedly passing last.getRegion().getEndKey() as the next startKey, where last is the final element of the previous response. All replicas of a region share the same RegionInfo, so the last entry's end key is the correct cursor regardless of which replica it is. Pass null for the first call. Stop paging when the returned list is empty or when the last region's end key is HConstants.EMPTY_END_ROW (zero-length) - that signals the end of the table; passing it back in would re-scan from the beginning since by convention an empty start key means "from the first region".

      Unlike getAllRegionLocations(), this method performs at most one RPC against hbase:meta per invocation, so its latency is bounded by limit rather than table size. The single-RPC behavior is best-effort: if the response would exceed hbase.client.scanner.max.result.size (default 2 MB), the server may split the slice across multiple ScannerNext RPCs. For typical meta row sizes and default caching this rarely fires, but callers passing large limit values against clusters with replicas or heavy meta rows should treat single-RPC as a soft guarantee, not absolute.

      This method is optional. Implementations that cannot support paginated lookups should throw UnsupportedOperationException (the default behavior); callers should fall back to getAllRegionLocations() in that case.

      Parameters:
      startKey - region start-key to begin scanning from (inclusive); null or empty starts from the first region
      limit - maximum number of regions to return. If <= 0, falls back to hbase.meta.scanner.caching - this is a SOFT cap on a single page, NOT "all regions"; tables larger than the cap still require the caller to keep paging via last.getRegion().getEndKey().
      Returns:
      up to limit HRegionLocations in start-key order, possibly empty when no more regions exist
      Throws:
      IOException - if a remote or network exception occurs
      UnsupportedOperationException - if this implementation does not support paginated lookups

    • getStartKeys

      default byte[][] getStartKeys() throws IOException
      Gets the starting row key for every region in the currently open table.

      This is mainly useful for the MapReduce integration.

      Returns:
      Array of region starting row keys
      Throws:
      IOException - if a remote or network exception occurs

    • getEndKeys

      default byte[][] getEndKeys() throws IOException
      Gets the ending row key for every region in the currently open table.

      This is mainly useful for the MapReduce integration.

      Returns:
      Array of region ending row keys
      Throws:
      IOException - if a remote or network exception occurs

    • getStartEndKeys

      default Pair<byte[][],byte[][]> getStartEndKeys() throws IOException
      Gets the starting and ending row keys for every region in the currently open table.

      This is mainly useful for the MapReduce integration.

      Returns:
      Pair of arrays of region starting and ending row keys
      Throws:
      IOException - if a remote or network exception occurs

    • getName

      TableName getName()
      Gets the fully qualified table name instance of this table.