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 }