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   * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to
206   * be thread-safe. A new instance should be created by each thread. This is a lightweight
207   * operation. Pooling or caching of the returned Hbck instance is not recommended.
208   * <p/>
209   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance.
210   * <p/>
211   * This will be used mostly by hbck tool.
212   * @return an Hbck instance for active master. Active master is fetched from the zookeeper.
213   */
214  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
215  CompletableFuture<Hbck> getHbck();
216
217  /**
218   * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to
219   * be thread-safe. A new instance should be created by each thread. This is a lightweight
220   * operation. Pooling or caching of the returned Hbck instance is not recommended.
221   * <p/>
222   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance.
223   * <p/>
224   * This will be used mostly by hbck tool. This may only be used to by pass getting registered
225   * master from ZK. In situations where ZK is not available or active master is not registered with
226   * ZK and user can get master address by other means, master can be explicitly specified.
227   * @param masterServer explicit {@link ServerName} for master server
228   * @return an Hbck instance for a specified master server
229   */
230  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
231  Hbck getHbck(ServerName masterServer) throws IOException;
232}