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.io.IOException;
021import java.util.List;
022import java.util.concurrent.CompletableFuture;
023import java.util.stream.Collectors;
024import org.apache.hadoop.hbase.HRegionLocation;
025import org.apache.hadoop.hbase.TableName;
026import org.apache.hadoop.hbase.util.Pair;
027import org.apache.yetus.audience.InterfaceAudience;
028
029/**
030 * The asynchronous version of RegionLocator.
031 * <p>
032 * Usually the implementations will not throw any exception directly, you need to get the exception
033 * from the returned {@link CompletableFuture}.
034 * @since 2.0.0
035 */
036@InterfaceAudience.Public
037public interface AsyncTableRegionLocator {
038
039  /**
040   * Gets the fully qualified table name instance of the table whose region we want to locate.
041   */
042  TableName getName();
043
044  /**
045   * Finds the region on which the given row is being served. Does not reload the cache.
046   * <p/>
047   * Returns the location of the region to which the row belongs.
048   * @param row Row to find.
049   */
050  default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row) {
051    return getRegionLocation(row, false);
052  }
053
054  /**
055   * Finds the region on which the given row is being served.
056   * <p/>
057   * Returns the location of the region to which the row belongs.
058   * @param row Row to find.
059   * @param reload true to reload information or false to use cached information
060   */
061  default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, boolean reload) {
062    return getRegionLocation(row, RegionInfo.DEFAULT_REPLICA_ID, reload);
063  }
064
065  /**
066   * Finds the region with the given <code>replicaId</code> on which the given row is being served.
067   * <p/>
068   * Returns the location of the region with the given <code>replicaId</code> to which the row
069   * belongs.
070   * @param row Row to find.
071   * @param replicaId the replica id of the region
072   */
073  default CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId) {
074    return getRegionLocation(row, replicaId, false);
075  }
076
077  /**
078   * Finds the region with the given <code>replicaId</code> on which the given row is being served.
079   * <p/>
080   * Returns the location of the region with the given <code>replicaId</code> to which the row
081   * belongs.
082   * @param row Row to find.
083   * @param replicaId the replica id of the region
084   * @param reload true to reload information or false to use cached information
085   */
086  CompletableFuture<HRegionLocation> getRegionLocation(byte[] row, int replicaId, boolean reload);
087
088  /**
089   * Find all the replicas for the region on which the given row is being served.
090   * @param row Row to find.
091   * @return Locations for all the replicas of the row.
092   * @throws IOException if a remote or network exception occurs
093   */
094  default CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row) {
095    return getRegionLocations(row, false);
096  }
097
098  /**
099   * Find all the replicas for the region on which the given row is being served.
100   * @param row Row to find.
101   * @param reload true to reload information or false to use cached information
102   * @return Locations for all the replicas of the row.
103   * @throws IOException if a remote or network exception occurs
104   */
105  CompletableFuture<List<HRegionLocation>> getRegionLocations(byte[] row, boolean reload);
106
107  /**
108   * Retrieves all of the regions associated with this table.
109   * <p/>
110   * Usually we will go to meta table directly in this method so there is no {@code reload}
111   * parameter.
112   * <p/>
113   * Notice that the location for region replicas other than the default replica are also returned.
114   * @return a {@link List} of all regions associated with this table.
115   */
116  CompletableFuture<List<HRegionLocation>> getAllRegionLocations();
117
118  /**
119   * Gets the starting row key for every region in the currently open table.
120   * <p>
121   * This is mainly useful for the MapReduce integration.
122   * @return Array of region starting row keys
123   * @throws IOException if a remote or network exception occurs
124   */
125  default CompletableFuture<List<byte[]>> getStartKeys() throws IOException {
126    return getStartEndKeys().thenApply(
127      startEndKeys -> startEndKeys.stream().map(Pair::getFirst).collect(Collectors.toList()));
128  }
129
130  /**
131   * Gets the ending row key for every region in the currently open table.
132   * <p>
133   * This is mainly useful for the MapReduce integration.
134   * @return Array of region ending row keys
135   * @throws IOException if a remote or network exception occurs
136   */
137  default CompletableFuture<List<byte[]>> getEndKeys() throws IOException {
138    return getStartEndKeys().thenApply(
139      startEndKeys -> startEndKeys.stream().map(Pair::getSecond).collect(Collectors.toList()));
140  }
141
142  /**
143   * Gets the starting and ending row keys for every region in the currently open table.
144   * <p>
145   * This is mainly useful for the MapReduce integration.
146   * @return Pair of arrays of region starting and ending row keys
147   * @throws IOException if a remote or network exception occurs
148   */
149  default CompletableFuture<List<Pair<byte[], byte[]>>> getStartEndKeys() throws IOException {
150    return getAllRegionLocations().thenApply(
151      locs -> locs.stream().filter(loc -> RegionReplicaUtil.isDefaultReplica(loc.getRegion()))
152        .map(HRegionLocation::getRegion).map(r -> Pair.newPair(r.getStartKey(), r.getEndKey()))
153        .collect(Collectors.toList()));
154  }
155
156  /**
157   * Clear all the entries in the region location cache.
158   * <p/>
159   * This may cause performance issue so use it with caution.
160   */
161  void clearRegionLocationCache();
162}