hbase-client/src/main/java/org/apache/hadoop/hbase/client/AdvancedScanResultConsumer.java

   1 /**
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 package org.apache.hadoop.hbase.client;
  19
  20 import java.util.Optional;
  21
  22 import org.apache.yetus.audience.InterfaceAudience;
  23
  24 /**
  25  * This is the low level API for asynchronous scan.
  26  * <p>
  27  * All results that match the given scan object will be passed to this class by calling
  28  * {@link #onNext(Result[], ScanController)}. {@link #onComplete()} means the scan is finished, and
  29  * {@link #onError(Throwable)} means we hit an unrecoverable error and the scan is terminated.
  30  * {@link #onHeartbeat(ScanController)} means the RS is still working but we can not get a valid
  31  * result to call {@link #onNext(Result[], ScanController)}. This is usually because the matched
  32  * results are too sparse, for example, a filter which almost filters out everything is specified.
  33  * <p>
  34  * Notice that, all the methods here will be called directly in the thread which we send request to
  35  * HBase service. So if you want the asynchronous scanner fetch data from HBase in background while
  36  * you process the returned data, you need to move the processing work to another thread to make the
  37  * {@link #onNext(Result[], ScanController)} call return immediately. And please do NOT do any time
  38  * consuming tasks in these methods unless you know what you are doing.
  39  * @since 2.0.0
  40  */
  41 @InterfaceAudience.Public
  42 public interface AdvancedScanResultConsumer extends ScanResultConsumerBase {
  43
  44   /**
  45    * Used to resume a scan.
  46    */
  47   @InterfaceAudience.Public
  48   interface ScanResumer {
  49
  50     /**
  51      * Resume the scan. You are free to call it multiple time but only the first call will take
  52      * effect.
  53      */
  54     void resume();
  55   }
  56
  57   /**
  58    * Used to suspend or stop a scan, or get a scan cursor if available.
  59    * <p>
  60    * Notice that, you should only call the {@link #suspend()} or {@link #terminate()} inside onNext
  61    * or onHeartbeat method. A IllegalStateException will be thrown if you call them at other places.
  62    * <p>
  63    * You can only call one of the {@link #suspend()} and {@link #terminate()} methods(of course you
  64    * are free to not call them both), and the methods are not reentrant. An IllegalStateException
  65    * will be thrown if you have already called one of the methods.
  66    */
  67   @InterfaceAudience.Public
  68   interface ScanController {
  69
  70     /**
  71      * Suspend the scan.
  72      * <p>
  73      * This means we will stop fetching data in background, i.e., will not call onNext any more
  74      * before you resume the scan.
  75      * @return A resumer used to resume the scan later.
  76      */
  77     ScanResumer suspend();
  78
  79     /**
  80      * Terminate the scan.
  81      * <p>
  82      * This is useful when you have got enough results and want to stop the scan in onNext method,
  83      * or you want to stop the scan in onHeartbeat method because it has spent too many time.
  84      */
  85     void terminate();
  86
  87     /**
  88      * Get the scan cursor if available.
  89      * @return The scan cursor.
  90      */
  91     Optional<Cursor> cursor();
  92   }
  93
  94   /**
  95    * Indicate that we have receive some data.
  96    * @param results the data fetched from HBase service.
  97    * @param controller used to suspend or terminate the scan. Notice that the {@code controller}
  98    *          instance is only valid within scope of onNext method. You can only call its method in
  99    *          onNext, do NOT store it and call it later outside onNext.
 100    */
 101   void onNext(Result[] results, ScanController controller);
 102
 103   /**
 104    * Indicate that there is a heartbeat message but we have not cumulated enough cells to call
 105    * {@link #onNext(Result[], ScanController)}.
 106    * <p>
 107    * Note that this method will always be called when RS returns something to us but we do not have
 108    * enough cells to call {@link #onNext(Result[], ScanController)}. Sometimes it may not be a
 109    * 'heartbeat' message for RS, for example, we have a large row with many cells and size limit is
 110    * exceeded before sending all the cells for this row. For RS it does send some data to us and the
 111    * time limit has not been reached, but we can not return the data to client so here we call this
 112    * method to tell client we have already received something.
 113    * <p>
 114    * This method give you a chance to terminate a slow scan operation.
 115    * @param controller used to suspend or terminate the scan. Notice that the {@code controller}
 116    *          instance is only valid within the scope of onHeartbeat method. You can only call its
 117    *          method in onHeartbeat, do NOT store it and call it later outside onHeartbeat.
 118    */
 119   default void onHeartbeat(ScanController controller) {
 120   }
 121 }