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.io.retry; 19 20 import org.apache.hadoop.classification.InterfaceStability; 21 22 /** 23 * <p> 24 * Specifies a policy for retrying method failures. 25 * Implementations of this interface should be immutable. 26 * </p> 27 */ 28 @InterfaceStability.Evolving 29 public interface RetryPolicy { 30 31 /** 32 * Returned by {@link RetryPolicy#shouldRetry(Exception, int, int, boolean)}. 33 */ 34 @InterfaceStability.Evolving 35 public static class RetryAction { 36 37 // A few common retry policies, with no delays. 38 public static final RetryAction FAIL = 39 new RetryAction(RetryDecision.FAIL); 40 public static final RetryAction RETRY = 41 new RetryAction(RetryDecision.RETRY); 42 public static final RetryAction FAILOVER_AND_RETRY = 43 new RetryAction(RetryDecision.FAILOVER_AND_RETRY); 44 45 public final RetryDecision action; 46 public final long delayMillis; 47 public final String reason; 48 RetryAction(RetryDecision action)49 public RetryAction(RetryDecision action) { 50 this(action, 0, null); 51 } 52 RetryAction(RetryDecision action, long delayTime)53 public RetryAction(RetryDecision action, long delayTime) { 54 this(action, delayTime, null); 55 } 56 RetryAction(RetryDecision action, long delayTime, String reason)57 public RetryAction(RetryDecision action, long delayTime, String reason) { 58 this.action = action; 59 this.delayMillis = delayTime; 60 this.reason = reason; 61 } 62 63 @Override toString()64 public String toString() { 65 return getClass().getSimpleName() + "(action=" + action 66 + ", delayMillis=" + delayMillis + ", reason=" + reason + ")"; 67 } 68 69 public enum RetryDecision { 70 FAIL, 71 RETRY, 72 FAILOVER_AND_RETRY 73 } 74 } 75 76 /** 77 * <p> 78 * Determines whether the framework should retry a method for the given 79 * exception, and the number of retries that have been made for that operation 80 * so far. 81 * </p> 82 * 83 * @param e The exception that caused the method to fail 84 * @param retries The number of times the method has been retried 85 * @param failovers The number of times the method has failed over to a 86 * different backend implementation 87 * @param isIdempotentOrAtMostOnce <code>true</code> if the method is 88 * {@link Idempotent} or {@link AtMostOnce} and so can reasonably be 89 * retried on failover when we don't know if the previous attempt 90 * reached the server or not 91 * @return <code>true</code> if the method should be retried, 92 * <code>false</code> if the method should not be retried but 93 * shouldn't fail with an exception (only for void methods) 94 * @throws Exception The re-thrown exception <code>e</code> indicating that 95 * the method failed and should not be retried further 96 */ shouldRetry(Exception e, int retries, int failovers, boolean isIdempotentOrAtMostOnce)97 public RetryAction shouldRetry(Exception e, int retries, int failovers, 98 boolean isIdempotentOrAtMostOnce) throws Exception; 99 } 100