hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From e...@apache.org
Subject git commit: HBASE-12083 Deprecate new HBaseAdmin() in favor of Connection.getAdmin()
Date Mon, 13 Oct 2014 20:20:29 GMT
Repository: hbase
Updated Branches:
  refs/heads/master 9a893a9c6 -> 6abb88386


HBASE-12083 Deprecate new HBaseAdmin() in favor of Connection.getAdmin()


Project: http://git-wip-us.apache.org/repos/asf/hbase/repo
Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/6abb8838
Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/6abb8838
Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/6abb8838

Branch: refs/heads/master
Commit: 6abb883865ff4dee56e53ad7ba547cb7ef033722
Parents: 9a893a9
Author: Enis Soztutar <enis@apache.org>
Authored: Mon Oct 13 13:20:16 2014 -0700
Committer: Enis Soztutar <enis@apache.org>
Committed: Mon Oct 13 13:20:16 2014 -0700

----------------------------------------------------------------------
 .../org/apache/hadoop/hbase/client/Admin.java   | 12 ++++++-
 .../apache/hadoop/hbase/client/Connection.java  | 21 +++++++++---
 .../hadoop/hbase/client/ConnectionFactory.java  | 12 +++++--
 .../apache/hadoop/hbase/client/HBaseAdmin.java  | 35 ++++++++++++++------
 .../org/apache/hadoop/hbase/client/HTable.java  | 14 ++++++--
 .../hadoop/hbase/client/RegionLocator.java      |  3 ++
 .../org/apache/hadoop/hbase/client/Table.java   | 11 ++++--
 7 files changed, 84 insertions(+), 24 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java
index 6bb314d..adf6616 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java
+++ b/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.
+ * <p>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();
 

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java
index c97167a..92b3f04 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Connection.java
+++ b/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;
  *
  * <p>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.
-   * 
+   * <br>
+   * 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.
+   * <br>
+   * 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.
+   * <br>
+   * 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.
+   * <br>
+   * The caller is responsible for calling {@link Admin#close()} on the returned
+   * Admin instance.
    *
    * @return an Admin instance for cluster administration
    */

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java
b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java
index aedaade..4af6740 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/ConnectionFactory.java
+++ b/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();
  * }
  * </pre>
- * 
- * 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.
+   * <br>
    * 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.
+   * <br>
    * 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.
+   * <br>
    * 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.
+   * <br>
    * 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.
+   * <br>
    * The caller is responsible for calling {@link Connection#close()} on the returned
    * connection instance.
    *

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java
index c6d5e2e..c740b5c 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java
+++ b/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.
  *
- * <p>See {@link HTable} to add, update, and delete data from an individual table.
- * <p>Currently HBaseAdmin instances are not expected to be long-lived.  For
- * example, an HBaseAdmin instance will not ride over a Master restart.
+ * <p>Connection should be an <i>unmanaged</i> 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<Void>(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);
    * </pre></blockquote></div>
-   * 
+   *
    * @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);
   }
-  
+
 }

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java
index fafa604..a1650c1 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/HTable.java
+++ b/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.
+ * <p>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);

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java
b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java
index 2d56c0e..677b3c5 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionLocator.java
+++ b/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

http://git-wip-us.apache.org/repos/asf/hbase/blob/6abb8838/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java
----------------------------------------------------------------------
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java
index ba8251d..07e4c08 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java
+++ b/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.
  *
+ * <p>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.


Mime
View raw message