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