Debian Codegraph @

src/main/java/com/jcabi/aspects/Cacheable.java

raw
1 /**
2 * Copyright (c) 2012-2017, 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 response cacheable in memory for some time.
41 *
42 * <p>For example, this {@code load()} method loads some data from the network
43 * and we want it to cache loaded data for 5 seconds (to avoid delays):
44 *
45 * <pre> &#64;Cacheable(lifetime = 5, unit = TimeUnit.SECONDS)
46 * String load(String resource) throws IOException {
47 * return "something";
48 * }</pre>
49 *
50 * <p>You can cache them forever, which means that once calculated and
51 * cached value will never expire (may be a nice alternative to static
52 * initializers):
53 *
54 * <pre> &#64;Cacheable(forever = true)
55 * String load(String resource) throws IOException {
56 * return "something";
57 * }</pre>
58 *
59 * <p>Since version 0.7.14 you can also annotate methods that should flush
60 * cache of the object.
61 *
62 * <p>Since 0.7.18 you can control when exactly flushing happens, with
63 * {@link Cacheable.FlushBefore} and {@link Cacheable.FlushAfter} annotations
64 * ({@link Cacheable.Flush} is deprecated), for example:
65 *
66 * <pre>public class Page {
67 * &#64;Cacheable
68 * public String get() {
69 * // load data from external source, e.g. the network
70 * return data;
71 * }
72 * &#64;Cacheable.FlushBefore
73 * public void set(String data) {
74 * // save data to the network
75 * }
76 * }</pre>
77 *
78 * @author Yegor Bugayenko ([email protected])
79 * @version $Id: 9b6a5b2897e06cef755d08d7cf2896f5aa84c1df $
80 * @since 0.7.7
81 * @see <a href="http://aspects.jcabi.com">http://aspects.jcabi.com/</a>
82 */
83 @Documented
84 @Retention(RetentionPolicy.RUNTIME)
85 @Target(ElementType.METHOD)
86 public @interface Cacheable {
87
88 /**
89 * Lifetime of an object in cache, in time units.
90 */
91 int lifetime() default 1;
92
93 /**
94 * Time units of object lifetime.
95 *
96 * <p>The minimum unit you can use is a second. We simply can't cache for
97 * less than a second, because cache is being cleaned every second.
98 */
99 TimeUnit unit() default TimeUnit.MINUTES;
100
101 /**
102 * Keep in cache forever.
103 */
104 boolean forever() default false;
105
106 /**
107 * Returns the current store after the expiration, and
108 * then asynchronously update the data.
109 */
110 boolean asyncUpdate() default false;
111
112 /**
113 * Before-flushing trigger(s).
114 *
115 * <p>Before calling the method, call static method {@code flushBefore()}
116 * in this class and, according to its result, either flush or not.
117 * For example:
118 *
119 * <pre> class Foo {
120 * &#64;Cacheable(before = Foo.class)
121 * int read() {
122 * // return some number
123 * }
124 * public static boolean flushBefore() {
125 * // if TRUE is returned, flushing will happen before
126 * // the call to #read()
127 * }
128 * }</pre>
129 *
130 * @since 0.21
131 */
132 Class<?>[] before() default { };
133
134 /**
135 * After-flushing trigger(s).
136 *
137 * <p>After calling the method, call static method {@code flushAfter()}
138 * in this class and, according to its result, either flush or not.
139 * For example:
140 *
141 * <pre> class Foo {
142 * &#64;Cacheable(after = Foo.class)
143 * int read() {
144 * // return some number
145 * }
146 * public static boolean flushAfter() {
147 * // if TRUE is returned, flushing will happen after
148 * // the call to #read()
149 * }
150 * }</pre>
151 *
152 * @since 0.21
153 */
154 Class<?>[] after() default { };
155
156 /**
157 * Identifies a method that should flush all cached entities of
158 * this class/object.
159 * @since 0.7.14
160 * @deprecated It is identical to {@link Cacheable.FlushBefore}
161 */
162 @Documented
163 @Retention(RetentionPolicy.RUNTIME)
164 @Target(ElementType.METHOD)
165 @Deprecated
166 @interface Flush {
167 }
168
169 /**
170 * Identifies a method that should flush all cached entities of
171 * this class/object, before being executed.
172 * @since 0.7.18
173 */
174 @Documented
175 @Retention(RetentionPolicy.RUNTIME)
176 @Target(ElementType.METHOD)
177 @interface FlushBefore {
178 }
179
180 /**
181 * Identifies a method that should flush all cached entities of
182 * this class/object, after being executed.
183 * @since 0.7.18
184 */
185 @Documented
186 @Retention(RetentionPolicy.RUNTIME)
187 @Target(ElementType.METHOD)
188 @interface FlushAfter {
189 }
190
191 }