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.Closeable;
021import java.io.IOException;
022import java.util.List;
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 * Used to view region location information for a single HBase table. Obtain an instance from an
031 * {@link Connection}.
032 * @see ConnectionFactory
033 * @see Connection
034 * @see Table
035 * @since 0.99.0
036 */
037@InterfaceAudience.Public
038public interface RegionLocator extends Closeable {
039
040  /**
041   * Configuration for Region Locator's mode when meta replica is configured. Valid values are:
042   * HedgedRead, LoadBalance, None
043   */
044  String LOCATOR_META_REPLICAS_MODE = "hbase.locator.meta.replicas.mode";
045
046  /**
047   * Configuration for meta replica selector when Region Locator's LoadBalance mode is configured.
048   * The default value is org.apache.hadoop.hbase.client.CatalogReplicaLoadBalanceSimpleSelector.
049   */
050  String LOCATOR_META_REPLICAS_MODE_LOADBALANCE_SELECTOR =
051    "hbase.locator.meta.replicas.mode.loadbalance.selector";
052
053  /**
054   * Finds the region on which the given row is being served. Does not reload the cache.
055   * @param row Row to find.
056   * @return Location of the row.
057   * @throws IOException if a remote or network exception occurs
058   */
059  default HRegionLocation getRegionLocation(byte[] row) throws IOException {
060    return getRegionLocation(row, false);
061  }
062
063  /**
064   * Finds the region on which the given row is being served.
065   * @param row    Row to find.
066   * @param reload true to reload information or false to use cached information
067   * @return Location of the row.
068   * @throws IOException if a remote or network exception occurs
069   */
070  default HRegionLocation getRegionLocation(byte[] row, boolean reload) throws IOException {
071    return getRegionLocation(row, RegionInfo.DEFAULT_REPLICA_ID, reload);
072  }
073
074  /**
075   * Finds the region with the given replica id on which the given row is being served.
076   * @param row       Row to find.
077   * @param replicaId the replica id
078   * @return Location of the row.
079   * @throws IOException if a remote or network exception occurs
080   */
081  default HRegionLocation getRegionLocation(byte[] row, int replicaId) throws IOException {
082    return getRegionLocation(row, replicaId, false);
083  }
084
085  /**
086   * Finds the region with the given replica id on which the given row is being served.
087   * @param row       Row to find.
088   * @param replicaId the replica id
089   * @param reload    true to reload information or false to use cached information
090   * @return Location of the row.
091   * @throws IOException if a remote or network exception occurs
092   */
093  HRegionLocation getRegionLocation(byte[] row, int replicaId, boolean reload) throws IOException;
094
095  /**
096   * Find all the replicas for the region on which the given row is being served.
097   * @param row Row to find.
098   * @return Locations for all the replicas of the row.
099   * @throws IOException if a remote or network exception occurs
100   */
101  default List<HRegionLocation> getRegionLocations(byte[] row) throws IOException {
102    return getRegionLocations(row, false);
103  }
104
105  /**
106   * Find all the replicas for the region on which the given row is being served.
107   * @param row    Row to find.
108   * @param reload true to reload information or false to use cached information
109   * @return Locations for all the replicas of the row.
110   * @throws IOException if a remote or network exception occurs
111   */
112  List<HRegionLocation> getRegionLocations(byte[] row, boolean reload) throws IOException;
113
114  /**
115   * Clear all the entries in the region location cache.
116   * <p/>
117   * This may cause performance issue so use it with caution.
118   */
119  void clearRegionLocationCache();
120
121  /**
122   * Retrieves all of the regions associated with this table.
123   * <p/>
124   * Usually we will go to meta table directly in this method so there is no {@code reload}
125   * parameter.
126   * <p/>
127   * Notice that the location for region replicas other than the default replica are also returned.
128   * @return a {@link List} of all regions associated with this table.
129   * @throws IOException if a remote or network exception occurs
130   */
131  List<HRegionLocation> getAllRegionLocations() throws IOException;
132
133  /**
134   * Gets the starting row key for every region in the currently open table.
135   * <p>
136   * This is mainly useful for the MapReduce integration.
137   * @return Array of region starting row keys
138   * @throws IOException if a remote or network exception occurs
139   */
140  default byte[][] getStartKeys() throws IOException {
141    return getStartEndKeys().getFirst();
142  }
143
144  /**
145   * Gets the ending row key for every region in the currently open table.
146   * <p>
147   * This is mainly useful for the MapReduce integration.
148   * @return Array of region ending row keys
149   * @throws IOException if a remote or network exception occurs
150   */
151  default byte[][] getEndKeys() throws IOException {
152    return getStartEndKeys().getSecond();
153  }
154
155  /**
156   * Gets the starting and ending row keys for every region in the currently open table.
157   * <p>
158   * This is mainly useful for the MapReduce integration.
159   * @return Pair of arrays of region starting and ending row keys
160   * @throws IOException if a remote or network exception occurs
161   */
162  default Pair<byte[][], byte[][]> getStartEndKeys() throws IOException {
163    List<HRegionLocation> regions = getAllRegionLocations().stream()
164      .filter(loc -> RegionReplicaUtil.isDefaultReplica(loc.getRegion()))
165      .collect(Collectors.toList());
166    byte[][] startKeys = new byte[regions.size()][];
167    byte[][] endKeys = new byte[regions.size()][];
168    for (int i = 0, n = regions.size(); i < n; i++) {
169      RegionInfo region = regions.get(i).getRegion();
170      startKeys[i] = region.getStartKey();
171      endKeys[i] = region.getEndKey();
172    }
173    return Pair.newPair(startKeys, endKeys);
174  }
175
176  /**
177   * Gets the fully qualified table name instance of this table.
178   */
179  TableName getName();
180}