CAMEL-11578: Add javadoc to util.backoff
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/04f07062 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/04f07062 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/04f07062 Branch: refs/heads/master Commit: 04f07062eb928fe53e40362f67f42b4b53e19f00 Parents: 29a3b28 Author: lburgazzoli <lburgazz...@gmail.com> Authored: Mon Aug 7 08:37:04 2017 +0200 Committer: lburgazzoli <lburgazz...@gmail.com> Committed: Tue Aug 8 13:29:28 2017 +0200 ---------------------------------------------------------------------- .../org/apache/camel/util/backoff/BackOff.java | 34 ++++++++++++++++++++ .../camel/util/backoff/BackOffContext.java | 31 +++++++++++++++++- .../apache/camel/util/backoff/BackOffTimer.java | 9 +++++- ...SupervisingRouteControllerConfiguration.java | 2 +- 4 files changed, 73 insertions(+), 3 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/04f07062/camel-core/src/main/java/org/apache/camel/util/backoff/BackOff.java ---------------------------------------------------------------------- diff --git a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOff.java b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOff.java index 1e3d326..f38c957 100644 --- a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOff.java +++ b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOff.java @@ -21,6 +21,9 @@ import java.util.concurrent.TimeUnit; import org.apache.camel.util.ObjectHelper; +/** + * A back-off policy. + */ public final class BackOff { public static final long NEVER = -1L; public static final Duration MAX_DURATION = Duration.ofMillis(Long.MAX_VALUE); @@ -49,10 +52,16 @@ public final class BackOff { // Properties // ************************************* + /** + * @return the delay to wait before retry the operation. + */ public Duration getDelay() { return delay; } + /** + * The delay to wait before retry the operation. + */ public void setDelay(Duration delay) { this.delay = delay; } @@ -61,6 +70,9 @@ public final class BackOff { return maxDelay; } + /** + * The maximum back-off time after which the delay is not more increased. + */ public void setMaxDelay(Duration maxDelay) { this.maxDelay = maxDelay; } @@ -69,6 +81,10 @@ public final class BackOff { return maxElapsedTime; } + /** + * The maximum elapsed time after which the back-off should be considered + * exhausted and no more attempts should be made. + */ public void setMaxElapsedTime(Duration maxElapsedTime) { this.maxElapsedTime = maxElapsedTime; } @@ -77,6 +93,12 @@ public final class BackOff { return maxAttempts; } + /** + * The maximum number of attempts after which the back-off should be considered + * exhausted and no more attempts should be made. + * + * @param maxAttempts + */ public void setMaxAttempts(Long maxAttempts) { this.maxAttempts = maxAttempts; } @@ -85,6 +107,9 @@ public final class BackOff { return multiplier; } + /** + * The value to multiply the current interval by for each retry attempt. + */ public void setMultiplier(Double multiplier) { this.multiplier = multiplier; } @@ -108,6 +133,9 @@ public final class BackOff { return new Builder(); } + /** + * A builder for {@link BackOff} + */ public static final class Builder { private Duration delay = BackOff.DEFAULT_DELAY; private Duration maxDelay = BackOff.MAX_DURATION; @@ -115,6 +143,9 @@ public final class BackOff { private Long maxAttempts = Long.MAX_VALUE; private Double multiplier = BackOff.DEFAULT_MULTIPLIER; + /** + * Read values from the given {@link BackOff} + */ public Builder read(BackOff template) { delay = template.delay; maxDelay = template.maxDelay; @@ -174,6 +205,9 @@ public final class BackOff { return this; } + /** + * Build a new instance of {@link BackOff} + */ public BackOff build() { return new BackOff(delay, maxDelay, maxElapsedTime, maxAttempts, multiplier); } http://git-wip-us.apache.org/repos/asf/camel/blob/04f07062/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffContext.java ---------------------------------------------------------------------- diff --git a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffContext.java b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffContext.java index 502f0ad..cd46653 100644 --- a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffContext.java +++ b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffContext.java @@ -16,7 +16,9 @@ */ package org.apache.camel.util.backoff; - +/** + * The context associated to a back-off operation. + */ public final class BackOffContext { private final BackOff backOff; @@ -35,22 +37,37 @@ public final class BackOffContext { // Properties // ************************************* + /** + * The back-off associated with this context. + */ public BackOff backOff() { return backOff; } + /** + * The number of attempts so far. + */ public long getCurrentAttempts() { return currentAttempts; } + /** + * The current computed delay. + */ public long getCurrentDelay() { return currentDelay; } + /** + * The current elapsed time. + */ public long getCurrentElapsedTime() { return currentElapsedTime; } + /** + * Inform if the context is exhausted thus not more attempts should be made. + */ public boolean isExhausted() { return currentDelay == BackOff.NEVER; } @@ -59,6 +76,11 @@ public final class BackOffContext { // Impl // ************************************* + /** + * Return the number of milliseconds to wait before retrying the operation + * or ${@link BackOff#NEVER} to indicate that no further attempt should be + * made. + */ public long next() { // A call to next when currentDelay is set to NEVER has no effects // as this means that either the timer is exhausted or it has explicit @@ -83,6 +105,9 @@ public final class BackOffContext { return currentDelay; } + /** + * Reset the context. + */ public BackOffContext reset() { this.currentAttempts = 0; this.currentDelay = 0; @@ -91,6 +116,10 @@ public final class BackOffContext { return this; } + /** + * Mark the context as exhausted to indicate that no further attempt should + * be made. + */ public BackOffContext stop() { this.currentAttempts = 0; this.currentDelay = BackOff.NEVER; http://git-wip-us.apache.org/repos/asf/camel/blob/04f07062/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffTimer.java ---------------------------------------------------------------------- diff --git a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffTimer.java b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffTimer.java index d82c824..c0c035f 100644 --- a/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffTimer.java +++ b/camel-core/src/main/java/org/apache/camel/util/backoff/BackOffTimer.java @@ -22,7 +22,10 @@ import java.util.concurrent.TimeUnit; import org.apache.camel.util.function.ThrowingFunction; - +/** + * A simple timer utility that use a linked {@link BackOff} to determine when + * a task should be executed. + */ public class BackOffTimer { private final ScheduledExecutorService scheduler; @@ -30,6 +33,10 @@ public class BackOffTimer { this.scheduler = scheduler; } + /** + * Schedule the given function/task to be executed some time in the future + * according to the given backOff. + */ public CompletableFuture<BackOffContext> schedule(BackOff backOff, ThrowingFunction<BackOffContext, Boolean, Exception> function) { final BackOffContext context = new BackOffContext(backOff); final Task task = new Task(context, function); http://git-wip-us.apache.org/repos/asf/camel/blob/04f07062/components/camel-spring-boot/src/main/java/org/apache/camel/spring/boot/SupervisingRouteControllerConfiguration.java ---------------------------------------------------------------------- diff --git a/components/camel-spring-boot/src/main/java/org/apache/camel/spring/boot/SupervisingRouteControllerConfiguration.java b/components/camel-spring-boot/src/main/java/org/apache/camel/spring/boot/SupervisingRouteControllerConfiguration.java index 32ef447..bf68b6a 100644 --- a/components/camel-spring-boot/src/main/java/org/apache/camel/spring/boot/SupervisingRouteControllerConfiguration.java +++ b/components/camel-spring-boot/src/main/java/org/apache/camel/spring/boot/SupervisingRouteControllerConfiguration.java @@ -99,7 +99,7 @@ public class SupervisingRouteControllerConfiguration { private String maxElapsedTime; /** - * Teh maximum number of attempts after which the back-off is exhausted. + * The maximum number of attempts after which the back-off is exhausted. */ private Long maxAttempts;