001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.client; 019 020import java.util.List; 021import java.util.concurrent.CompletableFuture; 022import java.util.stream.Collectors; 023import org.apache.hadoop.hbase.HRegionLocation; 024import org.apache.hadoop.hbase.TableName; 025import org.apache.hadoop.hbase.util.Pair; 026import org.apache.yetus.audience.InterfaceAudience; 027 028/** 029 * The asynchronous version of RegionLocator. 030 * <p> 031 * Usually the implementations will not throw any exception directly, you need to get the exception 032 * from the returned {@link CompletableFuture}. 033 * @since 2.0.0 034 */ 035@InterfaceAudience.Public 036public interface AsyncTableRegionLocator { 037 038 /** 039 * Gets the fully qualified table name instance of the table whose region we want to locate. 040 */ 041 TableName getName(); 042 043 /** 044 * Finds the region on which the given row is being served. Does not reload the cache. 045 * <p/> 046 * Returns the location of the region to which the row belongs. 047 * @param row Row to find. 048 */ 049 default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row) { 050 return getRegionLocation(row, false); 051 } 052 053 /** 054 * Finds the region on which the given row is being served. 055 * <p/> 056 * Returns the location of the region to which the row belongs. 057 * @param row Row to find. 058 * @param reload true to reload information or false to use cached information 059 */ 060 default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, boolean reload) { 061 return getRegionLocation(row, RegionInfo.DEFAULT_REPLICA_ID, reload); 062 } 063 064 /** 065 * Finds the region with the given <code>replicaId</code> on which the given row is being served. 066 * <p/> 067 * Returns the location of the region with the given <code>replicaId</code> to which the row 068 * belongs. 069 * @param row Row to find. 070 * @param replicaId the replica id of the region 071 */ 072 default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId) { 073 return getRegionLocation(row, replicaId, false); 074 } 075 076 /** 077 * Finds the region with the given <code>replicaId</code> on which the given row is being served. 078 * <p/> 079 * Returns the location of the region with the given <code>replicaId</code> to which the row 080 * belongs. 081 * @param row Row to find. 082 * @param replicaId the replica id of the region 083 * @param reload true to reload information or false to use cached information 084 */ 085 CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId, boolean reload); 086 087 /** 088 * Find all the replicas for the region on which the given row is being served. 089 * @param row Row to find. 090 * @return Locations for all the replicas of the row. 091 */ 092 default CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row) { 093 return getRegionLocations(row, false); 094 } 095 096 /** 097 * Find all the replicas for the region on which the given row is being served. 098 * @param row Row to find. 099 * @param reload true to reload information or false to use cached information 100 * @return Locations for all the replicas of the row. 101 */ 102 CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row, boolean reload); 103 104 /** 105 * Retrieves all of the regions associated with this table. 106 * <p/> 107 * Usually we will go to meta table directly in this method so there is no {@code reload} 108 * parameter. 109 * <p/> 110 * Notice that the location for region replicas other than the default replica are also returned. 111 * @return a {@link List} of all regions associated with this table. 112 */ 113 CompletableFuture<List<HRegionLocation>> getAllRegionLocations(); 114 115 /** 116 * Gets the starting row key for every region in the currently open table. 117 * <p> 118 * This is mainly useful for the MapReduce integration. 119 * @return Array of region starting row keys 120 */ 121 default CompletableFuture<List<byte[]>> getStartKeys() { 122 return getStartEndKeys().thenApply( 123 startEndKeys -> startEndKeys.stream().map(Pair::getFirst).collect(Collectors.toList())); 124 } 125 126 /** 127 * Gets the ending row key for every region in the currently open table. 128 * <p> 129 * This is mainly useful for the MapReduce integration. 130 * @return Array of region ending row keys 131 */ 132 default CompletableFuture<List<byte[]>> getEndKeys() { 133 return getStartEndKeys().thenApply( 134 startEndKeys -> startEndKeys.stream().map(Pair::getSecond).collect(Collectors.toList())); 135 } 136 137 /** 138 * Gets the starting and ending row keys for every region in the currently open table. 139 * <p> 140 * This is mainly useful for the MapReduce integration. 141 * @return Pair of arrays of region starting and ending row keys 142 */ 143 default CompletableFuture<List<Pair<byte[], byte[]>>> getStartEndKeys() { 144 return getAllRegionLocations().thenApply( 145 locs -> locs.stream().filter(loc -> RegionReplicaUtil.isDefaultReplica(loc.getRegion())) 146 .map(HRegionLocation::getRegion).map(r -> Pair.newPair(r.getStartKey(), r.getEndKey())) 147 .collect(Collectors.toList())); 148 } 149 150 /** 151 * Clear all the entries in the region location cache. 152 * <p/> 153 * This may cause performance issue so use it with caution. 154 */ 155 void clearRegionLocationCache(); 156}