View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  package org.apache.hadoop.hbase.client;
20  
21  import java.io.IOException;
22  import java.util.List;
23  
24  import org.apache.hadoop.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.HRegionLocation;
26  import org.apache.hadoop.hbase.MasterNotRunningException;
27  import org.apache.hadoop.hbase.RegionLocations;
28  import org.apache.hadoop.hbase.ServerName;
29  import org.apache.hadoop.hbase.TableName;
30  import org.apache.hadoop.hbase.ZooKeeperConnectionException;
31  import org.apache.hadoop.hbase.protobuf.generated.AdminProtos.AdminService;
32  import org.apache.hadoop.hbase.protobuf.generated.ClientProtos.ClientService;
33  import org.apache.hadoop.hbase.protobuf.generated.MasterProtos.MasterService;
34  
35  /** Internal methods on HConnection that should not be used by user code. */
36  @InterfaceAudience.Private
37  // NOTE: Although this class is public, this class is meant to be used directly from internal
38  // classes and unit tests only.
39  public interface ClusterConnection extends HConnection {
40  
41    /** @return - true if the master server is running */
42    @Override
43    boolean isMasterRunning()
44        throws MasterNotRunningException, ZooKeeperConnectionException;
45  
46    /**
47     * Use this api to check if the table has been created with the specified number of
48     * splitkeys which was used while creating the given table.
49     * Note : If this api is used after a table's region gets splitted, the api may return
50     * false.
51     * @param tableName
52     *          tableName
53     * @param splitKeys
54     *          splitKeys used while creating table
55     * @throws IOException
56     *           if a remote or network exception occurs
57     */
58    @Override
59    boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws
60        IOException;
61  
62    /**
63     * Find the location of the region of <i>tableName</i> that <i>row</i>
64     * lives in.
65     * @param tableName name of the table <i>row</i> is in
66     * @param row row key you're trying to find the region of
67     * @return HRegionLocation that describes where to find the region in
68     * question
69     * @throws IOException if a remote or network exception occurs
70     */
71    @Override
72    public HRegionLocation locateRegion(final TableName tableName,
73        final byte [] row) throws IOException;
74  
75    /**
76     * Allows flushing the region cache.
77     */
78    @Override
79    void clearRegionCache();
80  
81    /**
82     * Allows flushing the region cache of all locations that pertain to
83     * <code>tableName</code>
84     * @param tableName Name of the table whose regions we are to remove from
85     * cache.
86     */
87    @Override
88    void clearRegionCache(final TableName tableName);
89  
90    /**
91     * Deletes cached locations for the specific region.
92     * @param location The location object for the region, to be purged from cache.
93     */
94    @Override
95    void deleteCachedRegionLocation(final HRegionLocation location);
96  
97    /**
98     * Find the location of the region of <i>tableName</i> that <i>row</i>
99     * lives in, ignoring any value that might be in the cache.
100    * @param tableName name of the table <i>row</i> is in
101    * @param row row key you're trying to find the region of
102    * @return HRegionLocation that describes where to find the region in
103    * question
104    * @throws IOException if a remote or network exception occurs
105    */
106   @Override
107   HRegionLocation relocateRegion(final TableName tableName,
108       final byte [] row) throws IOException;
109 
110   /**
111    * Find the location of the region of <i>tableName</i> that <i>row</i>
112    * lives in, ignoring any value that might be in the cache.
113    * @param tableName name of the table <i>row</i> is in
114    * @param row row key you're trying to find the region of
115    * @param replicaId the replicaId of the region
116    * @return HRegionLocation that describes where to find the region in
117    * question
118    * @throws IOException if a remote or network exception occurs
119    */
120   HRegionLocation relocateRegion(final TableName tableName,
121       final byte [] row, int replicaId) throws IOException;
122 
123   /**
124    * Update the location cache. This is used internally by HBase, in most cases it should not be
125    *  used by the client application.
126    * @param tableName the table name
127    * @param regionName the region name
128    * @param rowkey the row
129    * @param exception the exception if any. Can be null.
130    * @param source the previous location
131    */
132   @Override
133   void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey,
134                                     Object exception, ServerName source);
135 
136 
137   /**
138    * Gets the location of the region of <i>regionName</i>.
139    * @param regionName name of the region to locate
140    * @return HRegionLocation that describes where to find the region in
141    * question
142    * @throws IOException if a remote or network exception occurs
143    */
144   @Override
145   HRegionLocation locateRegion(final byte[] regionName)
146   throws IOException;
147 
148   /**
149    * Gets the locations of all regions in the specified table, <i>tableName</i>.
150    * @param tableName table to get regions of
151    * @return list of region locations for all regions of table
152    * @throws IOException
153    */
154   @Override
155   List<HRegionLocation> locateRegions(final TableName tableName) throws IOException;
156 
157   /**
158    * Gets the locations of all regions in the specified table, <i>tableName</i>.
159    * @param tableName table to get regions of
160    * @param useCache Should we use the cache to retrieve the region information.
161    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
162    *          regions from returned list.
163    * @return list of region locations for all regions of table
164    * @throws IOException
165    */
166   @Override
167   List<HRegionLocation> locateRegions(final TableName tableName,
168       final boolean useCache,
169       final boolean offlined) throws IOException;
170 
171   /**
172    *
173    * @param tableName table to get regions of
174    * @param row the row
175    * @param useCache Should we use the cache to retrieve the region information.
176    * @param retry do we retry
177    * @return region locations for this row.
178    * @throws IOException
179    */
180   RegionLocations locateRegion(TableName tableName,
181                                byte[] row, boolean useCache, boolean retry) throws IOException;
182 
183   /**
184   *
185   * @param tableName table to get regions of
186   * @param row the row
187   * @param useCache Should we use the cache to retrieve the region information.
188   * @param retry do we retry
189   * @param replicaId the replicaId for the region
190   * @return region locations for this row.
191   * @throws IOException
192   */
193  RegionLocations locateRegion(TableName tableName,
194                               byte[] row, boolean useCache, boolean retry, int replicaId) throws IOException;
195 
196   /**
197    * Returns a {@link MasterKeepAliveConnection} to the active master
198    */
199   @Override
200   MasterService.BlockingInterface getMaster() throws IOException;
201 
202 
203   /**
204    * Establishes a connection to the region server at the specified address.
205    * @param serverName
206    * @return proxy for HRegionServer
207    * @throws IOException if a remote or network exception occurs
208    */
209   @Override
210   AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
211 
212   /**
213    * Establishes a connection to the region server at the specified address, and returns
214    * a region client protocol.
215    *
216    * @param serverName
217    * @return ClientProtocol proxy for RegionServer
218    * @throws IOException if a remote or network exception occurs
219    *
220    */
221   @Override
222   ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
223 
224   /**
225    * Find region location hosting passed row
226    * @param tableName table name
227    * @param row Row to find.
228    * @param reload If true do not use cache, otherwise bypass.
229    * @return Location of row.
230    * @throws IOException if a remote or network exception occurs
231    */
232   @Override
233   HRegionLocation getRegionLocation(TableName tableName, byte [] row,
234     boolean reload)
235   throws IOException;
236 
237   /**
238    * Clear any caches that pertain to server name <code>sn</code>.
239    * @param sn A server name
240    */
241   @Override
242   void clearCaches(final ServerName sn);
243 
244   /**
245    * This function allows HBaseAdmin and potentially others to get a shared MasterService
246    * connection.
247    * @return The shared instance. Never returns null.
248    * @throws MasterNotRunningException
249    */
250   @Override
251   @Deprecated
252   MasterKeepAliveConnection getKeepAliveMasterService()
253   throws MasterNotRunningException;
254 
255   /**
256    * @param serverName
257    * @return true if the server is known as dead, false otherwise.
258    * @deprecated internal method, do not use thru HConnection */
259   @Override
260   @Deprecated
261   boolean isDeadServer(ServerName serverName);
262 
263   /**
264    * @return Nonce generator for this HConnection; may be null if disabled in configuration.
265    */
266   @Override
267   public NonceGenerator getNonceGenerator();
268 
269   /**
270    * @return Default AsyncProcess associated with this connection.
271    */
272   AsyncProcess getAsyncProcess();
273 }