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}