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 74bb5d8..2f449f8 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 @@ -31,6 +31,8 @@ import org.apache.hadoop.hbase.TableExistsException; import org.apache.hadoop.hbase.TableName; import org.apache.hadoop.hbase.TableNotFoundException; import org.apache.hadoop.hbase.UnknownRegionException; +import org.apache.hadoop.hbase.classification.InterfaceAudience; +import org.apache.hadoop.hbase.classification.InterfaceStability; import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel; import org.apache.hadoop.hbase.protobuf.generated.AdminProtos; import org.apache.hadoop.hbase.protobuf.generated.HBaseProtos; @@ -52,10 +54,18 @@ import java.util.Map; import java.util.regex.Pattern; /** - * The administrative API for HBase. Obtain an instance from an {@link HConnection}. + * 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 e9e2227..252966a 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
@@ -155,15 +155,16 @@ 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 public visible class. Use {@link Connection#getAdmin()}
+ * to obtain an instance of {@link Admin} instead of constructing an HBaseAdmin directly. Connection
+ * should be an unmanaged connection obtained via
+ * {@link ConnectionFactory#createConnection(Configuration)}
*
- *
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. + * @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); @@ -193,7 +194,10 @@ public class HBaseAdmin implements Admin { * See {@link #HBaseAdmin(Connection connection)} * * @param c Configuration object. Copied internally. + * @deprecated HBaseAdmin is no longer a public visible class. 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 @@ -215,7 +219,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 HBaseAdmin is no longer a public visible class. Use {@link Connection#getAdmin()} + * to obtain an instance of {@link Admin} instead. */ @Deprecated public HBaseAdmin(Connection connection) 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 ee7db15..7f7b9d7 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 @@ -82,7 +82,9 @@ 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 public visible class. 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} @@ -93,11 +95,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 505e841..6fb6e39 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 @@ -31,6 +31,9 @@ import java.io.IOException; * 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.