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