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 }