Package org.apache.hadoop.hbase.client

Interface AsyncTableRegionLocator

All Known Implementing Classes:
AsyncTableRegionLocatorImpl
@Public public interface AsyncTableRegionLocator
The asynchronous version of RegionLocator.

Usually the implementations will not throw any exception directly, you need to get the exception from the returned CompletableFuture.

Since:
2.0.0

  • Method Details

    • getName

      TableName getName()
      Gets the fully qualified table name instance of the table whose region we want to locate.

    • getRegionLocation

      default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row)
      Finds the region on which the given row is being served. Does not reload the cache.

      Returns the location of the region to which the row belongs.

      Parameters:
      row - Row to find.

    • getRegionLocation

      default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, boolean reload)
      Finds the region on which the given row is being served.

      Returns the location of the region to which the row belongs.

      Parameters:
      row - Row to find.
      reload - true to reload information or false to use cached information

    • getRegionLocation

      default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId)
      Finds the region with the given replicaId on which the given row is being served.

      Returns the location of the region with the given replicaId to which the row belongs.

      Parameters:
      row - Row to find.
      replicaId - the replica id of the region

    • getRegionLocation

      CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId, boolean reload)
      Finds the region with the given replicaId on which the given row is being served.

      Returns the location of the region with the given replicaId to which the row belongs.

      Parameters:
      row - Row to find.
      replicaId - the replica id of the region
      reload - true to reload information or false to use cached information

    • getRegionLocations

      default CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row)
      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.

    • getRegionLocations

      CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row, boolean reload)
      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.

    • getAllRegionLocations

      CompletableFuture<List<HRegionLocation>> getAllRegionLocations()
      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.

    • getRegionLocationsPage

      default CompletableFuture<List<HRegionLocation>> getRegionLocationsPage(byte[] startKey, int limit)
      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. Note that this method does not coordinate with other in-flight meta lookups on the connection - aggregate pacing across concurrent callers is the caller's responsibility.

      This method is optional. Implementations that cannot support paginated lookups will return a future that completes exceptionally with 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; errors are reported via the returned future

    • getStartKeys

      default CompletableFuture<List<byte[]>> getStartKeys()
      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

    • getEndKeys

      default CompletableFuture<List<byte[]>> getEndKeys()
      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

    • getStartEndKeys

      default CompletableFuture<List<Pair<byte[],byte[]>>> getStartEndKeys()
      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

    • clearRegionLocationCache

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

      This may cause performance issue so use it with caution.