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.CompletableFuture; 023import java.util.concurrent.ExecutorService; 024import org.apache.hadoop.conf.Configuration; 025import org.apache.hadoop.hbase.HBaseInterfaceAudience; 026import org.apache.hadoop.hbase.ServerName; 027import org.apache.hadoop.hbase.TableName; 028import org.apache.yetus.audience.InterfaceAudience; 029 030/** 031 * The asynchronous version of Connection. 032 * @since 2.0.0 033 */ 034@InterfaceAudience.Public 035public interface AsyncConnection extends Closeable { 036 037 /** 038 * Returns the {@link org.apache.hadoop.conf.Configuration} object used by this instance. 039 * <p> 040 * The reference returned is not a copy, so any change made to it will affect this instance. 041 */ 042 Configuration getConfiguration(); 043 044 /** 045 * Retrieve a AsyncRegionLocator implementation to inspect region information on a table. The 046 * returned AsyncRegionLocator is not thread-safe, so a new instance should be created for each 047 * using thread. This is a lightweight operation. Pooling or caching of the returned 048 * AsyncRegionLocator is neither required nor desired. 049 * @param tableName Name of the table who's region is to be examined 050 * @return An AsyncRegionLocator instance 051 */ 052 AsyncTableRegionLocator getRegionLocator(TableName tableName); 053 054 /** 055 * Clear all the entries in the region location cache, for all the tables. 056 * <p/> 057 * If you only want to clear the cache for a specific table, use 058 * {@link AsyncTableRegionLocator#clearRegionLocationCache()}. 059 * <p/> 060 * This may cause performance issue so use it with caution. 061 */ 062 void clearRegionLocationCache(); 063 064 /** 065 * Retrieve an {@link AsyncTable} implementation for accessing a table. 066 * <p> 067 * The returned instance will use default configs. Use {@link #getTableBuilder(TableName)} if you 068 * want to customize some configs. 069 * <p> 070 * This method no longer checks table existence. An exception will be thrown if the table does not 071 * exist only when the first operation is attempted. 072 * <p> 073 * The returned {@code CompletableFuture} will be finished directly in the rpc framework's 074 * callback thread, so typically you should not do any time consuming work inside these methods. 075 * And also the observer style scan API will use {@link AdvancedScanResultConsumer} which is 076 * designed for experts only. Only use it when you know what you are doing. 077 * @param tableName the name of the table 078 * @return an AsyncTable to use for interactions with this table 079 * @see #getTableBuilder(TableName) 080 */ 081 default AsyncTable<AdvancedScanResultConsumer> getTable(TableName tableName) { 082 return getTableBuilder(tableName).build(); 083 } 084 085 /** 086 * Returns an {@link AsyncTableBuilder} for creating {@link AsyncTable}. 087 * <p> 088 * This method no longer checks table existence. An exception will be thrown if the table does not 089 * exist only when the first operation is attempted. 090 * @param tableName the name of the table 091 */ 092 AsyncTableBuilder<AdvancedScanResultConsumer> getTableBuilder(TableName tableName); 093 094 /** 095 * Retrieve an {@link AsyncTable} implementation for accessing a table. 096 * <p> 097 * This method no longer checks table existence. An exception will be thrown if the table does not 098 * exist only when the first operation is attempted. 099 * @param tableName the name of the table 100 * @param pool the thread pool to use for executing callback 101 * @return an AsyncTable to use for interactions with this table 102 */ 103 default AsyncTable<ScanResultConsumer> getTable(TableName tableName, ExecutorService pool) { 104 return getTableBuilder(tableName, pool).build(); 105 } 106 107 /** 108 * Returns an {@link AsyncTableBuilder} for creating {@link AsyncTable}. 109 * <p> 110 * This method no longer checks table existence. An exception will be thrown if the table does not 111 * exist only when the first operation is attempted. 112 * @param tableName the name of the table 113 * @param pool the thread pool to use for executing callback 114 */ 115 AsyncTableBuilder<ScanResultConsumer> getTableBuilder(TableName tableName, ExecutorService pool); 116 117 /** 118 * Retrieve an {@link AsyncAdmin} implementation to administer an HBase cluster. 119 * <p> 120 * The returned instance will use default configs. Use {@link #getAdminBuilder()} if you want to 121 * customize some configs. 122 * <p> 123 * The admin operation's returned {@code CompletableFuture} will be finished directly in the rpc 124 * framework's callback thread, so typically you should not do any time consuming work inside 125 * these methods. 126 * @return an {@link AsyncAdmin} instance for cluster administration 127 */ 128 default AsyncAdmin getAdmin() { 129 return getAdminBuilder().build(); 130 } 131 132 /** 133 * Returns an {@link AsyncAdminBuilder} for creating {@link AsyncAdmin}. 134 * <p> 135 * The admin operation's returned {@code CompletableFuture} will be finished directly in the rpc 136 * framework's callback thread, so typically you should not do any time consuming work inside 137 * these methods. 138 */ 139 AsyncAdminBuilder getAdminBuilder(); 140 141 /** 142 * Retrieve an {@link AsyncAdmin} implementation to administer an HBase cluster. 143 * <p> 144 * The returned instance will use default configs. Use {@link #getAdminBuilder(ExecutorService)} 145 * if you want to customize some configs. 146 * @param pool the thread pool to use for executing callback 147 * @return an {@link AsyncAdmin} instance for cluster administration 148 */ 149 default AsyncAdmin getAdmin(ExecutorService pool) { 150 return getAdminBuilder(pool).build(); 151 } 152 153 /** 154 * Returns an {@link AsyncAdminBuilder} for creating {@link AsyncAdmin}. 155 * @param pool the thread pool to use for executing callback 156 */ 157 AsyncAdminBuilder getAdminBuilder(ExecutorService pool); 158 159 /** 160 * Retrieve an {@link AsyncBufferedMutator} for performing client-side buffering of writes. 161 * <p> 162 * The returned instance will use default configs. Use 163 * {@link #getBufferedMutatorBuilder(TableName)} if you want to customize some configs. 164 * @param tableName the name of the table 165 * @return an {@link AsyncBufferedMutator} for the supplied tableName. 166 */ 167 default AsyncBufferedMutator getBufferedMutator(TableName tableName) { 168 return getBufferedMutatorBuilder(tableName).build(); 169 } 170 171 /** 172 * Returns an {@link AsyncBufferedMutatorBuilder} for creating {@link AsyncBufferedMutator}. 173 * @param tableName the name of the table 174 */ 175 AsyncBufferedMutatorBuilder getBufferedMutatorBuilder(TableName tableName); 176 177 /** 178 * Retrieve an {@link AsyncBufferedMutator} for performing client-side buffering of writes. 179 * <p> 180 * The returned instance will use default configs. Use 181 * {@link #getBufferedMutatorBuilder(TableName, ExecutorService)} if you want to customize some 182 * configs. 183 * @param tableName the name of the table 184 * @param pool the thread pool to use for executing callback 185 * @return an {@link AsyncBufferedMutator} for the supplied tableName. 186 */ 187 default AsyncBufferedMutator getBufferedMutator(TableName tableName, ExecutorService pool) { 188 return getBufferedMutatorBuilder(tableName, pool).build(); 189 } 190 191 /** 192 * Returns an {@link AsyncBufferedMutatorBuilder} for creating {@link AsyncBufferedMutator}. 193 * @param tableName the name of the table 194 * @param pool the thread pool to use for executing callback 195 */ 196 AsyncBufferedMutatorBuilder getBufferedMutatorBuilder(TableName tableName, ExecutorService pool); 197 198 /** 199 * Returns whether the connection is closed or not. 200 * @return true if this connection is closed 201 */ 202 boolean isClosed(); 203 204 /** 205 * Convert this connection to a {@link Connection}. 206 * <p/> 207 * Usually we will return the same instance if you call this method multiple times so you can 208 * consider this as a light-weighted operation. 209 */ 210 Connection toConnection(); 211 212 /** 213 * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to 214 * be thread-safe. A new instance should be created by each thread. This is a lightweight 215 * operation. Pooling or caching of the returned Hbck instance is not recommended. 216 * <p/> 217 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. 218 * <p/> 219 * This will be used mostly by hbck tool. 220 * @return an Hbck instance for active master. Active master is fetched from the zookeeper. 221 */ 222 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 223 CompletableFuture<Hbck> getHbck(); 224 225 /** 226 * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to 227 * be thread-safe. A new instance should be created by each thread. This is a lightweight 228 * operation. Pooling or caching of the returned Hbck instance is not recommended. 229 * <p/> 230 * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. 231 * <p/> 232 * This will be used mostly by hbck tool. This may only be used to by pass getting registered 233 * master from ZK. In situations where ZK is not available or active master is not registered with 234 * ZK and user can get master address by other means, master can be explicitly specified. 235 * @param masterServer explicit {@link ServerName} for master server 236 * @return an Hbck instance for a specified master server 237 */ 238 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK) 239 Hbck getHbck(ServerName masterServer) throws IOException; 240}