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 * <p>
78 * The caller is responsible for calling {@link Table#close()} on the returned
79 * table instance.
80 * <p>
81 * Since 0.98.1 this method no longer checks table existence. An exception
82 * will be thrown if the table does not exist only when the first operation is
83 * attempted.
84 * @param tableName the name of the table
85 * @return a Table to use for interactions with this table
86 */
87 Table getTable(TableName tableName) throws IOException;
88
89 /**
90 * Retrieve a Table implementation for accessing a table.
91 * The returned Table is not thread safe, a new instance should be created for each using thread.
92 * This is a lightweight operation, pooling or caching of the returned Table
93 * is neither required nor desired.
94 * <p>
95 * The caller is responsible for calling {@link Table#close()} on the returned
96 * table instance.
97 * <p>
98 * Since 0.98.1 this method no longer checks table existence. An exception
99 * will be thrown if the table does not exist only when the first operation is
100 * attempted.
101 *
102 * @param tableName the name of the table
103 * @param pool The thread pool to use for batch operations, null to use a default pool.
104 * @return a Table to use for interactions with this table
105 */
106 Table getTable(TableName tableName, ExecutorService pool) throws IOException;
107
108 /**
109 * <p>
110 * Retrieve a {@link BufferedMutator} for performing client-side buffering of writes. The
111 * {@link BufferedMutator} returned by this method is thread-safe. This BufferedMutator will
112 * use the Connection's ExecutorService. This object can be used for long lived operations.
113 * </p>
114 * <p>
115 * The caller is responsible for calling {@link BufferedMutator#close()} on
116 * the returned {@link BufferedMutator} instance.
117 * </p>
118 * <p>
119 * This accessor will use the connection's ExecutorService and will throw an
120 * exception in the main thread when an asynchronous exception occurs.
121 *
122 * @param tableName the name of the table
123 *
124 * @return a {@link BufferedMutator} for the supplied tableName.
125 */
126 public 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. The caller is responsible for calling
132 * {@link BufferedMutator#close()} on the returned {@link BufferedMutator} instance.
133 *
134 * @param params details on how to instantiate the {@code BufferedMutator}.
135 * @return a {@link BufferedMutator} for the supplied tableName.
136 */
137 public BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException;
138
139 /**
140 * Retrieve a RegionLocator implementation to inspect region information on a table. The returned
141 * RegionLocator is not thread-safe, so a new instance should be created for each using thread.
142 *
143 * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither
144 * required nor desired.
145 * <br>
146 * The caller is responsible for calling {@link RegionLocator#close()} on the returned
147 * RegionLocator instance.
148 *
149 * RegionLocator needs to be unmanaged
150 *
151 * @param tableName Name of the table who's region is to be examined
152 * @return A RegionLocator instance
153 */
154 public RegionLocator getRegionLocator(TableName tableName) throws IOException;
155
156 /**
157 * Retrieve an Admin implementation to administer an HBase cluster.
158 * The returned Admin is not guaranteed to be thread-safe. A new instance should be created for
159 * each using thread. This is a lightweight operation. Pooling or caching of the returned
160 * Admin is not recommended.
161 * <br>
162 * The caller is responsible for calling {@link Admin#close()} on the returned
163 * Admin instance.
164 *
165 * @return an Admin instance for cluster administration
166 */
167 Admin getAdmin() throws IOException;
168
169 @Override
170 public void close() throws IOException;
171
172 /**
173 * Returns whether the connection is closed or not.
174 * @return true if this connection is closed
175 */
176 boolean isClosed();
177
178 }