1 /** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 * See the License for the specific language governing permissions and 17 * limitations under the License. 18 */ 19 package org.apache.hadoop.hbase.client; 20 21 import java.io.Closeable; 22 import java.io.IOException; 23 import java.util.concurrent.ExecutorService; 24 25 import org.apache.hadoop.hbase.classification.InterfaceAudience; 26 import org.apache.hadoop.hbase.classification.InterfaceStability; 27 import org.apache.hadoop.conf.Configuration; 28 import org.apache.hadoop.hbase.Abortable; 29 import org.apache.hadoop.hbase.TableName; 30 31 /** 32 * A cluster connection encapsulating lower level individual connections to actual servers and 33 * a connection to zookeeper. Connections are instantiated through the {@link ConnectionFactory} 34 * class. The lifecycle of the connection is managed by the caller, who has to {@link #close()} 35 * the connection to release the resources. 36 * 37 * <p> The connection object contains logic to find the master, locate regions out on the cluster, 38 * keeps a cache of locations and then knows how to re-calibrate after they move. The individual 39 * connections to servers, meta cache, zookeeper connection, etc are all shared by the 40 * {@link Table} and {@link Admin} instances obtained from this connection. 41 * 42 * <p> Connection creation is a heavy-weight operation. Connection implementations are thread-safe, 43 * so that the client can create a connection once, and share it with different threads. 44 * {@link Table} and {@link Admin} instances, on the other hand, are light-weight and are not 45 * thread-safe. Typically, a single connection per client application is instantiated and every 46 * thread will obtain its own Table instance. Caching or pooling of {@link Table} and {@link Admin} 47 * is not recommended. 48 * 49 * <p>This class replaces {@link HConnection}, which is now deprecated. 50 * @see ConnectionFactory 51 * @since 0.99.0 52 */ 53 @InterfaceAudience.Public 54 @InterfaceStability.Evolving 55 public interface Connection extends Abortable, Closeable { 56 57 /* 58 * Implementation notes: 59 * - Only allow new style of interfaces: 60 * -- All table names are passed as TableName. No more byte[] and string arguments 61 * -- Most of the classes with names H is deprecated in favor of non-H versions 62 * (Table, Connection vs HConnection, etc) 63 * -- Only real client-facing public methods are allowed 64 * - Connection should contain only getTable(), getAdmin() kind of general methods. 65 */ 66 67 /** 68 * @return Configuration instance being used by this Connection instance. 69 */ 70 Configuration getConfiguration(); 71 72 /** 73 * Retrieve a Table implementation for accessing a table. 74 * The returned Table is not thread safe, a new instance should be created for each using thread. 75 * This is a lightweight operation, pooling or caching of the returned Table 76 * is neither required nor desired. 77 * <br> 78 * The caller is responsible for calling {@link Table#close()} on the returned 79 * table instance. 80 * 81 * @param tableName the name of the table 82 * @return a Table to use for interactions with this table 83 */ 84 Table getTable(TableName tableName) throws IOException; 85 86 /** 87 * Retrieve a Table implementation for accessing a table. 88 * The returned Table is not thread safe, a new instance should be created for each using thread. 89 * This is a lightweight operation, pooling or caching of the returned Table 90 * is neither required nor desired. 91 * <br> 92 * The caller is responsible for calling {@link Table#close()} on the returned 93 * table instance. 94 * 95 * @param tableName the name of the table 96 * @param pool The thread pool to use for batch operations, null to use a default pool. 97 * @return a Table to use for interactions with this table 98 */ 99 Table getTable(TableName tableName, ExecutorService pool) throws IOException; 100 101 /** 102 * <p> 103 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 104 * {@link BufferedMutator} returned by this method is thread-safe. This BufferedMutator will 105 * use the Connection's ExecutorService. This object can be used for long lived operations. 106 * </p> 107 * <p> 108 * The caller is responsible for calling {@link BufferedMutator#close()} on 109 * the returned {@link BufferedMutator} instance. 110 * </p> 111 * <p> 112 * This accessor will use the connection's ExecutorService and will throw an 113 * exception in the main thread when an asynchronous exception occurs. 114 * 115 * @param tableName the name of the table 116 * 117 * @return a {@link BufferedMutator} for the supplied tableName. 118 */ 119 public BufferedMutator getBufferedMutator(TableName tableName) throws IOException; 120 121 /** 122 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The 123 * {@link BufferedMutator} returned by this method is thread-safe. This object can be used for 124 * long lived table operations. The caller is responsible for calling 125 * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance. 126 * 127 * @param params details on how to instantiate the {@code BufferedMutator}. 128 * @return a {@link BufferedMutator} for the supplied tableName. 129 */ 130 public BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException; 131 132 /** 133 * Retrieve a RegionLocator implementation to inspect region information on a table. The returned 134 * RegionLocator is not thread-safe, so a new instance should be created for each using thread. 135 * 136 * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither 137 * required nor desired. 138 * <br> 139 * The caller is responsible for calling {@link RegionLocator#close()} on the returned 140 * RegionLocator instance. 141 * 142 * RegionLocator needs to be unmanaged 143 * 144 * @param tableName Name of the table who's region is to be examined 145 * @return A RegionLocator instance 146 */ 147 public RegionLocator getRegionLocator(TableName tableName) throws IOException; 148 149 /** 150 * Retrieve an Admin implementation to administer an HBase cluster. 151 * The returned Admin is not guaranteed to be thread-safe. A new instance should be created for 152 * each using thread. This is a lightweight operation. Pooling or caching of the returned 153 * Admin is not recommended. 154 * <br> 155 * The caller is responsible for calling {@link Admin#close()} on the returned 156 * Admin instance. 157 * 158 * @return an Admin instance for cluster administration 159 */ 160 Admin getAdmin() throws IOException; 161 162 @Override 163 public void close() throws IOException; 164 165 /** 166 * Returns whether the connection is closed or not. 167 * @return true if this connection is closed 168 */ 169 boolean isClosed(); 170 171 }