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