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 * Makes a method time constrained. 41 * 42 * <p>For example, this {@code load()} method should not take more than 43 * a second, and should be interrupted if it takes more: 44 * 45 * <pre> @Timeable(limit = 1, unit = TimeUnit.SECONDS) 46 * String load(String resource) { 47 * // something that runs potentially long 48 * }</pre> 49 * 50 * <p>Important to note that in Java 1.5+ it is impossible to force thread 51 * termination, for many reasons. Thus, we can't 52 * just call {@code Thread.stop()}, 53 * when a thread is over a specified time limit. The best thing we can do is to 54 * call {@link Thread#interrupt()} and hope that the thread itself 55 * is checking its 56 * {@link Thread#isInterrupted()} status. If you want to design your long 57 * running methods in a way that {@link Timeable} can terminate them, embed 58 * a checker into your most intessively used place, for example: 59 * 60 * <pre> @Timeable(limit = 1, unit = TimeUnit.SECONDS) 61 * String load(String resource) { 62 * while (true) { 63 * if (Thread.currentThread.isInterrupted()) { 64 * throw new IllegalStateException("time out"); 65 * } 66 * // execution as usual 67 * } 68 * }</pre> 69 * 70 * @since 0.7.16 71 * @see <a href="http://aspects.jcabi.com">http://aspects.jcabi.com/</a> 72 * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/misc/threadPrimitiveDeprecation.html">Why Are Thread.stop, Thread.suspend, Thread.resume and Runtime.runFinalizersOnExit Deprecated?</a> 73 * @see <a href="http://www.yegor256.com/2014/06/20/limit-method-execution-time.html">Limit Java Method Execution Time, by Yegor Bugayenko</a> 74 */ 75 @Documented 76 @Retention(RetentionPolicy.RUNTIME) 77 @Target(ElementType.METHOD) 78 public @interface Timeable { 79 80 /** 81 * The default maximum amount (of seconds). 82 */ 83 int DEFAULT_LIMIT = 15; 84 85 /** 86 * Maximum amount allowed for this method. 87 * @return The limit 88 */ 89 int limit() default Timeable.DEFAULT_LIMIT; 90 91 /** 92 * Time unit for the limit. 93 * 94 * <p>The minimum unit you can use is a second. We simply can't monitor with 95 * a frequency higher than a second. 96 * @return The time unit 97 */ 98 TimeUnit unit() default TimeUnit.SECONDS; 99 100 }