Warning free build on java-8. Corrected javadoc.

Author: shasts

src/main/java/com/github/rholder/retry/AttemptTimeLimiter.java

@@ -28,6 +28,7 @@ public interface AttemptTimeLimiter<V> {
     /**
      * @param callable to subject to the time limit
      * @return the return of the given callable
+     * @throws java.lang.Exception All exceptions that can happen because of this invocation.
      */
     V call(Callable<V> callable) throws Exception;
 }

src/main/java/com/github/rholder/retry/AttemptTimeLimiters.java

@@ -36,6 +36,7 @@ private AttemptTimeLimiters(){
     }
 
     /**
+     * @param <V> The type of the computation result.
      * @return an {@link AttemptTimeLimiter} impl which has no time limit
      */
     public static <V> AttemptTimeLimiter<V> noTimeLimit() {
@@ -48,6 +49,7 @@ public static <V> AttemptTimeLimiter<V> noTimeLimit() {
      * {@link SimpleTimeLimiter#SimpleTimeLimiter(ExecutorService)}, which this AttemptTimeLimiter uses.
      * @param duration that an attempt may persist before being circumvented
      * @param timeUnit of the 'duration' arg
+     * @param <V> The type of the computation result.
      * @return an {@link AttemptTimeLimiter} with a fixed time limit for each attempt
      */
     public static <V> AttemptTimeLimiter<V> fixedTimeLimit(long duration, @Nonnull TimeUnit timeUnit) {
@@ -59,6 +61,7 @@ public static <V> AttemptTimeLimiter<V> fixedTimeLimit(long duration, @Nonnull T
      * @param duration that an attempt may persist before being circumvented
      * @param timeUnit of the 'duration' arg
      * @param executorService used to enforce time limit
+     * @param <V> The type of the computation result.
      * @return an {@link AttemptTimeLimiter} with a fixed time limit for each attempt
      */
     public static <V> AttemptTimeLimiter<V> fixedTimeLimit(long duration, @Nonnull TimeUnit timeUnit, @Nonnull ExecutorService executorService) {

src/main/java/com/github/rholder/retry/RetryException.java

@@ -61,13 +61,15 @@ public RetryException(String message, int numberOfFailedAttempts, Attempt<?> las
 
     /**
      * Returns the number of failed attempts
+     * @return Gets the number of failed attempts
      */
     public int getNumberOfFailedAttempts() {
         return numberOfFailedAttempts;
     }
 
     /**
      * Returns the last failed attempt
+     * @return The last failed attempt.
      */
     public Attempt<?> getLastFailedAttempt() {
         return lastFailedAttempt;

src/main/java/com/github/rholder/retry/Retryer.java

@@ -89,6 +89,8 @@ public Retryer(@Nonnull AttemptTimeLimiter<V> attemptTimeLimiter,
      * accepts the attempt, the stop strategy is used to decide if a new attempt
      * must be made. Then the wait strategy is used to decide how must time to sleep,
      * and a new attempt is made.
+     * @param callable The callable task which need to be executed.
+     * @return The computed result of the given callable.
      * @throws ExecutionException if the given callable throws an exception, and the
      * rejection predicate considers the attempt as successful. The original exception
      * is wrapped into an ExecutionException.
@@ -128,6 +130,7 @@ public V call(Callable<V> callable) throws ExecutionException, RetryException {
      * Wraps the given callable into a {@link RetryerCallable}, which can be submitted to an executor.
      * The returned callable will use this retryer to call the given callable
      * @param callable the callable to wrap
+     * @return A {@link RetryerCallable} containing and retryer and a callable.
      */
     public RetryerCallable<V> wrap(Callable<V> callable) {
         return new RetryerCallable<V>(this, callable);

src/main/java/com/github/rholder/retry/RetryerBuilder.java

@@ -40,6 +40,7 @@ private RetryerBuilder() {
 
     /**
      * Constructs a new builder
+     * @param <V> The type of result, the callable task is supposed to return.
      * @return the new builder
      */
     public static <V> RetryerBuilder<V> newBuilder() {

src/main/java/com/github/rholder/retry/StopStrategies.java

@@ -32,6 +32,7 @@ private StopStrategies() {
 
     /**
      * Returns a stop strategy which consists in never stopping retrying
+     * @return A stop strategy which never stops.
      */
     public static StopStrategy neverStop() {
         return NEVER_STOP;
@@ -40,6 +41,7 @@ public static StopStrategy neverStop() {
     /**
      * Returns a stop strategy which consists in stopping after N failed attempts
      * @param attemptNumber the number of failed attempts before stopping
+     * @return A stop strategy which stops after {@code attemptNumber} attempts
      */
     public static StopStrategy stopAfterAttempt(int attemptNumber) {
         return new StopAfterAttemptStrategy(attemptNumber);
@@ -48,6 +50,7 @@ public static StopStrategy stopAfterAttempt(int attemptNumber) {
     /**
      * Returns a stop strategy which consists in stopping after a given delay
      * @param delayInMillis the delay, in milliseconds, starting with the start of the first attempt.
+     * @return A stop strategy which stops after {@code delayInMillis} time in milli seconds.
      */
     public static StopStrategy stopAfterDelay(long delayInMillis) {
         return new StopAfterDelayStrategy(delayInMillis);

src/main/java/com/github/rholder/retry/WaitStrategies.java

@@ -36,6 +36,7 @@ private WaitStrategies() {
 
     /**
      * Returns a strategy that doesn't sleep at all before retrying.
+     * @return A wait strategy which doesn't wait between retries
      */
     public static WaitStrategy noWait() {
         return NO_WAIT_STRATEGY;
@@ -46,6 +47,7 @@ public static WaitStrategy noWait() {
      *
      * @param sleepTime the time to sleep
      * @param timeUnit the unit of the time to sleep
+     * @return A wait strategy with fixed {@code sleepTime}
      * @throws IllegalStateException if the sleep time is < 0.
      */
     public static WaitStrategy fixedWait(long sleepTime, @Nonnull TimeUnit timeUnit) throws IllegalStateException {
@@ -58,6 +60,7 @@ public static WaitStrategy fixedWait(long sleepTime, @Nonnull TimeUnit timeUnit)
      *
      * @param maximumTime the maximum time to sleep
      * @param timeUnit the unit of the maximum time
+     * @return A wait strategy with random wait time
      * @throws IllegalStateException if the maximum sleep time is <= 0.
      */
     public static WaitStrategy randomWait(long maximumTime, @Nonnull TimeUnit timeUnit) {
@@ -72,6 +75,7 @@ public static WaitStrategy randomWait(long maximumTime, @Nonnull TimeUnit timeUn
      * @param minimumTimeUnit the unit of the minimum time
      * @param maximumTime the maximum time to sleep
      * @param maximumTimeUnit the unit of the maximum time
+     * @return A wait strategy with random wait time
      * @throws IllegalStateException if the minimum sleep time is < 0, or if the
      * maximum sleep time is less than (or equals to) the minimum.
      */
@@ -94,6 +98,7 @@ public static WaitStrategy randomWait(long minimumTime,
      * @param initialSleepTimeUnit the unit of the initial sleep time
      * @param increment the increment added to the previous sleep time after each failed attempt
      * @param incrementTimeUnit the unit of the increment
+     * @return A wait strategy with wait time following the incremental pattern.
      */
     public static WaitStrategy incrementingWait(long initialSleepTime,
                                                 @Nonnull TimeUnit initialSleepTimeUnit,
@@ -108,6 +113,8 @@ public static WaitStrategy incrementingWait(long initialSleepTime,
     /**
      * Returns a strategy which sleeps for an exponential amount of time after the first failed attempt,
      * and in exponentially incrementing amounts after each failed attempt up to Long.MAX_VALUE.
+     *
+     * @return A wait strategy with wait time following the exponential pattern.
      */
     public static WaitStrategy exponentialWait() {
         return new ExponentialWaitStrategy(1, Long.MAX_VALUE);
@@ -119,6 +126,7 @@ public static WaitStrategy exponentialWait() {
      *
      * @param maximumTime the maximum time to sleep
      * @param maximumTimeUnit the unit of the maximum time
+     * @return A wait strategy with wait time following the exponential pattern.
      */
     public static WaitStrategy exponentialWait(long maximumTime,
                                                @Nonnull TimeUnit maximumTimeUnit) {
@@ -129,10 +137,13 @@ public static WaitStrategy exponentialWait(long maximumTime,
     /**
      * Returns a strategy which sleeps for an exponential amount of time after the first failed attempt,
      * and in exponentially incrementing amounts after each failed attempt up to the maximumTime.
+     * The wait time between the retries can be controlled by the multiplier.
+     * nextWaitTime = exponentialIncrement * {@code multiplier}.
      *
      * @param multiplier multiply the wait time calculated by this
      * @param maximumTime the maximum time to sleep
      * @param maximumTimeUnit the unit of the maximum time
+     * @return A wait strategy with wait time following the exponential pattern.
      */
     public static WaitStrategy exponentialWait(long multiplier,
                                                long maximumTime,
@@ -144,6 +155,8 @@ public static WaitStrategy exponentialWait(long multiplier,
     /**
      * Returns a strategy which sleeps for an increasing amount of time after the first failed attempt,
      * and in Fibonacci increments after each failed attempt up to {@link Long#MAX_VALUE}.
+     *
+     * @return A wait strategy with wait time following the fibonacci pattern.
      */
     public static WaitStrategy fibonacciWait() {
         return new FibonacciWaitStrategy(1, Long.MAX_VALUE);
@@ -155,6 +168,7 @@ public static WaitStrategy fibonacciWait() {
      *
      * @param maximumTime the maximum time to sleep
      * @param maximumTimeUnit the unit of the maximum time
+     * @return  A wait strategy with wait time following the fibonacci pattern.
      */
     public static WaitStrategy fibonacciWait(long maximumTime,
                                              @Nonnull TimeUnit maximumTimeUnit) {
@@ -165,10 +179,13 @@ public static WaitStrategy fibonacciWait(long maximumTime,
     /**
      * Returns a strategy which sleeps for an increasing amount of time after the first failed attempt,
      * and in Fibonacci increments after each failed attempt up to the {@code maximumTime}.
+     * The wait time between the retries can be controlled by the multiplier.
+     * nextWaitTime = fibonacciIncrement * {@code multiplier}.
      *
      * @param multiplier multiply the wait time calculated by this
      * @param maximumTime the maximum time to sleep
      * @param maximumTimeUnit the unit of the maximum time
+     * @return A wait strategy with wait time following the fibonacci pattern.
      */
     public static WaitStrategy fibonacciWait(long multiplier,
                                              long maximumTime,

src/main/java/com/github/rholder/retry/WaitStrategy.java

@@ -26,6 +26,7 @@ public interface WaitStrategy {
      * Returns the time, in milliseconds, to sleep before retrying.
      * @param previousAttemptNumber the number, starting from 1, of the previous (failed) attempt
      * @param delaySinceFirstAttemptInMillis the delay since the start of the first attempt, in milliseconds
+     * @return the sleep time before next attempt
      */
     long computeSleepTime(int previousAttemptNumber, long delaySinceFirstAttemptInMillis);
 }