001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.camel.util.backoff;
018
019import java.util.Set;
020import java.util.function.BiConsumer;
021
022import org.apache.camel.util.function.ThrowingFunction;
023
024/**
025 * A simple timer utility that use a linked {@link BackOff} to determine when a task should be executed.
026 */
027public interface BackOffTimer {
028
029    /**
030     * Schedules a task to run according to the backoff settings
031     *
032     * @param  backOff  the settings for how often to run the task
033     * @param  function the function to call for each run
034     * @return          the task
035     */
036    Task schedule(BackOff backOff, ThrowingFunction<Task, Boolean, Exception> function);
037
038    /**
039     * Gets the name of this timer.
040     */
041    String getName();
042
043    /**
044     * Removes the task
045     */
046    void remove(Task task);
047
048    /**
049     * Access to unmodifiable set of all the tasks
050     */
051    Set<Task> getTasks();
052
053    /**
054     * Number of tasks
055     */
056    int size();
057
058    // ****************************************
059    // TimerTask
060    // ****************************************
061
062    interface Task {
063        enum Status {
064            Active,
065            Inactive,
066            Exhausted,
067            Completed,
068            Failed
069        }
070
071        /**
072         * Name of this task
073         */
074        String getName();
075
076        /**
077         * The back-off associated with this task.
078         */
079        BackOff getBackOff();
080
081        /**
082         * Gets the task status.
083         */
084        Status getStatus();
085
086        /**
087         * The number of attempts so far.
088         */
089        long getCurrentAttempts();
090
091        /**
092         * The current computed delay.
093         */
094        long getCurrentDelay();
095
096        /**
097         * The current elapsed time.
098         */
099        long getCurrentElapsedTime();
100
101        /**
102         * The time the first attempt was performed.
103         */
104        long getFirstAttemptTime();
105
106        /**
107         * The time the last attempt has been performed.
108         */
109        long getLastAttemptTime();
110
111        /**
112         * An indication about the time the next attempt will be made.
113         */
114        long getNextAttemptTime();
115
116        /**
117         * The task failed for some un-expected exception
118         */
119        Throwable getException();
120
121        /**
122         * Reset the task.
123         */
124        void reset();
125
126        /**
127         * Cancel the task.
128         */
129        void cancel();
130
131        /**
132         * Action to execute when the context is completed (cancelled or exhausted)
133         *
134         * @param whenCompleted the consumer.
135         */
136        void whenComplete(BiConsumer<Task, Throwable> whenCompleted);
137    }
138}