diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java index 6bb314d..adf6616 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java @@ -35,6 +35,8 @@ import org.apache.hadoop.hbase.TableNotFoundException; import org.apache.hadoop.hbase.UnknownRegionException; import org.apache.hadoop.hbase.ZooKeeperConnectionException; import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel; +import org.apache.hadoop.hbase.classification.InterfaceAudience; +import org.apache.hadoop.hbase.classification.InterfaceStability; import org.apache.hadoop.hbase.protobuf.generated.AdminProtos; import org.apache.hadoop.hbase.protobuf.generated.HBaseProtos; import org.apache.hadoop.hbase.protobuf.generated.MasterProtos; @@ -55,10 +57,18 @@ import java.util.Map; import java.util.regex.Pattern; /** - * The administrative API for HBase. Obtain an instance from a {@link Connection}. + * The administrative API for HBase. Obtain an instance from an {@link Connection#getAdmin()} and + * call {@link #close()} afterwards. + *

Admin can be used to create, drop, list, enable and disable tables, add and drop table + * column families and other administrative operations. * + * @see ConnectionFactory + * @see Connection + * @see Table * @since 0.99.0 */ +@InterfaceAudience.Public +@InterfaceStability.Evolving public interface Admin extends Abortable, Closeable { int getOperationTimeout(); diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java index c97167a..92b3f04 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java @@ -1,5 +1,5 @@ /** - * + * * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information @@ -48,6 +48,7 @@ import org.apache.hadoop.hbase.TableName; * *

This class replaces {@link HConnection}, which is now deprecated. * @see ConnectionFactory + * @since 0.99.0 */ @InterfaceAudience.Public @InterfaceStability.Evolving @@ -60,11 +61,11 @@ public interface Connection extends Abortable, Closeable { * -- Most of the classes with names H is deprecated in favor of non-H versions * (Table, Connection vs HConnection, etc) * -- Only real client-facing public methods are allowed - * - Connection should contain only getTable(), gAdmin() kind of general methods. + * - Connection should contain only getTable(), getAdmin() kind of general methods. */ /** - * @return Configuration instance being used by this HConnection instance. + * @return Configuration instance being used by this Connection instance. */ Configuration getConfiguration(); @@ -73,7 +74,10 @@ public interface Connection extends Abortable, Closeable { * The returned Table is not thread safe, a new instance should be created for each using thread. * This is a lightweight operation, pooling or caching of the returned Table * is neither required nor desired. - * + *
+ * The caller is responsible for calling {@link Table#close()} on the returned + * table instance. + * * @param tableName the name of the table * @return a Table to use for interactions with this table */ @@ -84,6 +88,9 @@ public interface Connection extends Abortable, Closeable { * The returned Table is not thread safe, a new instance should be created for each using thread. * This is a lightweight operation, pooling or caching of the returned Table * is neither required nor desired. + *
+ * The caller is responsible for calling {@link Table#close()} on the returned + * table instance. * * @param tableName the name of the table * @param pool The thread pool to use for batch operations, null to use a default pool. @@ -97,6 +104,9 @@ public interface Connection extends Abortable, Closeable { * * This is a lightweight operation. Pooling or caching of the returned RegionLocator is neither * required nor desired. + *
+ * The caller is responsible for calling {@link RegionLocator#close()} on the returned + * RegionLocator instance. * * RegionLocator needs to be unmanaged * @@ -110,6 +120,9 @@ public interface Connection extends Abortable, Closeable { * The returned Admin is not guaranteed to be thread-safe. A new instance should be created for * each using thread. This is a lightweight operation. Pooling or caching of the returned * Admin is not recommended. + *
+ * The caller is responsible for calling {@link Admin#close()} on the returned + * Admin instance. * * @return an Admin instance for cluster administration */ diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java index aedaade..4af6740 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java @@ -47,10 +47,13 @@ import org.apache.hadoop.hbase.security.UserProvider; * connection.close(); * } * - * - * Similarly, {@link Connection} also returns {@link RegionLocator} implementations. + * + * Similarly, {@link Connection} also returns {@link Admin} and {@link RegionLocator} + * implementations. * * This class replaces {@link HConnectionManager}, which is now deprecated. + * @see Connection + * @since 0.99.0 */ @InterfaceAudience.Public @InterfaceStability.Evolving @@ -65,6 +68,7 @@ public class ConnectionFactory { * encapsulates all housekeeping for a connection to the cluster. All tables and interfaces * created from returned connection share zookeeper connection, meta cache, and connections * to region servers and masters. + *
* The caller is responsible for calling {@link Connection#close()} on the returned * connection instance. * @@ -92,6 +96,7 @@ public class ConnectionFactory { * encapsulates all housekeeping for a connection to the cluster. All tables and interfaces * created from returned connection share zookeeper connection, meta cache, and connections * to region servers and masters. + *
* The caller is responsible for calling {@link Connection#close()} on the returned * connection instance. * @@ -120,6 +125,7 @@ public class ConnectionFactory { * encapsulates all housekeeping for a connection to the cluster. All tables and interfaces * created from returned connection share zookeeper connection, meta cache, and connections * to region servers and masters. + *
* The caller is responsible for calling {@link Connection#close()} on the returned * connection instance. * @@ -150,6 +156,7 @@ public class ConnectionFactory { * encapsulates all housekeeping for a connection to the cluster. All tables and interfaces * created from returned connection share zookeeper connection, meta cache, and connections * to region servers and masters. + *
* The caller is responsible for calling {@link Connection#close()} on the returned * connection instance. * @@ -180,6 +187,7 @@ public class ConnectionFactory { * encapsulates all housekeeping for a connection to the cluster. All tables and interfaces * created from returned connection share zookeeper connection, meta cache, and connections * to region servers and masters. + *
* The caller is responsible for calling {@link Connection#close()} on the returned * connection instance. * diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java index c6d5e2e..c740b5c 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java @@ -157,15 +157,22 @@ import com.google.protobuf.ByteString; import com.google.protobuf.ServiceException; /** - * Provides an interface to manage HBase database table metadata + general - * administrative functions. Use HBaseAdmin to create, drop, list, enable and - * disable tables. Use it also to add and drop table column families. + * HBaseAdmin is no longer a client API. It is marked InterfaceAudience.Private indicating that + * this is an HBase-internal class as defined in + * https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/InterfaceClassification.html + * There are no guarantees for backwards source / binary compatibility and methods or class can + * change or go away without deprecation. + * Use {@link Connection#getAdmin()} to obtain an instance of {@link Admin} instead of constructing + * an HBaseAdmin directly. * - *

See {@link HTable} to add, update, and delete data from an individual table. - *

Currently HBaseAdmin instances are not expected to be long-lived. For - * example, an HBaseAdmin instance will not ride over a Master restart. + *

Connection should be an unmanaged connection obtained via + * {@link ConnectionFactory#createConnection(Configuration)} + * + * @see ConnectionFactory + * @see Connection + * @see Admin */ -@InterfaceAudience.Public +@InterfaceAudience.Private @InterfaceStability.Evolving public class HBaseAdmin implements Admin { private static final Log LOG = LogFactory.getLog(HBaseAdmin.class); @@ -195,7 +202,10 @@ public class HBaseAdmin implements Admin { * See {@link #HBaseAdmin(Connection connection)} * * @param c Configuration object. Copied internally. + * @deprecated Constructing HBaseAdmin objects manually has been deprecated. + * Use {@link Connection#getAdmin()} to obtain an instance of {@link Admin} instead. */ + @Deprecated public HBaseAdmin(Configuration c) throws MasterNotRunningException, ZooKeeperConnectionException, IOException { // Will not leak connections, as the new implementation of the constructor @@ -217,7 +227,8 @@ public class HBaseAdmin implements Admin { * @param connection The Connection instance to use * @throws MasterNotRunningException, ZooKeeperConnectionException are not * thrown anymore but kept into the interface for backward api compatibility - * @deprecated Do not use this internal ctor. + * @deprecated Constructing HBaseAdmin objects manually has been deprecated. + * Use {@link Connection#getAdmin()} to obtain an instance of {@link Admin} instead. */ @Deprecated public HBaseAdmin(Connection connection) @@ -3579,6 +3590,7 @@ public class HBaseAdmin implements Admin { * @param quota the quota settings * @throws IOException if a remote or network exception occurs */ + @Override public void setQuota(final QuotaSettings quota) throws IOException { executeCallable(new MasterCallable(getConnection()) { @Override @@ -3596,6 +3608,7 @@ public class HBaseAdmin implements Admin { * @return the quota scanner * @throws IOException if a remote or network exception occurs */ + @Override public QuotaRetriever getQuotaRetriever(final QuotaFilter filter) throws IOException { return QuotaRetriever.open(conf, filter); } @@ -3689,7 +3702,7 @@ public class HBaseAdmin implements Admin { return true; } } - + /** * Creates and returns a {@link com.google.protobuf.RpcChannel} instance * connected to the passed region server. @@ -3708,7 +3721,7 @@ public class HBaseAdmin implements Admin { * .build(); * MyCallResponse response = service.myCall(null, request); * - * + * * @param sn the server name to which the endpoint call is made * @return A RegionServerCoprocessorRpcChannel instance */ @@ -3716,5 +3729,5 @@ public class HBaseAdmin implements Admin { public CoprocessorRpcChannel coprocessorService(ServerName sn) { return new RegionServerCoprocessorRpcChannel(connection, sn); } - + } diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java index fafa604..a1650c1 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java @@ -80,7 +80,14 @@ import com.google.protobuf.Service; import com.google.protobuf.ServiceException; /** - * An implementation of {@link Table}. Used to communicate with a single HBase table. + * + * HTable is no longer a client API. It is marked InterfaceAudience.Private indicating that + * this is an HBase-internal class as defined in + * https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/InterfaceClassification.html + * There are no guarantees for backwards source / binary compatibility and methods or class can + * change or go away without deprecation. Use {@link Connection#getTable(TableName)} + * to obtain an instance of {@link Table} instead of constructing an HTable directly. + *

An implementation of {@link Table}. Used to communicate with a single HBase table. * Lightweight. Get as needed and just close when done. * Instances of this class SHOULD NOT be constructed directly. * Obtain an instance via {@link Connection}. See {@link ConnectionFactory} @@ -91,11 +98,12 @@ import com.google.protobuf.ServiceException; * be corrupted if multiple threads contend over a single HTable instance. * In the case of reads, some fields used by a Scan are shared among all threads. * - * @see Admin for create, drop, list, enable and disable of tables. + * @see Table + * @see Admin * @see Connection * @see ConnectionFactory */ -@InterfaceAudience.Public +@InterfaceAudience.Private @InterfaceStability.Stable public class HTable implements HTableInterface, RegionLocator { private static final Log LOG = LogFactory.getLog(HTable.class); diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java index 2d56c0e..677b3c5 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java @@ -32,6 +32,9 @@ import java.util.List; * Used to view region location information for a single HBase table. * Obtain an instance from an {@link HConnection}. * + * @see ConnectionFactory + * @see Connection + * @see Table * @since 0.99.0 */ @InterfaceAudience.Public diff --git hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java index ba8251d..07e4c08 100644 --- hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java +++ hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java @@ -27,6 +27,7 @@ import com.google.protobuf.Descriptors; import com.google.protobuf.Message; import com.google.protobuf.Service; import com.google.protobuf.ServiceException; + import org.apache.hadoop.hbase.classification.InterfaceAudience; import org.apache.hadoop.hbase.classification.InterfaceStability; import org.apache.hadoop.conf.Configuration; @@ -38,13 +39,17 @@ import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel; /** * Used to communicate with a single HBase table. - * Obtain an instance from a {@link Connection}. + * Obtain an instance from a {@link Connection} and call {@link #close()} afterwards. * + *

Table can be used to get, put, delete or scan data from a table. + * @see ConnectionFactory + * @see Connection + * @see Admin + * @see RegionLocator * @since 0.99.0 */ - @InterfaceAudience.Public -@InterfaceStability.Stable +@InterfaceStability.Evolving public interface Table extends Closeable { /** * Gets the fully qualified table name instance of this table.