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 a 033 * 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()} the 035 * connection to release the resources. 036 * <p> 037 * The connection object contains logic to find the master, locate regions out on the cluster, keeps 038 * 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 {@link Table} 040 * and {@link Admin} instances obtained from this connection. 041 * <p> 042 * Connection creation is a heavy-weight operation. Connection implementations are thread-safe, so 043 * that the client can create a connection once, and share it with different threads. {@link Table} 044 * and {@link Admin} instances, on the other hand, are light-weight and are not thread-safe. 045 * Typically, a single connection per client application is instantiated and every thread will 046 * obtain its own Table instance. Caching or pooling of {@link Table} and {@link Admin} is not 047 * recommended. 048 * @see ConnectionFactory 049 * @since 0.99.0 050 */ 051@InterfaceAudience.Public 052public interface Connection extends Abortable, Closeable { 053 054 /* 055 * Implementation notes: - Only allow new style of interfaces: -- All table names are passed as 056 * TableName. No more byte[] and string arguments -- Most of the classes with names H is 057 * deprecated in favor of non-H versions (Table, Connection, etc) -- Only real client-facing 058 * public methods are allowed - Connection should contain only getTable(), getAdmin() kind of 059 * general methods. 060 */ 061 062 /** 063 * @return Configuration instance being used by this Connection instance. 064 */ 065 Configuration getConfiguration(); 066 067 /** 068 * Retrieve a Table implementation for accessing a table. The returned Table is not thread safe, a 069 * new instance should be created for each using thread. This is a lightweight operation, pooling 070 * or caching of the returned Table is neither required nor desired. 071 * <p> 072 * The caller is responsible for calling {@link Table#close()} on the returned table instance. 073 * <p> 074 * Since 0.98.1 this method no longer checks table existence. An exception will be thrown if the 075 * table does not exist only when the first operation is attempted. 076 * @param tableName the name of the table 077 * @return a Table to use for interactions with this table 078 */ 079 default Table getTable(TableName tableName) throws IOException { 080 return getTable(tableName, null); 081 } 082 083 /** 084 * Retrieve a Table implementation for accessing a table. The returned Table is not thread safe, a 085 * new instance should be created for each using thread. This is a lightweight operation, pooling 086 * or caching of the returned Table is neither required nor desired. 087 * <p> 088 * The caller is responsible for calling {@link Table#close()} on the returned table instance. 089 * <p> 090 * Since 0.98.1 this method no longer checks table existence. An exception will be thrown if the 091 * table does not exist only when the first operation is attempted. 092 * @param tableName the name of the table 093 * @param pool The thread pool to use for batch operations, null to use a default pool. 094 * @return a Table to use for interactions with this table 095 */ 096 default Table getTable(TableName tableName, ExecutorService pool) throws IOException { 097 return getTableBuilder(tableName, pool).build(); 098 } 099 100 /** 101 * <p> 102 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 103 * {@link BufferedMutator} returned by this method is thread-safe. This BufferedMutator will use 104 * the Connection's ExecutorService. This object can be used for long lived operations. 105 * </p> 106 * <p> 107 * The caller is responsible for calling {@link BufferedMutator#close()} on the returned 108 * {@link BufferedMutator} instance. 109 * </p> 110 * <p> 111 * This accessor will use the connection's ExecutorService and will throw an exception in the main 112 * thread when an asynchronous exception occurs. 113 * @param tableName the name of the table 114 * @return a {@link BufferedMutator} for the supplied tableName. 115 */ 116 default BufferedMutator getBufferedMutator(TableName tableName) throws IOException { 117 return getBufferedMutator(new BufferedMutatorParams(tableName)); 118 } 119 120 /** 121 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 122 * {@link BufferedMutator} returned by this method is thread-safe. This object can be used for 123 * long lived table operations. The caller is responsible for calling 124 * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance. 125 * @param params details on how to instantiate the {@code BufferedMutator}. 126 * @return a {@link BufferedMutator} for the supplied tableName. 127 */ 128 BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException; 129 130 /** 131 * Retrieve a RegionLocator implementation to inspect region information on a table. The returned 132 * RegionLocator is not thread-safe, so a new instance should be created for each using thread. 133 * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither 134 * required nor desired. <br> 135 * The caller is responsible for calling {@link RegionLocator#close()} on the returned 136 * RegionLocator instance. RegionLocator needs to be unmanaged 137 * @param tableName Name of the table who's region is to be examined 138 * @return A RegionLocator instance 139 */ 140 RegionLocator getRegionLocator(TableName tableName) throws IOException; 141 142 /** 143 * Clear all the entries in the region location cache, for all the tables. 144 * <p/> 145 * If you only want to clear the cache for a specific table, use 146 * {@link RegionLocator#clearRegionLocationCache()}. 147 * <p/> 148 * This may cause performance issue so use it with caution. 149 */ 150 void clearRegionLocationCache(); 151 152 /** 153 * Retrieve an Admin implementation to administer an HBase cluster. The returned Admin is not 154 * guaranteed to be thread-safe. A new instance should be created for each using thread. This is a 155 * lightweight operation. Pooling or caching of the returned Admin is not recommended. <br> 156 * The caller is responsible for calling {@link Admin#close()} on the returned Admin instance. 157 * @return an Admin instance for cluster administration 158 */ 159 Admin getAdmin() throws IOException; 160 161 @Override 162 void close() throws IOException; 163 164 /** 165 * Returns whether the connection is closed or not. 166 * @return true if this connection is closed 167 */ 168 boolean isClosed(); 169 170 /** 171 * Returns an {@link TableBuilder} for creating {@link Table}. 172 * @param tableName the name of the table 173 * @param pool the thread pool to use for requests like batch and scan 174 */ 175 TableBuilder getTableBuilder(TableName tableName, ExecutorService pool); 176 177 /** 178 * Convert this connection to an {@link AsyncConnection}. 179 * <p/> 180 * Usually we will return the same instance if you call this method multiple times so you can 181 * consider this as a light-weighted operation. 182 */ 183 AsyncConnection toAsyncConnection(); 184 185 /** 186 * @return the cluster ID unique to this HBase cluster. 187 */ 188 String getClusterId(); 189 190 /** 191 * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to 192 * be thread-safe. A new instance should be created by each thread. This is a lightweight 193 * operation. Pooling or caching of the returned Hbck instance is not recommended. <br> 194 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. <br> 195 * This will be used mostly by hbck tool. 196 * @return an Hbck instance for active master. Active master is fetched from the zookeeper. 197 */ 198 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 199 default Hbck getHbck() throws IOException { 200 return FutureUtils.get(toAsyncConnection().getHbck()); 201 } 202 203 /** 204 * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to 205 * be thread-safe. A new instance should be created by each thread. This is a lightweight 206 * operation. Pooling or caching of the returned Hbck instance is not recommended. <br> 207 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. <br> 208 * This will be used mostly by hbck tool. This may only be used to by pass getting registered 209 * master from ZK. In situations where ZK is not available or active master is not registered with 210 * ZK and user can get master address by other means, master can be explicitly specified. 211 * @param masterServer explicit {@link ServerName} for master server 212 * @return an Hbck instance for a specified master server 213 */ 214 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 215 default Hbck getHbck(ServerName masterServer) throws IOException { 216 return toAsyncConnection().getHbck(masterServer); 217 } 218}