1 /* 2 * Copyright (c) 2012-2024, jcabi.com 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 1) Redistributions of source code must retain the above 8 * copyright notice, this list of conditions and the following 9 * disclaimer. 2) Redistributions in binary form must reproduce the above 10 * copyright notice, this list of conditions and the following 11 * disclaimer in the documentation and/or other materials provided 12 * with the distribution. 3) Neither the name of the jcabi.com nor 13 * the names of its contributors may be used to endorse or promote 14 * products derived from this software without specific prior written 15 * permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 28 * OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 package com.jcabi.aspects; 31 32 import java.lang.annotation.Documented; 33 import java.lang.annotation.ElementType; 34 import java.lang.annotation.Retention; 35 import java.lang.annotation.RetentionPolicy; 36 import java.lang.annotation.Target; 37 import java.util.concurrent.TimeUnit; 38 39 /** 40 * Schedules the method to run with fixed delay, automatically. 41 * 42 * <p>For example, you want a method to do something every minute: 43 * 44 * <pre> @ScheduleWithFixedDelay(delay = 1, unit = TimeUnit.MINUTES) 45 * public class Bucket implements Runnable, Closeable { 46 * @Override 47 * void run() { 48 * // do some routine job 49 * } 50 * @Override 51 * void close() { 52 * // close operations 53 * } 54 * }</pre> 55 * 56 * <p>Execution will be started as soon as you make an instance of the class, 57 * and will be stopped when you call {@code close()}: 58 * 59 * <pre> Bucket bucket = new Bucket(); 60 * // some time later 61 * bucket.close();</pre> 62 * 63 * <p>In order to be executed the class should implement either 64 * {@link Runnable} or {@link java.util.concurrent.Callable}. In order to 65 * be closed and stopped, your the class should implement 66 * {@link java.io.Closeable} and its {@code close()} 67 * method should be explicitly called 68 * at the moment you want it to stop. 69 * 70 * <p><b>NOTE:</b> It should be pointed out that in order to ensure that there 71 * are no duplicate executions, you can only schedule an execution once between 72 * all equal objects (i.e. instances that are equal as per 73 * {@link Object#equals(Object)})). Invoking the same method multiple times, 74 * without stopping it first, will result in an {@link IllegalStateException} 75 * being thrown. 76 * 77 * @since 0.7.16 78 * @see <a href="http://aspects.jcabi.com">http://aspects.jcabi.com/</a> 79 */ 80 @Documented 81 @Retention(RetentionPolicy.RUNTIME) 82 @Target(ElementType.TYPE) 83 public @interface ScheduleWithFixedDelay { 84 85 /** 86 * Delay, in time units. 87 * @return The delay time amount 88 */ 89 int delay() default 1; 90 91 /** 92 * Time units of delay. 93 * @return The time unit 94 */ 95 TimeUnit unit() default TimeUnit.MINUTES; 96 97 /** 98 * How long to wait for the task to finish after shutdown in await units. 99 * 100 * @return The await time amount 101 */ 102 int await() default 1; 103 104 /** 105 * Time units of await time. 106 * @return The await time unit 107 */ 108 TimeUnit awaitUnit() default TimeUnit.MINUTES; 109 110 /** 111 * How many times to do a forceful shutdown after await time. 112 * Each forceful shutdown attempt will be followed by a 1 second wait to 113 * allow the threads to finish. 114 * @return The number if times 115 */ 116 int shutdownAttempts() default 1; 117 118 /** 119 * Total number of fixed threads. 120 * @return The number of threads 121 */ 122 int threads() default 1; 123 124 /** 125 * Be less verbose. 126 * @return The flag 127 */ 128 boolean verbose() default true; 129 }