View Javadoc

1   /**
2    * Copyright 2010 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase.client;
21  
22  import org.apache.hadoop.hbase.HRegionInfo;
23  import org.apache.hadoop.hbase.HRegionLocation;
24  import org.apache.hadoop.hbase.HServerAddress;
25  import org.apache.hadoop.hbase.HTableDescriptor;
26  import org.apache.hadoop.hbase.MasterNotRunningException;
27  import org.apache.hadoop.hbase.ipc.HMasterInterface;
28  import org.apache.hadoop.hbase.ipc.HRegionInterface;
29  import org.apache.hadoop.hbase.zookeeper.ZooKeeperWrapper;
30  
31  import java.io.IOException;
32  import java.util.ArrayList;
33  import java.util.List;
34  import java.util.Map;
35  import java.util.concurrent.ExecutorService;
36  
37  /**
38   * Cluster connection.
39   * {@link HConnectionManager} manages instances of this class.
40   */
41  public interface HConnection {
42    /**
43     * Retrieve ZooKeeperWrapper used by the connection.
44     * @return ZooKeeperWrapper handle being used by the connection.
45     * @throws IOException if a remote or network exception occurs
46     */
47    public ZooKeeperWrapper getZooKeeperWrapper() throws IOException;
48  
49    /**
50     * @return proxy connection to master server for this instance
51     * @throws MasterNotRunningException if the master is not running
52     */
53    public HMasterInterface getMaster() throws MasterNotRunningException;
54  
55    /** @return - true if the master server is running */
56    public boolean isMasterRunning();
57  
58    /**
59     * Checks if <code>tableName</code> exists.
60     * @param tableName Table to check.
61     * @return True if table exists already.
62     * @throws MasterNotRunningException if the master is not running
63     */
64    public boolean tableExists(final byte [] tableName)
65    throws MasterNotRunningException;
66  
67    /**
68     * A table that isTableEnabled == false and isTableDisabled == false
69     * is possible. This happens when a table has a lot of regions
70     * that must be processed.
71     * @param tableName table name
72     * @return true if the table is enabled, false otherwise
73     * @throws IOException if a remote or network exception occurs
74     */
75    public boolean isTableEnabled(byte[] tableName) throws IOException;
76  
77    /**
78     * @param tableName table name
79     * @return true if the table is disabled, false otherwise
80     * @throws IOException if a remote or network exception occurs
81     */
82    public boolean isTableDisabled(byte[] tableName) throws IOException;
83  
84    /**
85     * @param tableName table name
86     * @return true if all regions of the table are available, false otherwise
87     * @throws IOException if a remote or network exception occurs
88     */
89    public boolean isTableAvailable(byte[] tableName) throws IOException;
90  
91    /**
92     * List all the userspace tables.  In other words, scan the META table.
93     *
94     * If we wanted this to be really fast, we could implement a special
95     * catalog table that just contains table names and their descriptors.
96     * Right now, it only exists as part of the META table's region info.
97     *
98     * @return - returns an array of HTableDescriptors
99     * @throws IOException if a remote or network exception occurs
100    */
101   public HTableDescriptor[] listTables() throws IOException;
102 
103   /**
104    * @param tableName table name
105    * @return table metadata
106    * @throws IOException if a remote or network exception occurs
107    */
108   public HTableDescriptor getHTableDescriptor(byte[] tableName)
109   throws IOException;
110 
111   /**
112    * Find the location of the region of <i>tableName</i> that <i>row</i>
113    * lives in.
114    * @param tableName name of the table <i>row</i> is in
115    * @param row row key you're trying to find the region of
116    * @return HRegionLocation that describes where to find the reigon in
117    * question
118    * @throws IOException if a remote or network exception occurs
119    */
120   public HRegionLocation locateRegion(final byte [] tableName,
121       final byte [] row)
122   throws IOException;
123 
124   /**
125    * Allows flushing the region cache.
126    */
127   public void clearRegionCache();
128 
129   /**
130    * Find the location of the region of <i>tableName</i> that <i>row</i>
131    * lives in, ignoring any value that might be in the cache.
132    * @param tableName name of the table <i>row</i> is in
133    * @param row row key you're trying to find the region of
134    * @return HRegionLocation that describes where to find the reigon in
135    * question
136    * @throws IOException if a remote or network exception occurs
137    */
138   public HRegionLocation relocateRegion(final byte [] tableName,
139       final byte [] row)
140   throws IOException;
141 
142   /**
143    * Establishes a connection to the region server at the specified address.
144    * @param regionServer - the server to connect to
145    * @return proxy for HRegionServer
146    * @throws IOException if a remote or network exception occurs
147    */
148   public HRegionInterface getHRegionConnection(HServerAddress regionServer)
149   throws IOException;
150 
151   /**
152    * Establishes a connection to the region server at the specified address.
153    * @param regionServer - the server to connect to
154    * @param getMaster - do we check if master is alive
155    * @return proxy for HRegionServer
156    * @throws IOException if a remote or network exception occurs
157    */
158   public HRegionInterface getHRegionConnection(
159       HServerAddress regionServer, boolean getMaster)
160   throws IOException;
161 
162   /**
163    * Find region location hosting passed row
164    * @param tableName table name
165    * @param row Row to find.
166    * @param reload If true do not use cache, otherwise bypass.
167    * @return Location of row.
168    * @throws IOException if a remote or network exception occurs
169    */
170   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
171     boolean reload)
172   throws IOException;
173 
174   /**
175    * Pass in a ServerCallable with your particular bit of logic defined and
176    * this method will manage the process of doing retries with timed waits
177    * and refinds of missing regions.
178    *
179    * @param <T> the type of the return value
180    * @param callable callable to run
181    * @return an object of type T
182    * @throws IOException if a remote or network exception occurs
183    * @throws RuntimeException other unspecified error
184    */
185   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
186   throws IOException, RuntimeException;
187 
188   /**
189    * Pass in a ServerCallable with your particular bit of logic defined and
190    * this method will pass it to the defined region server.
191    * @param <T> the type of the return value
192    * @param callable callable to run
193    * @return an object of type T
194    * @throws IOException if a remote or network exception occurs
195    * @throws RuntimeException other unspecified error
196    */
197   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 
198   throws IOException, RuntimeException;
199 
200 
201   /**
202    * Process a batch of Puts. Does the retries.
203    * @param list A batch of Puts to process.
204    * @param tableName The name of the table
205    * @return Count of committed Puts.  On fault, < list.size().
206    * @throws IOException if a remote or network exception occurs
207    */
208   public int processBatchOfRows(ArrayList<Put> list, byte[] tableName)
209   throws IOException;
210 
211   /**
212    * Process a batch of Deletes. Does the retries.
213    * @param list A batch of Deletes to process.
214    * @return Count of committed Deletes. On fault, < list.size().
215    * @param tableName The name of the table
216    * @throws IOException if a remote or network exception occurs
217    */
218   public int processBatchOfDeletes(List<Delete> list, byte[] tableName)
219   throws IOException;
220 
221   public void processBatchOfPuts(List<Put> list,
222                                  final byte[] tableName, ExecutorService pool) throws IOException;
223 
224   /**
225    * Enable or disable region cache prefetch for the table. It will be
226    * applied for the given table's all HTable instances within this
227    * connection. By default, the cache prefetch is enabled.
228    * @param tableName name of table to configure.
229    * @param enable Set to true to enable region cache prefetch.
230    */
231   public void setRegionCachePrefetch(final byte[] tableName,
232       final boolean enable);
233 
234   /**
235    * Check whether region cache prefetch is enabled or not.
236    * @param tableName name of table to check
237    * @return true if table's region cache prefecth is enabled. Otherwise
238    * it is disabled.
239    */
240   public boolean getRegionCachePrefetch(final byte[] tableName);
241 
242   /**
243    * Load the region map and warm up the global region cache for the table.
244    * @param tableName name of the table to perform region cache prewarm.
245    * @param regions a region map.
246    */
247   public void prewarmRegionCache(final byte[] tableName,
248       final Map<HRegionInfo, HServerAddress> regions);
249 }