hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncConnection.java

   1 /**
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 package org.apache.hadoop.hbase.client;
  19
  20 import java.io.Closeable;
  21 import java.io.IOException;
  22 import java.util.concurrent.CompletableFuture;
  23 import java.util.concurrent.ExecutorService;
  24 import org.apache.hadoop.conf.Configuration;
  25 import org.apache.hadoop.hbase.HBaseInterfaceAudience;
  26 import org.apache.hadoop.hbase.ServerName;
  27 import org.apache.hadoop.hbase.TableName;
  28 import org.apache.yetus.audience.InterfaceAudience;
  29
  30 /**
  31  * The asynchronous version of Connection.
  32  * @since 2.0.0
  33  */
  34 @InterfaceAudience.Public
  35 public interface AsyncConnection extends Closeable {
  36
  37   /**
  38    * Returns the {@link org.apache.hadoop.conf.Configuration} object used by this instance.
  39    * <p>
  40    * The reference returned is not a copy, so any change made to it will affect this instance.
  41    */
  42   Configuration getConfiguration();
  43
  44   /**
  45    * Retrieve a AsyncRegionLocator implementation to inspect region information on a table. The
  46    * returned AsyncRegionLocator is not thread-safe, so a new instance should be created for each
  47    * using thread. This is a lightweight operation. Pooling or caching of the returned
  48    * AsyncRegionLocator is neither required nor desired.
  49    * @param tableName Name of the table who's region is to be examined
  50    * @return An AsyncRegionLocator instance
  51    */
  52   AsyncTableRegionLocator getRegionLocator(TableName tableName);
  53
  54   /**
  55    * Clear all the entries in the region location cache, for all the tables.
  56    * <p/>
  57    * If you only want to clear the cache for a specific table, use
  58    * {@link AsyncTableRegionLocator#clearRegionLocationCache()}.
  59    * <p/>
  60    * This may cause performance issue so use it with caution.
  61    */
  62   void clearRegionLocationCache();
  63
  64   /**
  65    * Retrieve an {@link AsyncTable} implementation for accessing a table.
  66    * <p>
  67    * The returned instance will use default configs. Use {@link #getTableBuilder(TableName)} if you
  68    * want to customize some configs.
  69    * <p>
  70    * This method no longer checks table existence. An exception will be thrown if the table does not
  71    * exist only when the first operation is attempted.
  72    * <p>
  73    * The returned {@code CompletableFuture} will be finished directly in the rpc framework's
  74    * callback thread, so typically you should not do any time consuming work inside these methods.
  75    * And also the observer style scan API will use {@link AdvancedScanResultConsumer} which is
  76    * designed for experts only. Only use it when you know what you are doing.
  77    * @param tableName the name of the table
  78    * @return an AsyncTable to use for interactions with this table
  79    * @see #getTableBuilder(TableName)
  80    */
  81   default AsyncTable<AdvancedScanResultConsumer> getTable(TableName tableName) {
  82     return getTableBuilder(tableName).build();
  83   }
  84
  85   /**
  86    * Returns an {@link AsyncTableBuilder} for creating {@link AsyncTable}.
  87    * <p>
  88    * This method no longer checks table existence. An exception will be thrown if the table does not
  89    * exist only when the first operation is attempted.
  90    * @param tableName the name of the table
  91    */
  92   AsyncTableBuilder<AdvancedScanResultConsumer> getTableBuilder(TableName tableName);
  93
  94   /**
  95    * Retrieve an {@link AsyncTable} implementation for accessing a table.
  96    * <p>
  97    * This method no longer checks table existence. An exception will be thrown if the table does not
  98    * exist only when the first operation is attempted.
  99    * @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 }