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.util.concurrent.ExecutorService;
  22
  23 import org.apache.hadoop.conf.Configuration;
  24 import org.apache.hadoop.hbase.TableName;
  25 import org.apache.hadoop.hbase.classification.InterfaceAudience;
  26
  27 /**
  28  * The asynchronous version of Connection.
  29  */
  30 @InterfaceAudience.Public
  31 public interface AsyncConnection extends Closeable {
  32
  33   /**
  34    * Returns the {@link org.apache.hadoop.conf.Configuration} object used by this instance.
  35    * <p>
  36    * The reference returned is not a copy, so any change made to it will affect this instance.
  37    */
  38   Configuration getConfiguration();
  39
  40   /**
  41    * Retrieve a AsyncRegionLocator implementation to inspect region information on a table. The
  42    * returned AsyncRegionLocator is not thread-safe, so a new instance should be created for each
  43    * using thread. This is a lightweight operation. Pooling or caching of the returned
  44    * AsyncRegionLocator is neither required nor desired.
  45    * @param tableName Name of the table who's region is to be examined
  46    * @return An AsyncRegionLocator instance
  47    */
  48   AsyncTableRegionLocator getRegionLocator(TableName tableName);
  49
  50   /**
  51    * Retrieve an {@link RawAsyncTable} implementation for accessing a table.
  52    * <p>
  53    * The returned instance will use default configs. Use {@link #getRawTableBuilder(TableName)} if you
  54    * want to customize some configs.
  55    * <p>
  56    * This method no longer checks table existence. An exception will be thrown if the table does not
  57    * exist only when the first operation is attempted.
  58    * @param tableName the name of the table
  59    * @return an RawAsyncTable to use for interactions with this table
  60    * @see #getRawTableBuilder(TableName)
  61    */
  62   default RawAsyncTable getRawTable(TableName tableName) {
  63     return getRawTableBuilder(tableName).build();
  64   }
  65
  66   /**
  67    * Returns an {@link AsyncTableBuilder} for creating {@link RawAsyncTable}.
  68    * <p>
  69    * This method no longer checks table existence. An exception will be thrown if the table does not
  70    * exist only when the first operation is attempted.
  71    * @param tableName the name of the table
  72    */
  73   AsyncTableBuilder<RawAsyncTable> getRawTableBuilder(TableName tableName);
  74
  75   /**
  76    * Retrieve an AsyncTable implementation for accessing a table.
  77    * <p>
  78    * This method no longer checks table existence. An exception will be thrown if the table does not
  79    * exist only when the first operation is attempted.
  80    * @param tableName the name of the table
  81    * @param pool the thread pool to use for executing callback
  82    * @return an AsyncTable to use for interactions with this table
  83    */
  84   default AsyncTable getTable(TableName tableName, ExecutorService pool) {
  85     return getTableBuilder(tableName, pool).build();
  86   }
  87
  88   /**
  89    * Returns an {@link AsyncTableBuilder} for creating {@link AsyncTable}.
  90    * <p>
  91    * This method no longer checks table existence. An exception will be thrown if the table does not
  92    * exist only when the first operation is attempted.
  93    * @param tableName the name of the table
  94    * @param pool the thread pool to use for executing callback
  95    */
  96   AsyncTableBuilder<AsyncTable> getTableBuilder(TableName tableName, ExecutorService pool);
  97
  98   /**
  99    * Retrieve an {@link AsyncAdmin} implementation to administer an HBase cluster.
 100    * <p>
 101    * The returned instance will use default configs. Use {@link #getAdminBuilder()} if you want to
 102    * customize some configs.
 103    * <p>
 104    * The admin operation's returned {@code CompletableFuture} will be finished directly in the rpc
 105    * framework's callback thread, so typically you should not do any time consuming work inside
 106    * these methods.
 107    * @return an {@link AsyncAdmin} instance for cluster administration
 108    */
 109   default AsyncAdmin getAdmin() {
 110     return getAdminBuilder().build();
 111   }
 112
 113   /**
 114    * Returns an {@link AsyncAdminBuilder} for creating {@link AsyncAdmin}.
 115    * <p>
 116    * The admin operation's returned {@code CompletableFuture} will be finished directly in the rpc
 117    * framework's callback thread, so typically you should not do any time consuming work inside
 118    * these methods.
 119    */
 120   AsyncAdminBuilder<RawAsyncHBaseAdmin> getAdminBuilder();
 121
 122   /**
 123    * Retrieve an {@link AsyncAdmin} implementation to administer an HBase cluster.
 124    * <p>
 125    * The returned instance will use default configs. Use {@link #getAdminBuilder(ExecutorService)}
 126    * if you want to customize some configs.
 127    * @param pool the thread pool to use for executing callback
 128    * @return an {@link AsyncAdmin} instance for cluster administration
 129    */
 130   default AsyncAdmin getAdmin(ExecutorService pool) {
 131     return getAdminBuilder(pool).build();
 132   }
 133
 134   /**
 135    * Returns an {@link AsyncAdminBuilder} for creating {@link AsyncAdmin}.
 136    * @param pool the thread pool to use for executing callback
 137    */
 138   AsyncAdminBuilder<AsyncHBaseAdmin> getAdminBuilder(ExecutorService pool);
 139 }