HBASE-22344 Documented the deprecation of public and limited private …

…APIs (#208) Signed-off-by: stack <stack@apache.org>
apache · Jun 17, 2019 · 6cff25c · 6cff25c
1 parent a70c767
commit 6cff25c
Show file tree

Hide file tree

Showing 30 changed files with 326 additions and 85 deletions.
diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/HColumnDescriptor.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/HColumnDescriptor.java
@@ -162,7 +162,10 @@ protected HColumnDescriptor(ModifyableColumnFamilyDescriptor delegate) {
    * name: i.e. 'printable' and ends in a ':' (Null passes are allowed because
    * <code>b</code> can be null when deserializing).  Cannot start with a '.'
    * either. Also Family can not be an empty value or equal "recovered.edits".
-   * @deprecated Use {@link ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@link ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])} instead.
+   * @see ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public static byte [] isLegalFamilyName(final byte [] b) {

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java
@@ -597,9 +597,11 @@ public int compareTo(final HTableDescriptor other) {
   /**
    * Returns an unmodifiable collection of all the {@link HColumnDescriptor}
    * of all the column families of the table.
-   * @deprecated Use {@link #getColumnFamilies}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getColumnFamilies()} instead.
    * @return Immutable collection of {@link HColumnDescriptor} of all the
    * column families.
+   * @see #getColumnFamilies()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public Collection<HColumnDescriptor> getFamilies() {
@@ -706,8 +708,9 @@ public int getColumnFamilyCount() {
    * of the table.
    *
    * @return Array of all the HColumnDescriptors of the current table
-   *
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
    * @see #getFamilies()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   @Override
@@ -723,7 +726,10 @@ public HColumnDescriptor[] getColumnFamilies() {
    * @param column Column family name
    * @return Column descriptor for the passed family name or the family on
    * passed in column.
-   * @deprecated Use {@link #getColumnFamily(byte[])}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getColumnFamily(byte[])}
+   *   instead.
+   * @see #getColumnFamily(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public HColumnDescriptor getFamily(final byte[] column) {
@@ -846,19 +852,31 @@ public void removeCoprocessor(String className) {
   public static final HTableDescriptor NAMESPACE_TABLEDESC
     = new HTableDescriptor(TableDescriptorBuilder.NAMESPACE_TABLEDESC);
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   @Deprecated
   public HTableDescriptor setOwner(User owner) {
     getDelegateeForModification().setOwner(owner);
     return this;
   }
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   // used by admin.rb:alter(table_name,*args) to update owner.
   @Deprecated
   public HTableDescriptor setOwnerString(String ownerString) {
     getDelegateeForModification().setOwnerString(ownerString);
     return this;
   }
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   @Override
   @Deprecated
   public String getOwnerString() {

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
@@ -1110,8 +1110,10 @@ Map<ServerName, Boolean> compactionSwitch(boolean switchState, List<String> serv
    *          array we'll assign to a random server. A server name is made of host, port and
    *          startcode. Here is an example: <code> host187.example.com,60020,1289493121758</code>
    * @throws IOException if we can't find a region named <code>encodedRegionName</code>
-   * @deprecated Use {@link #move(byte[], ServerName)} instead. And if you want to move the region
-   *             to a random server, please use {@link #move(byte[])}.
+   * @deprecated since 2.2.0 and will be removed in 4.0.0. Use {@link #move(byte[], ServerName)}
+   *   instead. And if you want to move the region to a random server, please use
+   *   {@link #move(byte[])}.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-22108">HBASE-22108</a>
    */
   @Deprecated
   default void move(byte[] encodedRegionName, byte[] destServerName) throws IOException {
@@ -1873,7 +1875,8 @@ HTableDescriptor[] getTableDescriptors(List<String> names)
    * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does
    *         not exist
    * @throws IOException if a remote or network exception occurs
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   default boolean abortProcedure(long procId, boolean mayInterruptIfRunning) throws IOException {
@@ -1893,7 +1896,8 @@ default boolean abortProcedure(long procId, boolean mayInterruptIfRunning) throw
    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
    * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does not exist
    * @throws IOException if a remote or network exception occurs
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   Future<Boolean> abortProcedureAsync(

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncAdmin.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncAdmin.java
@@ -954,7 +954,8 @@ CompletableFuture<Boolean> isProcedureFinished(String signature, String instance
    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
    * @return true if aborted, false if procedure already completed or does not exist. the value is
    *         wrapped by {@link CompletableFuture}
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   CompletableFuture<Boolean> abortProcedure(long procId, boolean mayInterruptIfRunning);

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Scan.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Scan.java
@@ -196,7 +196,9 @@ public class Scan extends Query {
   public Scan() {}
 
   /**
-   * @deprecated use {@code new Scan().withStartRow(startRow).setFilter(filter)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow).setFilter(filter)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow, Filter filter) {
@@ -210,7 +212,9 @@ public Scan(byte[] startRow, Filter filter) {
    * If the specified row does not exist, the Scanner will start from the next closest row after the
    * specified row.
    * @param startRow row to start scanner at or after
-   * @deprecated use {@code new Scan().withStartRow(startRow)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow) {
@@ -221,7 +225,9 @@ public Scan(byte[] startRow) {
    * Create a Scan operation for the range of rows specified.
    * @param startRow row to start scanner at or after (inclusive)
    * @param stopRow row to stop scanner before (exclusive)
-   * @deprecated use {@code new Scan().withStartRow(startRow).withStopRow(stopRow)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow).withStopRow(stopRow)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow, byte[] stopRow) {
@@ -423,8 +429,11 @@ public Scan setTimestamp(long timestamp) {
    * @return this
    * @throws IllegalArgumentException if startRow does not meet criteria for a row key (when length
    *           exceeds {@link HConstants#MAX_ROW_LENGTH})
-   * @deprecated use {@link #withStartRow(byte[])} instead. This method may change the inclusive of
-   *             the stop row to keep compatible with the old behavior.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStartRow(byte[])}
+   *   instead. This method may change the inclusive of the stop row to keep compatible with the old
+   *   behavior.
+   * @see #withStartRow(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan setStartRow(byte[] startRow) {
@@ -483,8 +492,11 @@ public Scan withStartRow(byte[] startRow, boolean inclusive) {
    * @return this
    * @throws IllegalArgumentException if stopRow does not meet criteria for a row key (when length
    *           exceeds {@link HConstants#MAX_ROW_LENGTH})
-   * @deprecated use {@link #withStopRow(byte[])} instead. This method may change the inclusive of
-   *             the stop row to keep compatible with the old behavior.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStopRow(byte[])} instead.
+   *   This method may change the inclusive of the stop row to keep compatible with the old
+   *   behavior.
+   * @see #withStopRow(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan setStopRow(byte[] stopRow) {
@@ -601,8 +613,10 @@ private byte[] calculateTheClosestNextRowKeyForPrefix(byte[] rowKeyPrefix) {
   /**
    * Get all available versions.
    * @return this
-   * @deprecated It is easy to misunderstand with column family's max versions, so use
-   *             {@link #readAllVersions()} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
+   *   family's max versions, so use {@link #readAllVersions()} instead.
+   * @see #readAllVersions()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
    */
   @Deprecated
   public Scan setMaxVersions() {
@@ -613,8 +627,10 @@ public Scan setMaxVersions() {
    * Get up to the specified number of versions of each column.
    * @param maxVersions maximum versions for each column
    * @return this
-   * @deprecated It is easy to misunderstand with column family's max versions, so use
-   *             {@link #readVersions(int)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
+   *   family's max versions, so use {@link #readVersions(int)} instead.
+   * @see #readVersions(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
    */
   @Deprecated
   public Scan setMaxVersions(int maxVersions) {
@@ -1037,12 +1053,13 @@ public boolean isRaw() {
    * better performance for small scan. [HBASE-9488]. Generally, if the scan range is within one
    * data block(64KB), it could be considered as a small scan.
    * @param small
-   * @deprecated since 2.0.0. Use {@link #setLimit(int)} and {@link #setReadType(ReadType)} instead.
-   *             And for the one rpc optimization, now we will also fetch data when openScanner, and
-   *             if the number of rows reaches the limit then we will close the scanner
-   *             automatically which means we will fall back to one rpc.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #setLimit(int)} and
+   *   {@link #setReadType(ReadType)} instead. And for the one rpc optimization, now we will also
+   *   fetch data when openScanner, and if the number of rows reaches the limit then we will close
+   *   the scanner automatically which means we will fall back to one rpc.
    * @see #setLimit(int)
    * @see #setReadType(ReadType)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
    */
   @Deprecated
   public Scan setSmall(boolean small) {
@@ -1054,7 +1071,9 @@ public Scan setSmall(boolean small) {
   /**
    * Get whether this scan is a small scan
    * @return true if small scan
-   * @deprecated since 2.0.0. See the comment of {@link #setSmall(boolean)}
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. See the comment of
+   *   {@link #setSmall(boolean)}
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
    */
   @Deprecated
   public boolean isSmall() {

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/SnapshotDescription.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/SnapshotDescription.java
@@ -37,7 +37,10 @@ public SnapshotDescription(String name) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table) {
@@ -49,7 +52,10 @@ public SnapshotDescription(String name, TableName table) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type) {
@@ -61,7 +67,10 @@ public SnapshotDescription(String name, TableName table, SnapshotType type) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType, String)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type, String owner) {
@@ -73,7 +82,10 @@ public SnapshotDescription(String name, TableName table, SnapshotType type, Stri
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType, String, long, int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type, String owner,
@@ -96,7 +108,11 @@ public String getName() {
   }
 
   /**
-   * @deprecated Use getTableName() or getTableNameAsString() instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getTableName()} or
+   *   {@link #getTableNameAsString()} instead.
+   * @see #getTableName()
+   * @see #getTableNameAsString()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public String getTable() {

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptor.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptor.java
@@ -191,6 +191,10 @@ default Collection<String> getCoprocessors() {
    */
   TableName getTableName();
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   String getOwnerString();
 

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptorBuilder.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptorBuilder.java
@@ -272,6 +272,7 @@ public class TableDescriptorBuilder {
       CP_HTD_ATTR_VALUE_PARAM_VALUE_PATTERN + "),?");
   private static final Pattern CP_HTD_ATTR_KEY_PATTERN =
     Pattern.compile("^coprocessor\\$([0-9]+)$", Pattern.CASE_INSENSITIVE);
+
   /**
    * Table descriptor for namespace table
    */
@@ -288,6 +289,7 @@ public class TableDescriptorBuilder {
         .setScope(HConstants.REPLICATION_SCOPE_LOCAL)
         .build())
       .build();
+
   private final ModifyableTableDescriptor desc;
 
   /**
@@ -488,12 +490,20 @@ public TableDescriptorBuilder setNormalizationEnabled(final boolean isEnable) {
     return this;
   }
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   public TableDescriptorBuilder setOwner(User owner) {
     desc.setOwner(owner);
     return this;
   }
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   public TableDescriptorBuilder setOwnerString(String ownerString) {
     desc.setOwnerString(ownerString);
@@ -1532,17 +1542,29 @@ public void removeCoprocessor(String className) {
       }
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     @Deprecated
     public ModifyableTableDescriptor setOwner(User owner) {
       return setOwnerString(owner != null ? owner.getShortName() : null);
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     // used by admin.rb:alter(table_name,*args) to update owner.
     @Deprecated
     public ModifyableTableDescriptor setOwnerString(String ownerString) {
       return setValue(OWNER_KEY, ownerString);
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     @Override
     @Deprecated
     public String getOwnerString() {

diff --git a/...t/src/main/java/org/apache/hadoop/hbase/filter/FirstKeyValueMatchingQualifiersFilter.java b/...t/src/main/java/org/apache/hadoop/hbase/filter/FirstKeyValueMatchingQualifiersFilter.java
@@ -43,7 +43,8 @@
  * caveat, this filter is only useful for special cases
  * like org.apache.hadoop.hbase.mapreduce.RowCounter.
  * <p>
- * @deprecated Deprecated in 2.0. See HBASE-13347
+ * @deprecated Deprecated in 2.0.0 and will be removed in 3.0.0.
+ * @see <a href="https://issues.apache.org/jira/browse/HBASE-13347">HBASE-13347</a>
  */
 @InterfaceAudience.Public
 @Deprecated