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