Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you 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 org.apache.brooklyn.util.repeat; import static com.google.common.base.Preconditions.checkNotNull; import java.util.concurrent.Callable; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; import javax.annotation.Nullable; import org.apache.brooklyn.util.exceptions.Exceptions; import org.apache.brooklyn.util.exceptions.ReferenceWithError; import org.apache.brooklyn.util.repeat.Repeater; import org.apache.brooklyn.util.time.CountdownTimer; import org.apache.brooklyn.util.time.Duration; import org.apache.brooklyn.util.time.Time; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import com.google.common.base.Function; import com.google.common.base.Functions; import com.google.common.base.Preconditions; import com.google.common.base.Predicate; import com.google.common.base.Stopwatch; import com.google.common.util.concurrent.Callables; /** * Simple mechanism to repeat an operation periodically until a condition is satisfied. * <p> * In its simplest case it is passed two {@link Callable} objects, the <em>operation</em> * and the <em>condition</em> which are executed in that order. This execution is repeated * until the <em>condition</em> returns {@code true}, when the loop finishes. Further customization * can be applied to set the period between loops and place a maximum limit on how long the * loop should run for, as well as other timing and delay properties. * <p> * <pre>{@code * Repeater.create("Wait until the Frobnitzer is ready") * .until(new Callable<Boolean>() { * public Boolean call() { * String status = frobnitzer.getStatus() * return "Ready".equals(status) || "Failed".equals(status); * }}) * .limitIterationsTo(30) * .run() * }</pre> * <p> * The */ public class Repeater implements Callable<Boolean> { private static final Logger log = LoggerFactory.getLogger(Repeater.class); /** A small initial duration that something should wait between repeats, * e.g. when doing {@link #backoffTo(Duration)}. * <p> * Chosen to be small enough that a user won't notice at all, * but we're not going to be chewing up CPU while waiting. */ public static final Duration DEFAULT_REAL_QUICK_PERIOD = Duration.millis(10); private final String description; private Callable<?> body = Callables.returning(null); private Callable<Boolean> exitCondition; private Function<? super Integer, Duration> delayOnIteration = null; private Duration timeLimit = null; private int iterationLimit = 0; private boolean rethrowException = false; private boolean rethrowExceptionImmediately = false; private boolean warnOnUnRethrownException = true; public Repeater() { this(null); } /** * Construct a new instance of Repeater. * * @param description a description of the operation that will appear in debug logs. */ public Repeater(String description) { this.description = description != null ? description : "Repeater"; } public static Repeater create() { return create(null); } public static Repeater create(String description) { return new Repeater(description); } /** * Sets the main body of the loop to be a no-op; useful if using {@link #until(Callable)} instead * * @return {@literal this} to aid coding in a fluent style. * @deprecated since 0.7.0 this is no-op, as the repeater defaults to repeating nothing, simply remove the call, * using just <code>Repeater.until(...)</code>. */ public Repeater repeat() { return repeat(Callables.returning(null)); } /** * Sets the main body of the loop. * * @param body a closure or other Runnable that is executed in the main body of the loop. * @return {@literal this} to aid coding in a fluent style. */ public Repeater repeat(Runnable body) { checkNotNull(body, "body must not be null"); this.body = (body instanceof Callable) ? (Callable<?>) body : Executors.callable(body); return this; } /** * Sets the main body of the loop. * * @param body a closure or other Callable that is executed in the main body of the loop. * @return {@literal this} to aid coding in a fluent style. */ public Repeater repeat(Callable<?> body) { checkNotNull(body, "body must not be null"); this.body = body; return this; } /** * Set how long to wait between loop iterations. * * @param period how long to wait between loop iterations. * @param unit the unit of measurement of the period. * @return {@literal this} to aid coding in a fluent style. */ public Repeater every(long period, TimeUnit unit) { return every(Duration.of(period, unit)); } /** * Set how long to wait between loop iterations, as a constant function in {@link #delayOnIteration} */ public Repeater every(Duration duration) { Preconditions.checkNotNull(duration, "duration must not be null"); Preconditions.checkArgument(duration.toMilliseconds() > 0, "period must be positive: %s", duration); return delayOnIteration(Functions.constant(duration)); } public Repeater every(groovy.time.Duration duration) { return every(Duration.of(duration)); } /** sets a function which determines how long to delay on a given iteration between checks, * with 0 being mapped to the initial delay (after the initial check) */ public Repeater delayOnIteration(Function<? super Integer, Duration> delayFunction) { Preconditions.checkNotNull(delayFunction, "delayFunction must not be null"); this.delayOnIteration = delayFunction; return this; } /** sets the {@link #delayOnIteration(Function)} function to be an exponential backoff as follows: * @param initialDelay the delay on the first iteration, after the initial check * @param multiplier the rate at which to increase the loop delay, must be >= 1 * @param finalDelay an optional cap on the loop delay */ public Repeater backoff(final Duration initialDelay, final double multiplier, @Nullable final Duration finalDelay) { Preconditions.checkNotNull(initialDelay, "initialDelay"); Preconditions.checkArgument(multiplier >= 1.0, "multiplier >= 1.0"); return delayOnIteration(new Function<Integer, Duration>() { @Override public Duration apply(Integer iteration) { /* we iterate because otherwise we risk overflow errors by using multiplier^iteration; * e.g. with: * return Duration.min(initialDelay.multiply(Math.pow(multiplier, iteration)), finalDelay); */ Duration result = initialDelay; for (int i = 0; i < iteration; i++) { result = result.multiply(multiplier); if (finalDelay != null && result.compareTo(finalDelay) > 0) return finalDelay; } return result; } }); } /** convenience to start with a 10ms delay and exponentially back-off at a rate of 1.2 * up to a max per-iteration delay as supplied here. * 1.2 chosen because it decays nicely, going from 10ms to 1s in approx 25 iterations totalling 5s elapsed time. */ public Repeater backoffTo(final Duration finalDelay) { return backoff(Duration.millis(10), 1.2, finalDelay); } /** * Set code fragment that tests if the loop has completed. * * @param exitCondition a closure or other Callable that returns a boolean. If this code returns {@literal true} then the * loop will stop executing. * @return {@literal this} to aid coding in a fluent style. */ public Repeater until(Callable<Boolean> exitCondition) { Preconditions.checkNotNull(exitCondition, "exitCondition must not be null"); this.exitCondition = exitCondition; return this; } public <T> Repeater until(final T target, final Predicate<T> exitCondition) { Preconditions.checkNotNull(exitCondition, "exitCondition must not be null"); return until(new Callable<Boolean>() { @Override public Boolean call() throws Exception { return exitCondition.apply(target); } }); } /** * If the exit condition check throws an exception, it will be recorded and the last exception will be thrown on failure. * * @return {@literal this} to aid coding in a fluent style. */ public Repeater rethrowException() { this.rethrowException = true; return this; } /** * If the repeated body or the exit condition check throws an exception, then propagate that exception immediately. * * @return {@literal this} to aid coding in a fluent style. */ public Repeater rethrowExceptionImmediately() { this.rethrowExceptionImmediately = true; return this; } public Repeater suppressWarnings() { this.warnOnUnRethrownException = false; return this; } /** * Set the maximum number of iterations. * * The loop will exit if the condition has not been satisfied after this number of iterations. * * @param iterationLimit the maximum number of iterations. * @return {@literal this} to aid coding in a fluent style. */ public Repeater limitIterationsTo(int iterationLimit) { Preconditions.checkArgument(iterationLimit > 0, "iterationLimit must be positive: %s", iterationLimit); this.iterationLimit = iterationLimit; return this; } /** * @see #limitTimeTo(Duration) * * @param deadline the time that the loop should wait. * @param unit the unit of measurement of the period. * @return {@literal this} to aid coding in a fluent style. */ public Repeater limitTimeTo(long deadline, TimeUnit unit) { return limitTimeTo(Duration.of(deadline, unit)); } /** * Set the amount of time to wait for the condition. * The repeater will wait at least this long for the condition to be true, * and will exit soon after even if the condition is false. */ public Repeater limitTimeTo(Duration duration) { Preconditions.checkNotNull(duration, "duration must not be null"); Preconditions.checkArgument(duration.toMilliseconds() > 0, "deadline must be positive: %s", duration); this.timeLimit = duration; return this; } /** * Run the loop. * * @return true if the exit condition was satisfied; false if the loop terminated for any other reason. */ public boolean run() { return runKeepingError().getWithoutError(); } public void runRequiringTrue() { Stopwatch timer = Stopwatch.createStarted(); ReferenceWithError<Boolean> result = runKeepingError(); result.checkNoError(); if (!result.get()) throw new IllegalStateException(description + " unsatisfied after " + Duration.of(timer)); } public ReferenceWithError<Boolean> runKeepingError() { Preconditions.checkState(body != null, "repeat() method has not been called to set the body"); Preconditions.checkState(exitCondition != null, "until() method has not been called to set the exit condition"); Preconditions.checkState(delayOnIteration != null, "every() method (or other delaySupplier() / backoff() method) has not been called to set the loop delay"); Throwable lastError = null; int iterations = 0; CountdownTimer timer = timeLimit != null ? CountdownTimer.newInstanceStarted(timeLimit) : CountdownTimer.newInstancePaused(Duration.PRACTICALLY_FOREVER); while (true) { Duration delayThisIteration = delayOnIteration.apply(iterations); iterations++; try { body.call(); } catch (Exception e) { log.warn(description, e); if (rethrowExceptionImmediately) throw Exceptions.propagate(e); } boolean done = false; try { lastError = null; done = exitCondition.call(); } catch (Exception e) { if (log.isDebugEnabled()) log.debug(description, e); lastError = e; if (rethrowExceptionImmediately) throw Exceptions.propagate(e); } if (done) { if (log.isDebugEnabled()) log.debug("{}: condition satisfied", description); return ReferenceWithError.newInstanceWithoutError(true); } else { if (log.isDebugEnabled()) { String msg = String.format("%s: unsatisfied during iteration %s %s", description, iterations, (iterationLimit > 0 ? "(max " + iterationLimit + " attempts)" : "") + (timer.isRunning() ? "(" + Time.makeTimeStringRounded(timer.getDurationRemaining()) + " remaining)" : "")); if (iterations == 1) { log.debug(msg); } else { log.trace(msg); } } } if (iterationLimit > 0 && iterations >= iterationLimit) { if (log.isDebugEnabled()) log.debug("{}: condition not satisfied and exceeded iteration limit", description); if (rethrowException && lastError != null) { log.warn("{}: error caught checking condition (rethrowing): {}", description, lastError.getMessage()); throw Exceptions.propagate(lastError); } if (warnOnUnRethrownException && lastError != null) log.warn("{}: error caught checking condition: {}", description, lastError.getMessage()); return ReferenceWithError.newInstanceMaskingError(false, lastError); } if (timer.isExpired()) { if (log.isDebugEnabled()) log.debug("{}: condition not satisfied, with {} elapsed (limit {})", new Object[] { description, Time.makeTimeStringRounded(timer.getDurationElapsed()), Time.makeTimeStringRounded(timeLimit) }); if (rethrowException && lastError != null) { log.error("{}: error caught checking condition: {}", description, lastError.getMessage()); throw Exceptions.propagate(lastError); } return ReferenceWithError.newInstanceMaskingError(false, lastError); } Time.sleep(delayThisIteration); } } public String getDescription() { return description; } public Duration getTimeLimit() { return timeLimit; } @Override public Boolean call() throws Exception { return run(); } }