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   * Finds the region on which the given row is being served. Does not reload the cache.
042   * @param row Row to find.
043   * @return Location of the row.
044   * @throws IOException if a remote or network exception occurs
045   */
046  default HRegionLocation getRegionLocation(byte[] row) throws IOException {
047    return getRegionLocation(row, false);
048  }
049
050  /**
051   * Finds the region on which the given row is being served.
052   * @param row Row to find.
053   * @param reload true to reload information or false to use cached information
054   * @return Location of the row.
055   * @throws IOException if a remote or network exception occurs
056   */
057  default HRegionLocation getRegionLocation(byte[] row, boolean reload) throws IOException {
058    return getRegionLocation(row, RegionInfo.DEFAULT_REPLICA_ID, reload);
059  }
060
061  /**
062   * Finds the region with the given replica id on which the given row is being served.
063   * @param row Row to find.
064   * @param replicaId the replica id
065   * @return Location of the row.
066   * @throws IOException if a remote or network exception occurs
067   */
068  default HRegionLocation getRegionLocation(byte[] row, int replicaId) throws IOException {
069    return getRegionLocation(row, replicaId, false);
070  }
071
072  /**
073   * Finds the region with the given replica id on which the given row is being served.
074   * @param row Row to find.
075   * @param replicaId the replica id
076   * @param reload true to reload information or false to use cached information
077   * @return Location of the row.
078   * @throws IOException if a remote or network exception occurs
079   */
080  HRegionLocation getRegionLocation(byte[] row, int replicaId, boolean reload) throws IOException;
081
082  /**
083   * Find all the replicas for the region on which the given row is being served.
084   * @param row Row to find.
085   * @return Locations for all the replicas of the row.
086   * @throws IOException if a remote or network exception occurs
087   */
088  default List<HRegionLocation> getRegionLocations(byte[] row) throws IOException {
089    return getRegionLocations(row, false);
090  }
091
092  /**
093   * Find all the replicas for the region on which the given row is being served.
094   * @param row Row to find.
095   * @param reload true to reload information or false to use cached information
096   * @return Locations for all the replicas of the row.
097   * @throws IOException if a remote or network exception occurs
098   */
099  List<HRegionLocation> getRegionLocations(byte[] row, boolean reload) throws IOException;
100
101  /**
102   * Clear all the entries in the region location cache.
103   * <p/>
104   * This may cause performance issue so use it with caution.
105   */
106  void clearRegionLocationCache();
107
108  /**
109   * Retrieves all of the regions associated with this table.
110   * <p/>
111   * Usually we will go to meta table directly in this method so there is no {@code reload}
112   * parameter.
113   * <p/>
114   * Notice that the location for region replicas other than the default replica are also returned.
115   * @return a {@link List} of all regions associated with this table.
116   * @throws IOException if a remote or network exception occurs
117   */
118  List<HRegionLocation> getAllRegionLocations() throws IOException;
119
120  /**
121   * Gets the starting row key for every region in the currently open table.
122   * <p>
123   * This is mainly useful for the MapReduce integration.
124   * @return Array of region starting row keys
125   * @throws IOException if a remote or network exception occurs
126   */
127  default byte[][] getStartKeys() throws IOException {
128    return getStartEndKeys().getFirst();
129  }
130
131  /**
132   * Gets the ending row key for every region in the currently open table.
133   * <p>
134   * This is mainly useful for the MapReduce integration.
135   * @return Array of region ending row keys
136   * @throws IOException if a remote or network exception occurs
137   */
138  default byte[][] getEndKeys() throws IOException {
139    return getStartEndKeys().getSecond();
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 Pair<byte[][], byte[][]> getStartEndKeys() throws IOException {
150    List<HRegionLocation> regions = getAllRegionLocations().stream()
151      .filter(loc -> RegionReplicaUtil.isDefaultReplica(loc.getRegion()))
152      .collect(Collectors.toList());
153    byte[][] startKeys = new byte[regions.size()][];
154    byte[][] endKeys = new byte[regions.size()][];
155    for (int i = 0, n = regions.size(); i < n; i++) {
156      RegionInfo region = regions.get(i).getRegion();
157      startKeys[i] = region.getStartKey();
158      endKeys[i] = region.getEndKey();
159    }
160    return Pair.newPair(startKeys, endKeys);
161  }
162
163  /**
164   * Gets the fully qualified table name instance of this table.
165   */
166  TableName getName();
167}