BackoffPolicy.java

/* Copyright (c) 2008 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package com.google.gdata.client.uploader;

/**
 * Policy class for determining how long to wait before retrying an HTTP
 * request.
 * 
 * 
 */
public interface BackoffPolicy {

  /**
   * Default backoff policy with a factor of 2, starting at 500ms and getting
   * capped at 64000ms.
   */
  public static BackoffPolicy DEFAULT = new BackoffPolicy() {
    
    /**
     * Default maximum amount of time to wait before making a retry (we back
     * off -- with a factor of 2 -- such that the requests are delayed by
     * the following number of seconds: .5, 1, 2, 4, 8, 16, 32, 64, 64, 64,
     * 64 ... etc.). The back off will increase by a factor of 2 until
     * backoffMs >= BACKOFF_DELAY_LIMIT_MS, at which point
     * backoffDelaySeconds will be assigned the limit.
     */
    private static final long BACKOFF_DELAY_LIMIT_MS = 64000L;
    
    /**
     * Initial backoff amount.
     */
    private static final long INITIAL_BACKOFF_MS = 500L;
    
    /**
     * Backoff factor
     */
    private static final long BACKOFF_FACTOR = 2;
    
    /**
     * Number milliseconds to wait before retrying an HTTP request.
     */
    private long backoffMs = INITIAL_BACKOFF_MS;
    
    public long getNextBackoffMs() {
      
      // Get the value to return
      long returnValueMs = backoffMs;
      
      // Update backoffMs for the next call.
      long nextBackoffMs = backoffMs * BACKOFF_FACTOR;
      backoffMs = (nextBackoffMs > BACKOFF_DELAY_LIMIT_MS)
          ? BACKOFF_DELAY_LIMIT_MS : nextBackoffMs;
      
      return returnValueMs;
    }
    
    public void reset() {
      backoffMs = INITIAL_BACKOFF_MS;
    }
  };
  
  /**
   * Value indicating that no more retries should be made, 
   * {@see #getNextBackoffMs()}.
   */
  public static final long STOP = -1L;
  
  /**
   * Gets the number of milliseconds to wait before retrying an HTTP request.
   * If {@link #STOP} is returned, no retries should be made.
   * 
   * This method should be used as follows:
   * <pre>
   *   long backoffTime = backoffPolicy.getNextBackoffMs();
   *   if (backoffTime = BackoffPolicy.STOP) {
   *     // Stop retrying.
   *   } else {
   *     // Retry after backoffTime.
   *   }
   * </pre>
   * 
   * @return the number of milliseconds to wait when backing off requests, or
   *     {@link #STOP} if no more retries should be made
   */
  public long getNextBackoffMs();
  
  /**
   * Resets the policy to begin from its initial state.
   */
  public void reset();
}