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