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.
113   * This accessor will create a new ThreadPoolExecutor and will be shutdown once we close the
114   *  BufferedMutator. 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   *
122   * @param tableName the name of the table
123   *
124   * @return a {@link BufferedMutator} for the supplied tableName.
125   */
126  BufferedMutator getBufferedMutator(TableName tableName) throws IOException;
127
128  /**
129   * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The
130   * {@link BufferedMutator} returned by this method is thread-safe. This object can be used for
131   * long lived table operations. If user passes ThreadPool in BufferedMutatorParams then we will
132   * use that otherwise we will create for the user. For user specified ThreadPool, it is the user's
133   * responsibility to shutdown. For ThreadPool created by us, we will shutdown when user calls
134   * {@link BufferedMutator#close()}. The caller is responsible for calling
135   * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance.
136   *
137   * @param params details on how to instantiate the {@code BufferedMutator}.
138   * @return a {@link BufferedMutator} for the supplied tableName.
139   */
140  BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException;
141
142  /**
143   * Retrieve a RegionLocator implementation to inspect region information on a table. The returned
144   * RegionLocator is not thread-safe, so a new instance should be created for each using thread.
145   *
146   * This is a lightweight operation.  Pooling or caching of the returned RegionLocator is neither
147   * required nor desired.
148   * <br>
149   * The caller is responsible for calling {@link RegionLocator#close()} on the returned
150   * RegionLocator instance.
151   *
152   * RegionLocator needs to be unmanaged
153   *
154   * @param tableName Name of the table who's region is to be examined
155   * @return A RegionLocator instance
156   */
157  RegionLocator getRegionLocator(TableName tableName) throws IOException;
158
159  /**
160   * Clear all the entries in the region location cache, for all the tables.
161   * <p/>
162   * If you only want to clear the cache for a specific table, use
163   * {@link RegionLocator#clearRegionLocationCache()}.
164   * <p/>
165   * This may cause performance issue so use it with caution.
166   */
167  void clearRegionLocationCache();
168
169  /**
170   * Retrieve an Admin implementation to administer an HBase cluster.
171   * The returned Admin is not guaranteed to be thread-safe.  A new instance should be created for
172   * each using thread.  This is a lightweight operation.  Pooling or caching of the returned
173   * Admin is not recommended.
174   * <br>
175   * The caller is responsible for calling {@link Admin#close()} on the returned
176   * Admin instance.
177   *
178   * @return an Admin instance for cluster administration
179   */
180  Admin getAdmin() throws IOException;
181
182  @Override
183  void close() throws IOException;
184
185  /**
186   * Returns whether the connection is closed or not.
187   * @return true if this connection is closed
188   */
189  boolean isClosed();
190
191  /**
192   * Returns an {@link TableBuilder} for creating {@link Table}.
193   * @param tableName the name of the table
194   * @param pool the thread pool to use for requests like batch and scan
195   */
196  TableBuilder getTableBuilder(TableName tableName, ExecutorService pool);
197
198  /**
199   * Retrieve an Hbck implementation to fix an HBase cluster.
200   * The returned Hbck is not guaranteed to be thread-safe. A new instance should be created by
201   * each thread. This is a lightweight operation. Pooling or caching of the returned Hbck instance
202   * is not recommended.
203   * <br>
204   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance.
205   *<br>
206   * This will be used mostly by hbck tool.
207   *
208   * @return an Hbck instance for active master. Active master is fetched from the zookeeper.
209   */
210  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
211  default Hbck getHbck() throws IOException {
212    throw new UnsupportedOperationException("Not implemented");
213  }
214
215  /**
216   * Retrieve an Hbck implementation to fix an HBase cluster.
217   * The returned Hbck is not guaranteed to be thread-safe. A new instance should be created by
218   * each thread. This is a lightweight operation. Pooling or caching of the returned Hbck instance
219   * is not recommended.
220   * <br>
221   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance.
222   *<br>
223   * This will be used mostly by hbck tool. This may only be used to by pass getting
224   * registered master from ZK. In situations where ZK is not available or active master is not
225   * registered with ZK and user can get master address by other means, master can be explicitly
226   * specified.
227   *
228   * @param masterServer explicit {@link ServerName} for master server
229   * @return an Hbck instance for a specified master server
230   */
231  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
232  default Hbck getHbck(ServerName masterServer) throws IOException {
233    throw new UnsupportedOperationException("Not implemented");
234  }
235}