001/**
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019package org.apache.hadoop.hbase.client;
020
021import java.io.Closeable;
022import java.io.IOException;
023import java.util.List;
024import java.util.Map;
025import java.util.concurrent.TimeUnit;
026
027import org.apache.hadoop.conf.Configuration;
028import org.apache.hadoop.hbase.CompareOperator;
029import org.apache.hadoop.hbase.HTableDescriptor;
030import org.apache.hadoop.hbase.TableName;
031import org.apache.hadoop.hbase.io.TimeRange;
032import org.apache.yetus.audience.InterfaceAudience;
033import org.apache.hadoop.hbase.client.coprocessor.Batch;
034import org.apache.hadoop.hbase.filter.CompareFilter;
035import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel;
036
037import com.google.protobuf.Descriptors;
038import com.google.protobuf.Message;
039import com.google.protobuf.Service;
040import com.google.protobuf.ServiceException;
041
042/**
043 * Used to communicate with a single HBase table.
044 * Obtain an instance from a {@link Connection} and call {@link #close()} afterwards.
045 *
046 * <p>Table can be used to get, put, delete or scan data from a table.
047 * @see ConnectionFactory
048 * @see Connection
049 * @see Admin
050 * @see RegionLocator
051 * @since 0.99.0
052 */
053@InterfaceAudience.Public
054public interface Table extends Closeable {
055  /**
056   * Gets the fully qualified table name instance of this table.
057   */
058  TableName getName();
059
060  /**
061   * Returns the {@link org.apache.hadoop.conf.Configuration} object used by this instance.
062   * <p>
063   * The reference returned is not a copy, so any change made to it will
064   * affect this instance.
065   */
066  Configuration getConfiguration();
067
068  /**
069   * Gets the {@link org.apache.hadoop.hbase.HTableDescriptor table descriptor} for this table.
070   * @throws java.io.IOException if a remote or network exception occurs.
071   * @deprecated since 2.0 version and will be removed in 3.0 version.
072   *             use {@link #getDescriptor()}
073   */
074  @Deprecated
075  HTableDescriptor getTableDescriptor() throws IOException;
076
077  /**
078   * Gets the {@link org.apache.hadoop.hbase.client.TableDescriptor table descriptor} for this table.
079   * @throws java.io.IOException if a remote or network exception occurs.
080   */
081  TableDescriptor getDescriptor() throws IOException;
082
083  /**
084   * Test for the existence of columns in the table, as specified by the Get.
085   * <p>
086   *
087   * This will return true if the Get matches one or more keys, false if not.
088   * <p>
089   *
090   * This is a server-side call so it prevents any data from being transfered to
091   * the client.
092   *
093   * @param get the Get
094   * @return true if the specified Get matches one or more keys, false if not
095   * @throws IOException e
096   */
097  boolean exists(Get get) throws IOException;
098
099  /**
100   * Test for the existence of columns in the table, as specified by the Gets.
101   * <p>
102   *
103   * This will return an array of booleans. Each value will be true if the related Get matches
104   * one or more keys, false if not.
105   * <p>
106   *
107   * This is a server-side call so it prevents any data from being transferred to
108   * the client.
109   *
110   * @param gets the Gets
111   * @return Array of boolean.  True if the specified Get matches one or more keys, false if not.
112   * @throws IOException e
113   */
114  boolean[] exists(List<Get> gets) throws IOException;
115
116  /**
117   * Test for the existence of columns in the table, as specified by the Gets.
118   * This will return an array of booleans. Each value will be true if the related Get matches
119   * one or more keys, false if not.
120   * This is a server-side call so it prevents any data from being transferred to
121   * the client.
122   *
123   * @param gets the Gets
124   * @return Array of boolean.  True if the specified Get matches one or more keys, false if not.
125   * @throws IOException e
126   * @deprecated since 2.0 version and will be removed in 3.0 version.
127   *             use {@link #exists(List)}
128   */
129  @Deprecated
130  default boolean[] existsAll(List<Get> gets) throws IOException {
131    return exists(gets);
132  }
133
134  /**
135   * Method that does a batch call on Deletes, Gets, Puts, Increments, Appends, RowMutations.
136   * The ordering of execution of the actions is not defined. Meaning if you do a Put and a
137   * Get in the same {@link #batch} call, you will not necessarily be
138   * guaranteed that the Get returns what the Put had put.
139   *
140   * @param actions list of Get, Put, Delete, Increment, Append, RowMutations.
141   * @param results Empty Object[], same size as actions. Provides access to partial
142   *                results, in case an exception is thrown. A null in the result array means that
143   *                the call for that action failed, even after retries. The order of the objects
144   *                in the results array corresponds to the order of actions in the request list.
145   * @throws IOException
146   * @since 0.90.0
147   */
148  void batch(final List<? extends Row> actions, final Object[] results) throws IOException,
149    InterruptedException;
150
151  /**
152   * Same as {@link #batch(List, Object[])}, but with a callback.
153   * @since 0.96.0
154   */
155  <R> void batchCallback(
156    final List<? extends Row> actions, final Object[] results, final Batch.Callback<R> callback
157  ) throws IOException, InterruptedException;
158
159  /**
160   * Extracts certain cells from a given row.
161   * @param get The object that specifies what data to fetch and from which row.
162   * @return The data coming from the specified row, if it exists.  If the row
163   * specified doesn't exist, the {@link Result} instance returned won't
164   * contain any {@link org.apache.hadoop.hbase.KeyValue}, as indicated by {@link Result#isEmpty()}.
165   * @throws IOException if a remote or network exception occurs.
166   * @since 0.20.0
167   */
168  Result get(Get get) throws IOException;
169
170  /**
171   * Extracts specified cells from the given rows, as a batch.
172   *
173   * @param gets The objects that specify what data to fetch and from which rows.
174   * @return The data coming from the specified rows, if it exists.  If the row specified doesn't
175   * exist, the {@link Result} instance returned won't contain any {@link
176   * org.apache.hadoop.hbase.Cell}s, as indicated by {@link Result#isEmpty()}. If there are any
177   * failures even after retries, there will be a <code>null</code> in the results' array for those
178   * Gets, AND an exception will be thrown. The ordering of the Result array corresponds to the order
179   * of the list of passed in Gets.
180   * @throws IOException if a remote or network exception occurs.
181   * @since 0.90.0
182   * @apiNote {@link #put(List)} runs pre-flight validations on the input list on client.
183   * Currently {@link #get(List)} doesn't run any validations on the client-side, currently there
184   * is no need, but this may change in the future. An
185   * {@link IllegalArgumentException} will be thrown in this case.
186   */
187  Result[] get(List<Get> gets) throws IOException;
188
189  /**
190   * Returns a scanner on the current table as specified by the {@link Scan}
191   * object.
192   * Note that the passed {@link Scan}'s start row and caching properties
193   * maybe changed.
194   *
195   * @param scan A configured {@link Scan} object.
196   * @return A scanner.
197   * @throws IOException if a remote or network exception occurs.
198   * @since 0.20.0
199   */
200  ResultScanner getScanner(Scan scan) throws IOException;
201
202  /**
203   * Gets a scanner on the current table for the given family.
204   *
205   * @param family The column family to scan.
206   * @return A scanner.
207   * @throws IOException if a remote or network exception occurs.
208   * @since 0.20.0
209   */
210  ResultScanner getScanner(byte[] family) throws IOException;
211
212  /**
213   * Gets a scanner on the current table for the given family and qualifier.
214   *
215   * @param family The column family to scan.
216   * @param qualifier The column qualifier to scan.
217   * @return A scanner.
218   * @throws IOException if a remote or network exception occurs.
219   * @since 0.20.0
220   */
221  ResultScanner getScanner(byte[] family, byte[] qualifier) throws IOException;
222
223
224  /**
225   * Puts some data in the table.
226   *
227   * @param put The data to put.
228   * @throws IOException if a remote or network exception occurs.
229   * @since 0.20.0
230   */
231  void put(Put put) throws IOException;
232
233  /**
234   * Batch puts the specified data into the table.
235   * <p>
236   * This can be used for group commit, or for submitting user defined batches. Before sending
237   * a batch of mutations to the server, the client runs a few validations on the input list. If an
238   * error is found, for example, a mutation was supplied but was missing it's column an
239   * {@link IllegalArgumentException} will be thrown and no mutations will be applied. If there
240   * are any failures even after retries, a {@link RetriesExhaustedWithDetailsException} will be
241   * thrown. RetriesExhaustedWithDetailsException contains lists of failed mutations and
242   * corresponding remote exceptions. The ordering of mutations and exceptions in the
243   * encapsulating exception corresponds to the order of the input list of Put requests.
244   *
245   * @param puts The list of mutations to apply.
246   * @throws IOException if a remote or network exception occurs.
247   * @since 0.20.0
248   */
249  void put(List<Put> puts) throws IOException;
250
251  /**
252   * Atomically checks if a row/family/qualifier value matches the expected
253   * value. If it does, it adds the put.  If the passed value is null, the check
254   * is for the lack of column (ie: non-existance)
255   *
256   * @param row to check
257   * @param family column family to check
258   * @param qualifier column qualifier to check
259   * @param value the expected value
260   * @param put data to put if check succeeds
261   * @throws IOException e
262   * @return true if the new put was executed, false otherwise
263   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
264   */
265  @Deprecated
266  boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
267      byte[] value, Put put) throws IOException;
268
269  /**
270   * Atomically checks if a row/family/qualifier value matches the expected
271   * value. If it does, it adds the put.  If the passed value is null, the check
272   * is for the lack of column (ie: non-existence)
273   *
274   * The expected value argument of this call is on the left and the current
275   * value of the cell is on the right side of the comparison operator.
276   *
277   * Ie. eg. GREATER operator means expected value > existing <=> add the put.
278   *
279   * @param row to check
280   * @param family column family to check
281   * @param qualifier column qualifier to check
282   * @param compareOp comparison operator to use
283   * @param value the expected value
284   * @param put data to put if check succeeds
285   * @throws IOException e
286   * @return true if the new put was executed, false otherwise
287   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
288   */
289  @Deprecated
290  boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
291      CompareFilter.CompareOp compareOp, byte[] value, Put put) throws IOException;
292
293  /**
294   * Atomically checks if a row/family/qualifier value matches the expected
295   * value. If it does, it adds the put.  If the passed value is null, the check
296   * is for the lack of column (ie: non-existence)
297   *
298   * The expected value argument of this call is on the left and the current
299   * value of the cell is on the right side of the comparison operator.
300   *
301   * Ie. eg. GREATER operator means expected value > existing <=> add the put.
302   *
303   * @param row to check
304   * @param family column family to check
305   * @param qualifier column qualifier to check
306   * @param op comparison operator to use
307   * @param value the expected value
308   * @param put data to put if check succeeds
309   * @throws IOException e
310   * @return true if the new put was executed, false otherwise
311   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
312   */
313  @Deprecated
314  boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
315      byte[] value, Put put) throws IOException;
316
317  /**
318   * Deletes the specified cells/row.
319   *
320   * @param delete The object that specifies what to delete.
321   * @throws IOException if a remote or network exception occurs.
322   * @since 0.20.0
323   */
324  void delete(Delete delete) throws IOException;
325
326  /**
327   * Batch Deletes the specified cells/rows from the table.
328   * <p>
329   * If a specified row does not exist, {@link Delete} will report as though sucessful
330   * delete; no exception will be thrown. If there are any failures even after retries,
331   * a * {@link RetriesExhaustedWithDetailsException} will be thrown.
332   * RetriesExhaustedWithDetailsException contains lists of failed {@link Delete}s and
333   * corresponding remote exceptions.
334   *
335   * @param deletes List of things to delete. The input list gets modified by this
336   * method. All successfully applied {@link Delete}s in the list are removed (in particular it
337   * gets re-ordered, so the order in which the elements are inserted in the list gives no
338   * guarantee as to the order in which the {@link Delete}s are executed).
339   * @throws IOException if a remote or network exception occurs. In that case
340   * the {@code deletes} argument will contain the {@link Delete} instances
341   * that have not be successfully applied.
342   * @since 0.20.1
343   * @apiNote In 3.0.0 version, the input list {@code deletes} will no longer be modified. Also,
344   * {@link #put(List)} runs pre-flight validations on the input list on client. Currently
345   * {@link #delete(List)} doesn't run validations on the client, there is no need currently,
346   * but this may change in the future. An * {@link IllegalArgumentException} will be thrown
347   * in this case.
348   */
349  void delete(List<Delete> deletes) throws IOException;
350
351  /**
352   * Atomically checks if a row/family/qualifier value matches the expected
353   * value. If it does, it adds the delete.  If the passed value is null, the
354   * check is for the lack of column (ie: non-existance)
355   *
356   * @param row to check
357   * @param family column family to check
358   * @param qualifier column qualifier to check
359   * @param value the expected value
360   * @param delete data to delete if check succeeds
361   * @throws IOException e
362   * @return true if the new delete was executed, false otherwise
363   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
364   */
365  @Deprecated
366  boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
367    byte[] value, Delete delete) throws IOException;
368
369  /**
370   * Atomically checks if a row/family/qualifier value matches the expected
371   * value. If it does, it adds the delete.  If the passed value is null, the
372   * check is for the lack of column (ie: non-existence)
373   *
374   * The expected value argument of this call is on the left and the current
375   * value of the cell is on the right side of the comparison operator.
376   *
377   * Ie. eg. GREATER operator means expected value > existing <=> add the delete.
378   *
379   * @param row to check
380   * @param family column family to check
381   * @param qualifier column qualifier to check
382   * @param compareOp comparison operator to use
383   * @param value the expected value
384   * @param delete data to delete if check succeeds
385   * @throws IOException e
386   * @return true if the new delete was executed, false otherwise
387   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
388   */
389  @Deprecated
390  boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
391    CompareFilter.CompareOp compareOp, byte[] value, Delete delete) throws IOException;
392
393  /**
394   * Atomically checks if a row/family/qualifier value matches the expected
395   * value. If it does, it adds the delete.  If the passed value is null, the
396   * check is for the lack of column (ie: non-existence)
397   *
398   * The expected value argument of this call is on the left and the current
399   * value of the cell is on the right side of the comparison operator.
400   *
401   * Ie. eg. GREATER operator means expected value > existing <=> add the delete.
402   *
403   * @param row to check
404   * @param family column family to check
405   * @param qualifier column qualifier to check
406   * @param op comparison operator to use
407   * @param value the expected value
408   * @param delete data to delete if check succeeds
409   * @throws IOException e
410   * @return true if the new delete was executed, false otherwise
411   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
412   */
413  @Deprecated
414  boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
415                         CompareOperator op, byte[] value, Delete delete) throws IOException;
416
417  /**
418   * Atomically checks if a row/family/qualifier value matches the expected value. If it does, it
419   * adds the Put/Delete/RowMutations.
420   * <p>
421   * Use the returned {@link CheckAndMutateBuilder} to construct your request and then execute it.
422   * This is a fluent style API, the code is like:
423   *
424   * <pre>
425   * <code>
426   * table.checkAndMutate(row, family).qualifier(qualifier).ifNotExists().thenPut(put);
427   * </code>
428   * </pre>
429   */
430  CheckAndMutateBuilder checkAndMutate(byte[] row, byte[] family);
431  /**
432   * A helper class for sending checkAndMutate request.
433   */
434  interface CheckAndMutateBuilder {
435
436    /**
437     * @param qualifier column qualifier to check.
438     */
439    CheckAndMutateBuilder qualifier(byte[] qualifier);
440
441    /**
442     * @param timeRange timeRange to check
443     */
444    CheckAndMutateBuilder timeRange(TimeRange timeRange);
445
446    /**
447     * Check for lack of column.
448     */
449    CheckAndMutateBuilder ifNotExists();
450
451    /**
452     * Check for equality.
453     * @param value the expected value
454     */
455    default CheckAndMutateBuilder ifEquals(byte[] value) {
456      return ifMatches(CompareOperator.EQUAL, value);
457    }
458
459    /**
460     * @param compareOp comparison operator to use
461     * @param value the expected value
462     */
463    CheckAndMutateBuilder ifMatches(CompareOperator compareOp, byte[] value);
464
465    /**
466     * @param put data to put if check succeeds
467     * @return {@code true} if the new put was executed, {@code false} otherwise.
468     */
469    boolean thenPut(Put put) throws IOException;
470
471    /**
472     * @param delete data to delete if check succeeds
473     * @return {@code true} if the new delete was executed, {@code false} otherwise.
474     */
475    boolean thenDelete(Delete delete) throws IOException;
476    /**
477     * @param mutation mutations to perform if check succeeds
478     * @return true if the new mutation was executed, false otherwise.
479     */
480    boolean thenMutate(RowMutations mutation) throws IOException;
481
482  }
483
484  /**
485   * Performs multiple mutations atomically on a single row. Currently
486   * {@link Put} and {@link Delete} are supported.
487   *
488   * @param rm object that specifies the set of mutations to perform atomically
489   * @throws IOException
490   */
491  void mutateRow(final RowMutations rm) throws IOException;
492
493  /**
494   * Appends values to one or more columns within a single row.
495   * <p>
496   * This operation guaranteed atomicity to readers. Appends are done
497   * under a single row lock, so write operations to a row are synchronized, and
498   * readers are guaranteed to see this operation fully completed.
499   *
500   * @param append object that specifies the columns and amounts to be used
501   *                  for the increment operations
502   * @throws IOException e
503   * @return values of columns after the append operation (maybe null)
504   */
505  Result append(final Append append) throws IOException;
506
507  /**
508   * Increments one or more columns within a single row.
509   * <p>
510   * This operation ensures atomicity to readers. Increments are done
511   * under a single row lock, so write operations to a row are synchronized, and
512   * readers are guaranteed to see this operation fully completed.
513   *
514   * @param increment object that specifies the columns and amounts to be used
515   *                  for the increment operations
516   * @throws IOException e
517   * @return values of columns after the increment
518   */
519  Result increment(final Increment increment) throws IOException;
520
521  /**
522   * See {@link #incrementColumnValue(byte[], byte[], byte[], long, Durability)}
523   * <p>
524   * The {@link Durability} is defaulted to {@link Durability#SYNC_WAL}.
525   * @param row The row that contains the cell to increment.
526   * @param family The column family of the cell to increment.
527   * @param qualifier The column qualifier of the cell to increment.
528   * @param amount The amount to increment the cell with (or decrement, if the
529   * amount is negative).
530   * @return The new value, post increment.
531   * @throws IOException if a remote or network exception occurs.
532   */
533  long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
534    long amount) throws IOException;
535
536  /**
537   * Atomically increments a column value. If the column value already exists
538   * and is not a big-endian long, this could throw an exception. If the column
539   * value does not yet exist it is initialized to <code>amount</code> and
540   * written to the specified column.
541   *
542   * <p>Setting durability to {@link Durability#SKIP_WAL} means that in a fail
543   * scenario you will lose any increments that have not been flushed.
544   * @param row The row that contains the cell to increment.
545   * @param family The column family of the cell to increment.
546   * @param qualifier The column qualifier of the cell to increment.
547   * @param amount The amount to increment the cell with (or decrement, if the
548   * amount is negative).
549   * @param durability The persistence guarantee for this increment.
550   * @return The new value, post increment.
551   * @throws IOException if a remote or network exception occurs.
552   */
553  long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
554    long amount, Durability durability) throws IOException;
555
556  /**
557   * Releases any resources held or pending changes in internal buffers.
558   *
559   * @throws IOException if a remote or network exception occurs.
560   */
561  @Override
562  void close() throws IOException;
563
564  /**
565   * Creates and returns a {@link com.google.protobuf.RpcChannel} instance connected to the
566   * table region containing the specified row.  The row given does not actually have
567   * to exist.  Whichever region would contain the row based on start and end keys will
568   * be used.  Note that the {@code row} parameter is also not passed to the
569   * coprocessor handler registered for this protocol, unless the {@code row}
570   * is separately passed as an argument in the service request.  The parameter
571   * here is only used to locate the region used to handle the call.
572   *
573   * <p>
574   * The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access a published
575   * coprocessor {@link com.google.protobuf.Service} using standard protobuf service invocations:
576   * </p>
577   *
578   * <div style="background-color: #cccccc; padding: 2px">
579   * <blockquote><pre>
580   * CoprocessorRpcChannel channel = myTable.coprocessorService(rowkey);
581   * MyService.BlockingInterface service = MyService.newBlockingStub(channel);
582   * MyCallRequest request = MyCallRequest.newBuilder()
583   *     ...
584   *     .build();
585   * MyCallResponse response = service.myCall(null, request);
586   * </pre></blockquote></div>
587   *
588   * @param row The row key used to identify the remote region location
589   * @return A CoprocessorRpcChannel instance
590   */
591  CoprocessorRpcChannel coprocessorService(byte[] row);
592
593  /**
594   * Creates an instance of the given {@link com.google.protobuf.Service} subclass for each table
595   * region spanning the range from the {@code startKey} row to {@code endKey} row (inclusive), and
596   * invokes the passed {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call} method
597   * with each {@link com.google.protobuf.Service} instance.
598   *
599   * @param service the protocol buffer {@code Service} implementation to call
600   * @param startKey start region selection with region containing this row.  If {@code null}, the
601   * selection will start with the first table region.
602   * @param endKey select regions up to and including the region containing this row. If {@code
603   * null}, selection will continue through the last table region.
604   * @param callable this instance's {@link org.apache.hadoop.hbase.client.coprocessor.Batch
605   * .Call#call}
606   * method will be invoked once per table region, using the {@link com.google.protobuf.Service}
607   * instance connected to that region.
608   * @param <T> the {@link com.google.protobuf.Service} subclass to connect to
609   * @param <R> Return type for the {@code callable} parameter's {@link
610   * org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call} method
611   * @return a map of result values keyed by region name
612   */
613  <T extends Service, R> Map<byte[],R> coprocessorService(final Class<T> service,
614    byte[] startKey, byte[] endKey, final Batch.Call<T,R> callable)
615    throws ServiceException, Throwable;
616
617  /**
618   * Creates an instance of the given {@link com.google.protobuf.Service} subclass for each table
619   * region spanning the range from the {@code startKey} row to {@code endKey} row (inclusive), and
620   * invokes the passed {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call} method
621   * with each {@link Service} instance.
622   *
623   * <p> The given {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[],
624   * byte[], Object)} method will be called with the return value from each region's {@link
625   * org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call} invocation. </p>
626   *
627   * @param service the protocol buffer {@code Service} implementation to call
628   * @param startKey start region selection with region containing this row.  If {@code null}, the
629   * selection will start with the first table region.
630   * @param endKey select regions up to and including the region containing this row. If {@code
631   * null}, selection will continue through the last table region.
632   * @param callable this instance's {@link org.apache.hadoop.hbase.client.coprocessor.Batch
633   * .Call#call}
634   * method will be invoked once per table region, using the {@link Service} instance connected to
635   * that region.
636   * @param callback
637   * @param <T> the {@link Service} subclass to connect to
638   * @param <R> Return type for the {@code callable} parameter's {@link
639   * org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call} method
640   */
641  <T extends Service, R> void coprocessorService(final Class<T> service,
642    byte[] startKey, byte[] endKey, final Batch.Call<T,R> callable,
643    final Batch.Callback<R> callback) throws ServiceException, Throwable;
644
645  /**
646   * Creates an instance of the given {@link com.google.protobuf.Service} subclass for each table
647   * region spanning the range from the {@code startKey} row to {@code endKey} row (inclusive), all
648   * the invocations to the same region server will be batched into one call. The coprocessor
649   * service is invoked according to the service instance, method name and parameters.
650   *
651   * @param methodDescriptor
652   *          the descriptor for the protobuf service method to call.
653   * @param request
654   *          the method call parameters
655   * @param startKey
656   *          start region selection with region containing this row. If {@code null}, the
657   *          selection will start with the first table region.
658   * @param endKey
659   *          select regions up to and including the region containing this row. If {@code null},
660   *          selection will continue through the last table region.
661   * @param responsePrototype
662   *          the proto type of the response of the method in Service.
663   * @param <R>
664   *          the response type for the coprocessor Service method
665   * @throws ServiceException
666   * @throws Throwable
667   * @return a map of result values keyed by region name
668   */
669  <R extends Message> Map<byte[], R> batchCoprocessorService(
670    Descriptors.MethodDescriptor methodDescriptor, Message request,
671    byte[] startKey, byte[] endKey, R responsePrototype) throws ServiceException, Throwable;
672
673  /**
674   * Creates an instance of the given {@link com.google.protobuf.Service} subclass for each table
675   * region spanning the range from the {@code startKey} row to {@code endKey} row (inclusive), all
676   * the invocations to the same region server will be batched into one call. The coprocessor
677   * service is invoked according to the service instance, method name and parameters.
678   *
679   * <p>
680   * The given
681   * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[],byte[],Object)}
682   * method will be called with the return value from each region's invocation.
683   * </p>
684   *
685   * @param methodDescriptor
686   *          the descriptor for the protobuf service method to call.
687   * @param request
688   *          the method call parameters
689   * @param startKey
690   *          start region selection with region containing this row. If {@code null}, the
691   *          selection will start with the first table region.
692   * @param endKey
693   *          select regions up to and including the region containing this row. If {@code null},
694   *          selection will continue through the last table region.
695   * @param responsePrototype
696   *          the proto type of the response of the method in Service.
697   * @param callback
698   *          callback to invoke with the response for each region
699   * @param <R>
700   *          the response type for the coprocessor Service method
701   * @throws ServiceException
702   * @throws Throwable
703   */
704  <R extends Message> void batchCoprocessorService(Descriptors.MethodDescriptor methodDescriptor,
705    Message request, byte[] startKey, byte[] endKey, R responsePrototype,
706    Batch.Callback<R> callback) throws ServiceException, Throwable;
707
708  /**
709   * Atomically checks if a row/family/qualifier value matches the expected value.
710   * If it does, it performs the row mutations.  If the passed value is null, the check
711   * is for the lack of column (ie: non-existence)
712   *
713   * The expected value argument of this call is on the left and the current
714   * value of the cell is on the right side of the comparison operator.
715   *
716   * Ie. eg. GREATER operator means expected value > existing <=> perform row mutations.
717   *
718   * @param row to check
719   * @param family column family to check
720   * @param qualifier column qualifier to check
721   * @param compareOp the comparison operator
722   * @param value the expected value
723   * @param mutation  mutations to perform if check succeeds
724   * @throws IOException e
725   * @return true if the new put was executed, false otherwise
726   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
727   */
728  @Deprecated
729  boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier,
730      CompareFilter.CompareOp compareOp, byte[] value, RowMutations mutation) throws IOException;
731
732  /**
733   * Atomically checks if a row/family/qualifier value matches the expected value.
734   * If it does, it performs the row mutations.  If the passed value is null, the check
735   * is for the lack of column (ie: non-existence)
736   *
737   * The expected value argument of this call is on the left and the current
738   * value of the cell is on the right side of the comparison operator.
739   *
740   * Ie. eg. GREATER operator means expected value > existing <=> perform row mutations.
741   *
742   * @param row to check
743   * @param family column family to check
744   * @param qualifier column qualifier to check
745   * @param op the comparison operator
746   * @param value the expected value
747   * @param mutation  mutations to perform if check succeeds
748   * @throws IOException e
749   * @return true if the new put was executed, false otherwise
750   * @deprecated Since 2.0.0. Will be removed in 3.0.0. Use {@link #checkAndMutate(byte[], byte[])}
751   */
752  @Deprecated
753  boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
754                         byte[] value, RowMutations mutation) throws IOException;
755
756  /**
757   * Get timeout of each rpc request in this Table instance. It will be overridden by a more
758   * specific rpc timeout config such as readRpcTimeout or writeRpcTimeout.
759   * @see #getReadRpcTimeout(TimeUnit)
760   * @see #getWriteRpcTimeout(TimeUnit)
761   * @param unit the unit of time the timeout to be represented in
762   * @return rpc timeout in the specified time unit
763   */
764  long getRpcTimeout(TimeUnit unit);
765
766  /**
767   * Get timeout (millisecond) of each rpc request in this Table instance.
768   *
769   * @return Currently configured read timeout
770   * @deprecated use {@link #getReadRpcTimeout(TimeUnit)} or
771   *             {@link #getWriteRpcTimeout(TimeUnit)} instead
772   */
773  @Deprecated
774  int getRpcTimeout();
775
776  /**
777   * Set timeout (millisecond) of each rpc request in operations of this Table instance, will
778   * override the value of hbase.rpc.timeout in configuration.
779   * If a rpc request waiting too long, it will stop waiting and send a new request to retry until
780   * retries exhausted or operation timeout reached.
781   * <p>
782   * NOTE: This will set both the read and write timeout settings to the provided value.
783   *
784   * @param rpcTimeout the timeout of each rpc request in millisecond.
785   *
786   * @deprecated Use setReadRpcTimeout or setWriteRpcTimeout instead
787   */
788  @Deprecated
789  void setRpcTimeout(int rpcTimeout);
790
791  /**
792   * Get timeout of each rpc read request in this Table instance.
793   * @param unit the unit of time the timeout to be represented in
794   * @return read rpc timeout in the specified time unit
795   */
796  long getReadRpcTimeout(TimeUnit unit);
797
798  /**
799   * Get timeout (millisecond) of each rpc read request in this Table instance.
800   * @deprecated since 2.0 and will be removed in 3.0 version
801   *             use {@link #getReadRpcTimeout(TimeUnit)} instead
802   */
803  @Deprecated
804  int getReadRpcTimeout();
805
806  /**
807   * Set timeout (millisecond) of each rpc read request in operations of this Table instance, will
808   * override the value of hbase.rpc.read.timeout in configuration.
809   * If a rpc read request waiting too long, it will stop waiting and send a new request to retry
810   * until retries exhausted or operation timeout reached.
811   *
812   * @param readRpcTimeout the timeout for read rpc request in milliseconds
813   * @deprecated since 2.0.0, use {@link TableBuilder#setReadRpcTimeout} instead
814   */
815  @Deprecated
816  void setReadRpcTimeout(int readRpcTimeout);
817
818  /**
819   * Get timeout of each rpc write request in this Table instance.
820   * @param unit the unit of time the timeout to be represented in
821   * @return write rpc timeout in the specified time unit
822   */
823  long getWriteRpcTimeout(TimeUnit unit);
824
825  /**
826   * Get timeout (millisecond) of each rpc write request in this Table instance.
827   * @deprecated since 2.0 and will be removed in 3.0 version
828   *             use {@link #getWriteRpcTimeout(TimeUnit)} instead
829   */
830  @Deprecated
831  int getWriteRpcTimeout();
832
833  /**
834   * Set timeout (millisecond) of each rpc write request in operations of this Table instance, will
835   * override the value of hbase.rpc.write.timeout in configuration.
836   * If a rpc write request waiting too long, it will stop waiting and send a new request to retry
837   * until retries exhausted or operation timeout reached.
838   *
839   * @param writeRpcTimeout the timeout for write rpc request in milliseconds
840   * @deprecated since 2.0.0, use {@link TableBuilder#setWriteRpcTimeout} instead
841   */
842  @Deprecated
843  void setWriteRpcTimeout(int writeRpcTimeout);
844
845  /**
846   * Get timeout of each operation in Table instance.
847   * @param unit the unit of time the timeout to be represented in
848   * @return operation rpc timeout in the specified time unit
849   */
850  long getOperationTimeout(TimeUnit unit);
851
852  /**
853   * Get timeout (millisecond) of each operation for in Table instance.
854   * @deprecated since 2.0 and will be removed in 3.0 version
855   *             use {@link #getOperationTimeout(TimeUnit)} instead
856   */
857  @Deprecated
858  int getOperationTimeout();
859
860  /**
861   * Set timeout (millisecond) of each operation in this Table instance, will override the value
862   * of hbase.client.operation.timeout in configuration.
863   * Operation timeout is a top-level restriction that makes sure a blocking method will not be
864   * blocked more than this. In each operation, if rpc request fails because of timeout or
865   * other reason, it will retry until success or throw a RetriesExhaustedException. But if the
866   * total time being blocking reach the operation timeout before retries exhausted, it will break
867   * early and throw SocketTimeoutException.
868   * @param operationTimeout the total timeout of each operation in millisecond.
869   * @deprecated since 2.0.0, use {@link TableBuilder#setOperationTimeout} instead
870   */
871  @Deprecated
872  void setOperationTimeout(int operationTimeout);
873}