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  /**
063   * @return Configuration instance being used by this Connection instance.
064   */
065  Configuration getConfiguration();
066
067  /**
068   * Retrieve a Table implementation for accessing a table. The returned Table is not thread safe, a
069   * new instance should be created for each using thread. This is a lightweight operation, pooling
070   * or caching of the returned Table is neither required nor desired.
071   * <p>
072   * The caller is responsible for calling {@link Table#close()} on the returned table instance.
073   * <p>
074   * Since 0.98.1 this method no longer checks table existence. An exception will be thrown if the
075   * table does not exist only when the first operation is attempted.
076   * @param tableName the name of the table
077   * @return a Table to use for interactions with this table
078   */
079  default Table getTable(TableName tableName) throws IOException {
080    return getTable(tableName, null);
081  }
082
083  /**
084   * Retrieve a Table implementation for accessing a table. The returned Table is not thread safe, a
085   * new instance should be created for each using thread. This is a lightweight operation, pooling
086   * or caching of the returned Table is neither required nor desired.
087   * <p>
088   * The caller is responsible for calling {@link Table#close()} on the returned table instance.
089   * <p>
090   * Since 0.98.1 this method no longer checks table existence. An exception will be thrown if the
091   * table does not exist only when the first operation is attempted.
092   * @param tableName the name of the table
093   * @param pool      The thread pool to use for batch operations, null to use a default pool.
094   * @return a Table to use for interactions with this table
095   */
096  default Table getTable(TableName tableName, ExecutorService pool) throws IOException {
097    return getTableBuilder(tableName, pool).build();
098  }
099
100  /**
101   * <p>
102   * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The
103   * {@link BufferedMutator} returned by this method is thread-safe. This BufferedMutator will use
104   * the Connection's ExecutorService. This object can be used for long lived operations.
105   * </p>
106   * <p>
107   * The caller is responsible for calling {@link BufferedMutator#close()} on the returned
108   * {@link BufferedMutator} instance.
109   * </p>
110   * <p>
111   * This accessor will use the connection's ExecutorService and will throw an exception in the main
112   * thread when an asynchronous exception occurs.
113   * @param tableName the name of the table
114   * @return a {@link BufferedMutator} for the supplied tableName.
115   */
116  default BufferedMutator getBufferedMutator(TableName tableName) throws IOException {
117    return getBufferedMutator(new BufferedMutatorParams(tableName));
118  }
119
120  /**
121   * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The
122   * {@link BufferedMutator} returned by this method is thread-safe. This object can be used for
123   * long lived table operations. The caller is responsible for calling
124   * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance.
125   * @param params details on how to instantiate the {@code BufferedMutator}.
126   * @return a {@link BufferedMutator} for the supplied tableName.
127   */
128  BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException;
129
130  /**
131   * Retrieve a RegionLocator implementation to inspect region information on a table. The returned
132   * RegionLocator is not thread-safe, so a new instance should be created for each using thread.
133   * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither
134   * required nor desired. <br>
135   * The caller is responsible for calling {@link RegionLocator#close()} on the returned
136   * RegionLocator instance. RegionLocator needs to be unmanaged
137   * @param tableName Name of the table who's region is to be examined
138   * @return A RegionLocator instance
139   */
140  RegionLocator getRegionLocator(TableName tableName) throws IOException;
141
142  /**
143   * Clear all the entries in the region location cache, for all the tables.
144   * <p/>
145   * If you only want to clear the cache for a specific table, use
146   * {@link RegionLocator#clearRegionLocationCache()}.
147   * <p/>
148   * This may cause performance issue so use it with caution.
149   */
150  void clearRegionLocationCache();
151
152  /**
153   * Retrieve an Admin implementation to administer an HBase cluster. The returned Admin is not
154   * guaranteed to be thread-safe. A new instance should be created for each using thread. This is a
155   * lightweight operation. Pooling or caching of the returned Admin is not recommended. <br>
156   * The caller is responsible for calling {@link Admin#close()} on the returned Admin instance.
157   * @return an Admin instance for cluster administration
158   */
159  Admin getAdmin() throws IOException;
160
161  @Override
162  void close() throws IOException;
163
164  /**
165   * Returns whether the connection is closed or not.
166   * @return true if this connection is closed
167   */
168  boolean isClosed();
169
170  /**
171   * Returns an {@link TableBuilder} for creating {@link Table}.
172   * @param tableName the name of the table
173   * @param pool      the thread pool to use for requests like batch and scan
174   */
175  TableBuilder getTableBuilder(TableName tableName, ExecutorService pool);
176
177  /**
178   * Convert this connection to an {@link AsyncConnection}.
179   * <p/>
180   * Usually we will return the same instance if you call this method multiple times so you can
181   * consider this as a light-weighted operation.
182   */
183  AsyncConnection toAsyncConnection();
184
185  /**
186   * @return the cluster ID unique to this HBase cluster.
187   */
188  String getClusterId();
189
190  /**
191   * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to
192   * be thread-safe. A new instance should be created by each thread. This is a lightweight
193   * operation. Pooling or caching of the returned Hbck instance is not recommended. <br>
194   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. <br>
195   * This will be used mostly by hbck tool.
196   * @return an Hbck instance for active master. Active master is fetched from the zookeeper.
197   */
198  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
199  default Hbck getHbck() throws IOException {
200    return FutureUtils.get(toAsyncConnection().getHbck());
201  }
202
203  /**
204   * Retrieve an Hbck implementation to fix an HBase cluster. The returned Hbck is not guaranteed to
205   * be thread-safe. A new instance should be created by each thread. This is a lightweight
206   * operation. Pooling or caching of the returned Hbck instance is not recommended. <br>
207   * The caller is responsible for calling {@link Hbck#close()} on the returned Hbck instance. <br>
208   * This will be used mostly by hbck tool. This may only be used to by pass getting registered
209   * master from ZK. In situations where ZK is not available or active master is not registered with
210   * ZK and user can get master address by other means, master can be explicitly specified.
211   * @param masterServer explicit {@link ServerName} for master server
212   * @return an Hbck instance for a specified master server
213   */
214  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.HBCK)
215  default Hbck getHbck(ServerName masterServer) throws IOException {
216    return toAsyncConnection().getHbck(masterServer);
217  }
218}