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

…APIs
apache · Apr 30, 2019 · 578ba41 · 578ba41
1 parent 2c7fdb3
commit 578ba41
Show file tree

Hide file tree

Showing 58 changed files with 594 additions and 121 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
@@ -598,9 +598,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() {
@@ -707,8 +709,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
@@ -724,7 +727,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) {
@@ -857,19 +863,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
@@ -706,8 +706,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 {
@@ -1179,7 +1181,8 @@ List<TableDescriptor> listTableDescriptors(List<TableName> tableNames)
    * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does
    *         not exist
    * @throws IOException
-   * @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 {
@@ -1199,7 +1202,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
-   * @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(long procId, boolean mayInterruptIfRunning)

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
@@ -969,7 +969,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
@@ -182,7 +182,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) {
@@ -196,7 +198,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) {
@@ -207,7 +211,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) {
@@ -409,8 +415,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) {
@@ -469,8 +478,10 @@ 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) {
@@ -587,8 +598,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() {
@@ -599,8 +612,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) {
@@ -1023,12 +1038,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) {
@@ -1040,7 +1056,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/Table.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java
@@ -773,8 +773,11 @@ default long getRpcTimeout(TimeUnit unit) {
    * Get timeout (millisecond) of each rpc request in this Table instance.
    *
    * @return Currently configured read timeout
-   * @deprecated use {@link #getReadRpcTimeout(TimeUnit)} or
-   *             {@link #getWriteRpcTimeout(TimeUnit)} instead
+   * @deprecated since 1.4.0 and will be removed in 3.0.0. Use {@link #getReadRpcTimeout(TimeUnit)}
+   *  or {@link #getWriteRpcTimeout(TimeUnit)} instead.
+   * @see #getReadRpcTimeout(TimeUnit)
+   * @see #getWriteRpcTimeout(TimeUnit)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15866">HBASE-15866</a>
    */
   @Deprecated
   default int getRpcTimeout() {
@@ -791,7 +794,11 @@ default int getRpcTimeout() {
    *
    * @param rpcTimeout the timeout of each rpc request in millisecond.
    *
-   * @deprecated Use setReadRpcTimeout or setWriteRpcTimeout instead
+   * @deprecated since 1.4.0 and will be removed in 3.0.0. Use {@link #setReadRpcTimeout(int)} or
+   *  {@link #setWriteRpcTimeout(int)} instead.
+   * @see #setReadRpcTimeout(int)
+   * @see #setReadRpcTimeout(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15866">HBASE-15866</a>
    */
   @Deprecated
   default void setRpcTimeout(int rpcTimeout) {
@@ -825,7 +832,10 @@ default int getReadRpcTimeout() {
    * until retries exhausted or operation timeout reached.
    *
    * @param readRpcTimeout the timeout for read rpc request in milliseconds
-   * @deprecated since 2.0.0, use {@link TableBuilder#setReadRpcTimeout} instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *  {@link TableBuilder#setReadRpcTimeout(int)} instead.
+   * @see TableBuilder#setReadRpcTimeout(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17491">HBASE-17491</a>
    */
   @Deprecated
   default void setReadRpcTimeout(int readRpcTimeout) {
@@ -858,7 +868,10 @@ default int getWriteRpcTimeout() {
    * until retries exhausted or operation timeout reached.
    *
    * @param writeRpcTimeout the timeout for write rpc request in milliseconds
-   * @deprecated since 2.0.0, use {@link TableBuilder#setWriteRpcTimeout} instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *  {@link TableBuilder#setWriteRpcTimeout(int)} instead.
+   * @see TableBuilder#setWriteRpcTimeout(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17491">HBASE-17491</a>
    */
   @Deprecated
   default void setWriteRpcTimeout(int writeRpcTimeout) {
@@ -893,7 +906,10 @@ default int getOperationTimeout() {
    * total time being blocking reach the operation timeout before retries exhausted, it will break
    * early and throw SocketTimeoutException.
    * @param operationTimeout the total timeout of each operation in millisecond.
-   * @deprecated since 2.0.0, use {@link TableBuilder#setOperationTimeout} instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *  {@link TableBuilder#setOperationTimeout(int)} instead.
+   * @see TableBuilder#setOperationTimeout(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-19029">HBASE-19029</a>
    */
   @Deprecated
   default void setOperationTimeout(int operationTimeout) {

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
@@ -176,6 +176,10 @@ public interface TableDescriptor {
    */
   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();