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

   1 /**
   2  *
   3  * Licensed to the Apache Software Foundation (ASF) under one
   4  * or more contributor license agreements.  See the NOTICE file
   5  * distributed with this work for additional information
   6  * regarding copyright ownership.  The ASF licenses this file
   7  * to you under the Apache License, Version 2.0 (the
   8  * "License"); you may not use this file except in compliance
   9  * with the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 package org.apache.hadoop.hbase.client;
  21
  22 import java.io.IOException;
  23
  24 import org.apache.yetus.audience.InterfaceAudience;
  25
  26 /**
  27  * A Callable&lt;T&gt; that will be retried. If {@link #call(int)} invocation throws exceptions,
  28  * we will call {@link #throwable(Throwable, boolean)} with whatever the exception was.
  29  * @param <T> result class from executing <tt>this</tt>
  30  */
  31 @InterfaceAudience.Private
  32 public interface RetryingCallable<T> {
  33   /**
  34    * Prepare by setting up any connections to servers, etc., ahead of call invocation.
  35    * TODO: We call prepare before EVERY call. Seems wrong. FIX!!!!
  36    * @param reload Set this to true if need to requery locations
  37    * @throws IOException e
  38    */
  39   void prepare(final boolean reload) throws IOException;
  40
  41   /**
  42    * Called when call throws an exception and we are going to retry; take action to
  43    * make it so we succeed on next call (clear caches, do relookup of locations, etc.).
  44    * @param t        throwable which was thrown
  45    * @param retrying True if we are in retrying mode (we are not in retrying mode when max
  46    *                 retries == 1; we ARE in retrying mode if retries &gt; 1 even when we are the
  47    *                 last attempt)
  48    */
  49   void throwable(final Throwable t, boolean retrying);
  50
  51   /**
  52    * @return Some details from the implementation that we would like to add to a terminating
  53    *         exception; i.e. a fatal exception is being thrown ending retries and we might like to
  54    *         add more implementation-specific detail on to the exception being thrown.
  55    */
  56   String getExceptionMessageAdditionalDetail();
  57
  58   /**
  59    * @param pause time to pause
  60    * @param tries amount of tries until till sleep
  61    * @return Suggestion on how much to sleep between retries
  62    */
  63   long sleep(final long pause, final int tries);
  64
  65   /**
  66    * Computes a result, or throws an exception if unable to do so.
  67    *
  68    * @param callTimeout - the time available for this call. 0 for infinite.
  69    * @return computed result
  70    * @throws Exception if unable to compute a result
  71    */
  72   T call(int callTimeout) throws Exception;
  73 }