"Fossies" - the Fresh Open Source Software Archive

Member "hbase-2.4.6/docs/apidocs/src-html/org/apache/hadoop/hbase/client/AdvancedScanResultConsumer.ScanController.html" (22 Jan 2020, 12898 Bytes) of package /linux/misc/hbase-2.4.6-bin.tar.gz:


Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the project site itself.

001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.client;
019
020import java.util.Optional;
021
022import org.apache.yetus.audience.InterfaceAudience;
023
024/**
025 * This is the low level API for asynchronous scan.
026 * <p>
027 * All results that match the given scan object will be passed to this class by calling
028 * {@link #onNext(Result[], ScanController)}. {@link #onComplete()} means the scan is finished, and
029 * {@link #onError(Throwable)} means we hit an unrecoverable error and the scan is terminated.
030 * {@link #onHeartbeat(ScanController)} means the RS is still working but we can not get a valid
031 * result to call {@link #onNext(Result[], ScanController)}. This is usually because the matched
032 * results are too sparse, for example, a filter which almost filters out everything is specified.
033 * <p>
034 * Notice that, all the methods here will be called directly in the thread which we send request to
035 * HBase service. So if you want the asynchronous scanner fetch data from HBase in background while
036 * you process the returned data, you need to move the processing work to another thread to make the
037 * {@link #onNext(Result[], ScanController)} call return immediately. And please do NOT do any time
038 * consuming tasks in these methods unless you know what you are doing.
039 * @since 2.0.0
040 */
041@InterfaceAudience.Public
042public interface AdvancedScanResultConsumer extends ScanResultConsumerBase {
043
044  /**
045   * Used to resume a scan.
046   */
047  @InterfaceAudience.Public
048  interface ScanResumer {
049
050    /**
051     * Resume the scan. You are free to call it multiple time but only the first call will take
052     * effect.
053     */
054    void resume();
055  }
056
057  /**
058   * Used to suspend or stop a scan, or get a scan cursor if available.
059   * <p>
060   * Notice that, you should only call the {@link #suspend()} or {@link #terminate()} inside onNext
061   * or onHeartbeat method. A IllegalStateException will be thrown if you call them at other places.
062   * <p>
063   * You can only call one of the {@link #suspend()} and {@link #terminate()} methods(of course you
064   * are free to not call them both), and the methods are not reentrant. An IllegalStateException
065   * will be thrown if you have already called one of the methods.
066   */
067  @InterfaceAudience.Public
068  interface ScanController {
069
070    /**
071     * Suspend the scan.
072     * <p>
073     * This means we will stop fetching data in background, i.e., will not call onNext any more
074     * before you resume the scan.
075     * @return A resumer used to resume the scan later.
076     */
077    ScanResumer suspend();
078
079    /**
080     * Terminate the scan.
081     * <p>
082     * This is useful when you have got enough results and want to stop the scan in onNext method,
083     * or you want to stop the scan in onHeartbeat method because it has spent too many time.
084     */
085    void terminate();
086
087    /**
088     * Get the scan cursor if available.
089     * @return The scan cursor.
090     */
091    Optional<Cursor> cursor();
092  }
093
094  /**
095   * Indicate that we have receive some data.
096   * @param results the data fetched from HBase service.
097   * @param controller used to suspend or terminate the scan. Notice that the {@code controller}
098   *          instance is only valid within scope of onNext method. You can only call its method in
099   *          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}