001/** 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.client; 019 020import java.io.Closeable; 021import java.io.IOException; 022import java.util.concurrent.ExecutorService; 023import org.apache.hadoop.conf.Configuration; 024import org.apache.hadoop.hbase.Abortable; 025import org.apache.hadoop.hbase.HBaseInterfaceAudience; 026import org.apache.hadoop.hbase.ServerName; 027import org.apache.hadoop.hbase.TableName; 028import org.apache.hadoop.hbase.util.FutureUtils; 029import org.apache.yetus.audience.InterfaceAudience; 030 031/** 032 * A cluster connection encapsulating lower level individual connections to actual servers and 033 * a connection to zookeeper. Connections are instantiated through the {@link ConnectionFactory} 034 * class. The lifecycle of the connection is managed by the caller, who has to {@link #close()} 035 * the connection to release the resources. 036 * 037 * <p> The connection object contains logic to find the master, locate regions out on the cluster, 038 * keeps a cache of locations and then knows how to re-calibrate after they move. The individual 039 * connections to servers, meta cache, zookeeper connection, etc are all shared by the 040 * {@link Table} and {@link Admin} instances obtained from this connection. 041 * 042 * <p> Connection creation is a heavy-weight operation. Connection implementations are thread-safe, 043 * so that the client can create a connection once, and share it with different threads. 044 * {@link Table} and {@link Admin} instances, on the other hand, are light-weight and are not 045 * thread-safe. Typically, a single connection per client application is instantiated and every 046 * thread will obtain its own Table instance. Caching or pooling of {@link Table} and {@link Admin} 047 * is not recommended. 048 * 049 * @see ConnectionFactory 050 * @since 0.99.0 051 */ 052@InterfaceAudience.Public 053public interface Connection extends Abortable, Closeable { 054 055 /* 056 * Implementation notes: 057 * - Only allow new style of interfaces: 058 * -- All table names are passed as TableName. No more byte[] and string arguments 059 * -- Most of the classes with names H is deprecated in favor of non-H versions 060 * (Table, Connection, etc) 061 * -- Only real client-facing public methods are allowed 062 * - Connection should contain only getTable(), getAdmin() kind of general methods. 063 */ 064 065 /** 066 * @return Configuration instance being used by this Connection instance. 067 */ 068 Configuration getConfiguration(); 069 070 /** 071 * Retrieve a Table implementation for accessing a table. 072 * The returned Table is not thread safe, a new instance should be created for each using thread. 073 * This is a lightweight operation, pooling or caching of the returned Table 074 * is neither required nor desired. 075 * <p> 076 * The caller is responsible for calling {@link Table#close()} on the returned 077 * table instance. 078 * <p> 079 * Since 0.98.1 this method no longer checks table existence. An exception 080 * will be thrown if the table does not exist only when the first operation is 081 * attempted. 082 * @param tableName the name of the table 083 * @return a Table to use for interactions with this table 084 */ 085 default Table getTable(TableName tableName) throws IOException { 086 return getTable(tableName, null); 087 } 088 089 /** 090 * Retrieve a Table implementation for accessing a table. 091 * The returned Table is not thread safe, a new instance should be created for each using thread. 092 * This is a lightweight operation, pooling or caching of the returned Table 093 * is neither required nor desired. 094 * <p> 095 * The caller is responsible for calling {@link Table#close()} on the returned 096 * table instance. 097 * <p> 098 * Since 0.98.1 this method no longer checks table existence. An exception 099 * will be thrown if the table does not exist only when the first operation is 100 * attempted. 101 * 102 * @param tableName the name of the table 103 * @param pool The thread pool to use for batch operations, null to use a default pool. 104 * @return a Table to use for interactions with this table 105 */ 106 default Table getTable(TableName tableName, ExecutorService pool) throws IOException { 107 return getTableBuilder(tableName, pool).build(); 108 } 109 110 /** 111 * <p> 112 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 113 * {@link BufferedMutator} returned by this method is thread-safe. This BufferedMutator will 114 * use the Connection's ExecutorService. This object can be used for long lived operations. 115 * </p> 116 * <p> 117 * The caller is responsible for calling {@link BufferedMutator#close()} on 118 * the returned {@link BufferedMutator} instance. 119 * </p> 120 * <p> 121 * This accessor will use the connection's ExecutorService and will throw an 122 * exception in the main thread when an asynchronous exception occurs. 123 * 124 * @param tableName the name of the table 125 * 126 * @return a {@link BufferedMutator} for the supplied tableName. 127 */ 128 default BufferedMutator getBufferedMutator(TableName tableName) throws IOException { 129 return getBufferedMutator(new BufferedMutatorParams(tableName)); 130 } 131 132 /** 133 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 134 * {@link BufferedMutator} returned by this method is thread-safe. This object can be used for 135 * long lived table operations. The caller is responsible for calling 136 * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance. 137 * 138 * @param params details on how to instantiate the {@code BufferedMutator}. 139 * @return a {@link BufferedMutator} for the supplied tableName. 140 */ 141 BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException; 142 143 /** 144 * Retrieve a RegionLocator implementation to inspect region information on a table. The returned 145 * RegionLocator is not thread-safe, so a new instance should be created for each using thread. 146 * 147 * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither 148 * required nor desired. 149 * <br> 150 * The caller is responsible for calling {@link RegionLocator#close()} on the returned 151 * RegionLocator instance. 152 * 153 * RegionLocator needs to be unmanaged 154 * 155 * @param tableName Name of the table who's region is to be examined 156 * @return A RegionLocator instance 157 */ 158 RegionLocator getRegionLocator(TableName tableName) throws IOException; 159 160 /** 161 * Clear all the entries in the region location cache, for all the tables. 162 * <p/> 163 * If you only want to clear the cache for a specific table, use 164 * {@link RegionLocator#clearRegionLocationCache()}. 165 * <p/> 166 * This may cause performance issue so use it with caution. 167 */ 168 void clearRegionLocationCache(); 169 170 /** 171 * Retrieve an Admin implementation to administer an HBase cluster. 172 * The returned Admin is not guaranteed to be thread-safe. A new instance should be created for 173 * each using thread. This is a lightweight operation. Pooling or caching of the returned 174 * Admin is not recommended. 175 * <br> 176 * The caller is responsible for calling {@link Admin#close()} on the returned 177 * Admin instance. 178 * 179 * @return an Admin instance for cluster administration 180 */ 181 Admin getAdmin() throws IOException; 182 183 @Override 184 void close() throws IOException; 185 186 /** 187 * Returns whether the connection is closed or not. 188 * @return true if this connection is closed 189 */ 190 boolean isClosed(); 191 192 /** 193 * Returns an {@link TableBuilder} for creating {@link Table}. 194 * @param tableName the name of the table 195 * @param pool the thread pool to use for requests like batch and scan 196 */ 197 TableBuilder getTableBuilder(TableName tableName, ExecutorService pool); 198 199 /** 200 * Convert this connection to an {@link AsyncConnection}. 201 * <p/> 202 * Usually we will return the same instance if you call this method multiple times so you can 203 * consider this as a light-weighted operation. 204 */ 205 AsyncConnection toAsyncConnection(); 206 207 /** 208 * @return the cluster ID unique to this HBase cluster. 209 */ 210 String getClusterId(); 211 212 /** 213 * Retrieve an Hbck implementation to fix an HBase cluster. 214 * The returned Hbck is not guaranteed to be thread-safe. A new instance should be created by 215 * each thread. This is a lightweight operation. Pooling or caching of the returned Hbck instance 216 * is not recommended. 217 * <br> 218 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. 219 *<br> 220 * This will be used mostly by hbck tool. 221 * 222 * @return an Hbck instance for active master. Active master is fetched from the zookeeper. 223 */ 224 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 225 default Hbck getHbck() throws IOException { 226 return FutureUtils.get(toAsyncConnection().getHbck()); 227 } 228 229 /** 230 * Retrieve an Hbck implementation to fix an HBase cluster. 231 * The returned Hbck is not guaranteed to be thread-safe. A new instance should be created by 232 * each thread. This is a lightweight operation. Pooling or caching of the returned Hbck instance 233 * is not recommended. 234 * <br> 235 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. 236 *<br> 237 * This will be used mostly by hbck tool. This may only be used to by pass getting 238 * registered master from ZK. In situations where ZK is not available or active master is not 239 * registered with ZK and user can get master address by other means, master can be explicitly 240 * specified. 241 * 242 * @param masterServer explicit {@link ServerName} for master server 243 * @return an Hbck instance for a specified master server 244 */ 245 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 246 default Hbck getHbck(ServerName masterServer) throws IOException { 247 return toAsyncConnection().getHbck(masterServer); 248 } 249}