Debian Codegraph @

src/main/java/com/jcabi/aspects/Loggable.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 loggable via {@link com.jcabi.log.Logger}.
41 *
42 * <p>For example, this {@code load()} method produces a log line
43 * on every call:
44 *
45 * <pre> &#64;Loggable
46 * String load(String resource) throws IOException {
47 * return "something";
48 * }</pre>
49 *
50 * <p>You can configure the level of logging:
51 *
52 * <pre> &#64;Loggable(Loggable.DEBUG)
53 * void save(String resource) throws IOException {
54 * // do something
55 * }</pre>
56 *
57 * <p>Since version 0.7.6, you can specify a maximum execution time limit for
58 * a method. If such a limit is reached a logging message will be issued with
59 * a {@code WARN} priority. It is a very convenient mechanism for profiling
60 * applications in production. Default value of a limit is 1 second.
61 *
62 * <pre> &#64;Loggable(limit = 2)
63 * void save(String resource) throws IOException {
64 * // do something, potentially slow
65 * }</pre>
66 *
67 * <p>Since version 0.7.14 you can change the time unit for the "limit"
68 * parameter. Default unit of measurement is a second:
69 *
70 * <pre> &#64;Loggable(limit = 200, unit = TimeUnit.MILLISECONDS)
71 * void save(String resource) throws IOException {
72 * // do something, potentially slow
73 * }</pre>
74 *
75 * <p>Since version 0.7.17 you can ignore certain exception types, and they
76 * won't be logged when thrown. It is very useful when exceptions are used
77 * to control flow (which is not a good practice, but is still used in
78 * some frameworks, for example in JAX-RS):
79 *
80 * <pre> &#64;Loggable(ignore = WebApplicationException.class)
81 * String get() {
82 * if (not_logged_in()) {
83 * throw new WebApplicationException(forward_to_login_page());
84 * }
85 * }</pre>
86 *
87 * <p>Since version 0.8 you can mark some exceptions as "always to be ignored",
88 * using {@link Loggable.Quiet} annotation.
89 *
90 * @author Yegor Bugayenko ([email protected])
91 * @version $Id: c0749e358584fba5ebcd8af97d7b6ab09faba80e $
92 * @since 0.7.2
93 * @see com.jcabi.log.Logger
94 * @see <a href="http://aspects.jcabi.com">http://aspects.jcabi.com/</a>
95 * @see <a href="http://www.yegor256.com/2014/06/01/aop-aspectj-java-method-logging.html">Java Method Logging with AOP and Annotations, by Yegor Bugayenko</a>
96 */
97 @Documented
98 @Retention(RetentionPolicy.RUNTIME)
99 @Target({ ElementType.METHOD, ElementType.TYPE })
100 @SuppressWarnings({
101 "PMD.VariableNamingConventions", "PMD.RedundantFieldInitializer"
102 })
103 public @interface Loggable {
104
105 /**
106 * TRACE level of logging.
107 */
108 int TRACE = 0;
109
110 /**
111 * DEBUG level of logging.
112 */
113 int DEBUG = 1;
114
115 /**
116 * INFO level of logging.
117 */
118 int INFO = 2;
119
120 /**
121 * WARN level of logging.
122 */
123 int WARN = 3;
124
125 /**
126 * ERROR level of logging.
127 */
128 int ERROR = 4;
129
130 /**
131 * Level of logging.
132 */
133 int value() default Loggable.INFO;
134
135 /**
136 * Maximum amount allowed for this method (a warning will be
137 * issued if it takes longer).
138 * @since 0.7.6
139 */
140 int limit() default 1;
141
142 /**
143 * Time unit for the limit.
144 * @since 0.7.14
145 */
146 TimeUnit unit() default TimeUnit.MINUTES;
147
148 /**
149 * Shall we trim long texts in order to make log lines more readable?
150 * @since 0.7.13
151 */
152 boolean trim() default true;
153
154 /**
155 * Method entry moment should be reported as well (by default only
156 * an exit moment is reported).
157 * @since 0.7.16
158 */
159 boolean prepend() default false;
160
161 /**
162 * List of exception types, which should not be logged if thrown.
163 *
164 * <p>You can also mark some exception types as "always to be ignored",
165 * using {@link Loggable.Quiet} annotation.
166 *
167 * @since 0.7.17
168 */
169 Class<? extends Throwable>[] ignore() default { };
170
171 /**
172 * Skip logging of result, replacing it with dots?
173 * @since 0.7.19
174 */
175 boolean skipResult() default false;
176
177 /**
178 * Skip logging of arguments, replacing them all with dots?
179 * @since 0.7.19
180 */
181 boolean skipArgs() default false;
182
183 /**
184 * Add toString() result to log line.
185 * @since 0.8.1
186 */
187 boolean logThis() default false;
188
189 /**
190 * The precision (number of fractional digits) to be used when displaying
191 * the measured execution time.
192 * @since 0.18
193 */
194 int precision() default 2;
195
196 /**
197 * The name of the logger to be used. If not specified, defaults to the
198 * class name of the annotated class or method.
199 * @since 0.18
200 */
201 String name() default "";
202
203 /**
204 * Identifies an exception that is never logged by {@link Loggable} if/when
205 * being thrown out of an annotated method.
206 *
207 * <p>Sometimes exceptions are used as flow control instruments (although
208 * this may be considered as a bad practice in most casts). In such
209 * situations we don't want to flood log console with error messages. One
210 * of the options is to use {@link Loggable#ignore()} attribute to list
211 * all exception types that should be ignored. However, this
212 * {@link Loggable.Quiet} annotation is more convenient when we want to
213 * ignore one specific exception type in all situations.
214 *
215 * @since 0.8
216 */
217 @Documented
218 @Retention(RetentionPolicy.RUNTIME)
219 @Target(ElementType.TYPE)
220 public @interface Quiet {
221 }
222
223 }