HBASE-3841 HTable and HTableInterface docs are inconsistent with one another

git-svn-id: https://svn.apache.org/repos/asf/hbase/trunk@1127678 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -229,6 +229,8 @@ Release 0.91.0 - Unreleased
    HBASE-2938  HBASE-2938 Add Thread-Local Behavior To HTable Pool
                (Karthick Sankarachary)
    HBASE-3811  Allow adding attributes to Scan (Alex Baranau)
+   HBASE-3841  HTable and HTableInterface docs are inconsistent with
+               one another (Harsh J Chouraria)
 
   TASKS
    HBASE-3559  Move report of split to master OFF the heartbeat channel

src/main/java/org/apache/hadoop/hbase/client/HTable.java

@@ -209,6 +209,10 @@ public class HTable implements HTableInterface, Closeable {
     this.closed = false;
   }
 
+  /**
+   * {@inheritDoc}
+   */
+  @Override
   public Configuration getConfiguration() {
     return configuration;
   }
@@ -290,6 +294,9 @@ public class HTable implements HTableInterface, Closeable {
     return connection.getRegionLocation(tableName, row, false);
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public byte [] getTableName() {
     return this.tableName;
@@ -329,6 +336,9 @@ public class HTable implements HTableInterface, Closeable {
     this.scannerCaching = scannerCaching;
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public HTableDescriptor getTableDescriptor() throws IOException {
     return new UnmodifyableHTableDescriptor(
@@ -532,6 +542,9 @@ public class HTable implements HTableInterface, Closeable {
     return allRegions;
   }
 
+  /**
+   * {@inheritDoc}
+   */
    @Override
    public Result getRowOrBefore(final byte[] row, final byte[] family)
    throws IOException {
@@ -544,6 +557,9 @@ public class HTable implements HTableInterface, Closeable {
      });
    }
 
+   /**
+    * {@inheritDoc}
+    */
   @Override
   public ResultScanner getScanner(final Scan scan) throws IOException {
     ClientScanner s = new ClientScanner(scan);
@@ -551,6 +567,9 @@ public class HTable implements HTableInterface, Closeable {
     return s;
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public ResultScanner getScanner(byte [] family) throws IOException {
     Scan scan = new Scan();
@@ -558,6 +577,9 @@ public class HTable implements HTableInterface, Closeable {
     return getScanner(scan);
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public ResultScanner getScanner(byte [] family, byte [] qualifier)
   throws IOException {
@@ -566,6 +588,10 @@ public class HTable implements HTableInterface, Closeable {
     return getScanner(scan);
   }
 
+  /**
+   * {@inheritDoc}
+   */
+  @Override
   public Result get(final Get get) throws IOException {
     return connection.getRegionServerWithRetries(
         new ServerCallable<Result>(connection, tableName, get.getRow()) {
@@ -576,6 +602,10 @@ public class HTable implements HTableInterface, Closeable {
     );
   }
 
+  /**
+   * {@inheritDoc}
+   */
+  @Override
   public Result[] get(List<Get> gets) throws IOException {
     try {
       Object [] r1 = batch((List)gets);
@@ -595,17 +625,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Method that does a batch call on Deletes, Gets and Puts.  The ordering of
+   * {@inheritDoc}
-   * execution of the actions is not defined. Meaning if you do a Put and a
-   * Get in the same {@link #batch} call, you will not necessarily be
-   * guaranteed that the Get returns what the Put had put.
-   *
-   * @param actions list of Get, Put, Delete objects
-   * @param results Empty Result[], same size as actions. Provides access to
-   * partial results, in case an exception is thrown. If there are any failures,
-   * there will be a null or Throwable will be in the results array, AND an
-   * exception will be thrown.
-   * @throws IOException
    */
   @Override
   public synchronized void batch(final List<Row> actions, final Object[] results)
@@ -614,12 +634,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Method that does a batch call on Deletes, Gets and Puts.
+   * {@inheritDoc}
-   *
-   * @param actions list of Get, Put, Delete objects
-   * @return the results from the actions. A null in the return array means that
-   * the call for that action failed, even after retries
-   * @throws IOException
    */
   @Override
   public synchronized Object[] batch(final List<Row> actions) throws InterruptedException, IOException {
@@ -629,11 +644,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Deletes the specified cells/row.
+   * {@inheritDoc}
-   *
-   * @param delete The object that specifies what to delete.
-   * @throws IOException if a remote or network exception occurs.
-   * @since 0.20.0
    */
   @Override
   public void delete(final Delete delete)
@@ -649,14 +660,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Deletes the specified cells/rows in bulk.
+   * {@inheritDoc}
-   * @param deletes List of things to delete. As a side effect, it will be modified:
-   * successful {@link Delete}s are removed. The ordering of the list will not change.
-   * @throws IOException if a remote or network exception occurs. In that case
-   * the {@code deletes} argument will contain the {@link Delete} instances
-   * that have not be successfully applied.
-   * @since 0.20.1
-   * @see #batch(java.util.List, Object[])
    */
   @Override
   public void delete(final List<Delete> deletes)
@@ -679,11 +683,17 @@ public class HTable implements HTableInterface, Closeable {
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void put(final Put put) throws IOException {
     doPut(Arrays.asList(put));
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void put(final List<Put> puts) throws IOException {
     doPut(puts);
@@ -700,6 +710,9 @@ public class HTable implements HTableInterface, Closeable {
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public Result increment(final Increment increment) throws IOException {
     if (!increment.hasFamilies()) {
@@ -716,6 +729,9 @@ public class HTable implements HTableInterface, Closeable {
     );
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public long incrementColumnValue(final byte [] row, final byte [] family,
       final byte [] qualifier, final long amount)
@@ -723,6 +739,9 @@ public class HTable implements HTableInterface, Closeable {
     return incrementColumnValue(row, family, qualifier, amount, true);
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public long incrementColumnValue(final byte [] row, final byte [] family,
       final byte [] qualifier, final long amount, final boolean writeToWAL)
@@ -749,17 +768,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Atomically checks if a row/family/qualifier value match the expectedValue.
+   * {@inheritDoc}
-   * If it does, it adds the put.  If value == null, checks for non-existence
-   * of the value.
-   *
-   * @param row to check
-   * @param family column family
-   * @param qualifier column qualifier
-   * @param value the expected value
-   * @param put put to execute if value matches.
-   * @throws IOException
-   * @return true if the new put was execute, false otherwise
    */
   @Override
   public boolean checkAndPut(final byte [] row,
@@ -776,18 +785,9 @@ public class HTable implements HTableInterface, Closeable {
     );
   }
 
+
   /**
-   * Atomically checks if a row/family/qualifier value match the expectedValue.
+   * {@inheritDoc}
-   * If it does, it adds the delete.  If value == null, checks for non-existence
-   * of the value.
-   *
-   * @param row to check
-   * @param family column family
-   * @param qualifier column qualifier
-   * @param value the expected value
-   * @param delete delete to execute if value matches.
-   * @throws IOException
-   * @return true if the new delete was executed, false otherwise
    */
   @Override
   public boolean checkAndDelete(final byte [] row,
@@ -807,15 +807,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Test for the existence of columns in the table, as specified in the Get.<p>
+   * {@inheritDoc}
-   *
-   * This will return true if the Get matches one or more keys, false if not.<p>
-   *
-   * This is a server-side call so it prevents any data from being transfered
-   * to the client.
-   * @param get param to check for
-   * @return true if the specified Get matches one or more keys, false if not
-   * @throws IOException
    */
   @Override
   public boolean exists(final Get get) throws IOException {
@@ -830,12 +822,7 @@ public class HTable implements HTableInterface, Closeable {
   }
 
   /**
-   * Executes all the buffered {@link Put} operations.
+   * {@inheritDoc}
-   * <p>
-   * This method gets called once automatically for every {@link Put} or batch
-   * of {@link Put}s (when {@link #batch(List)} is used) when
-   * {@link #isAutoFlush()} is {@code true}.
-   * @throws IOException if a remote or network exception occurs.
    */
   @Override
   public void flushCommits() throws IOException {
@@ -850,6 +837,9 @@ public class HTable implements HTableInterface, Closeable {
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void close() throws IOException {
     if (this.closed) {
@@ -879,6 +869,9 @@ public class HTable implements HTableInterface, Closeable {
     }
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public RowLock lockRow(final byte [] row)
   throws IOException {
@@ -893,6 +886,9 @@ public class HTable implements HTableInterface, Closeable {
     );
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public void unlockRow(final RowLock rl)
   throws IOException {
@@ -907,6 +903,9 @@ public class HTable implements HTableInterface, Closeable {
     );
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public boolean isAutoFlush() {
     return autoFlush;
@@ -1397,6 +1396,9 @@ public class HTable implements HTableInterface, Closeable {
     this.connection.clearRegionCache();
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public <T extends CoprocessorProtocol> T coprocessorProxy(
       Class<T> protocol, byte[] row) {
@@ -1409,6 +1411,9 @@ public class HTable implements HTableInterface, Closeable {
             row));
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public <T extends CoprocessorProtocol, R> Map<byte[],R> coprocessorExec(
       Class<T> protocol, byte[] startKey, byte[] endKey,
@@ -1426,6 +1431,9 @@ public class HTable implements HTableInterface, Closeable {
     return results;
   }
 
+  /**
+   * {@inheritDoc}
+   */
   @Override
   public <T extends CoprocessorProtocol, R> void coprocessorExec(
       Class<T> protocol, byte[] startKey, byte[] endKey,

src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java

@@ -75,7 +75,10 @@ public interface HTableInterface {
   boolean exists(Get get) throws IOException;
 
   /**
-   * Method that does a batch call on Deletes, Gets and Puts.
+   * Method that does a batch call on Deletes, Gets and Puts. The ordering of
+   * execution of the actions is not defined. Meaning if you do a Put and a
+   * Get in the same {@link #batch} call, you will not necessarily be
+   * guaranteed that the Get returns what the Put had put.
    *
    * @param actions list of Get, Put, Delete objects
    * @param results Empty Object[], same size as actions. Provides access to partial
@@ -87,8 +90,8 @@ public interface HTableInterface {
   void batch(final List<Row> actions, final Object[] results) throws IOException, InterruptedException;
 
   /**
-   * Method that does a batch call on Deletes, Gets and Puts.
+   * Same as {@link #batch(List, Object[])}, but returns an array of
-   *
+   * results instead of using a results parameter reference.
    *
    * @param actions list of Get, Put, Delete objects
    * @return the results from the actions. A null in the return array means that