1 /* This file is part of the aspect4log project.
2 This program is free software; you can redistribute it and/or
3 modify it under the terms of the GNU Lesser General Public License
4 as published by the Free Software Foundation; version 2.1
5 of the License.
6 This program is distributed in the hope that it will be useful,
7 but WITHOUT ANY WARRANTY; without even the implied warranty of
8 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9 GNU Lesser General Public License for more details.
10 You should have received a copy of the GNU Lesser General Public License
11 along with this program; if not, write to the Free Software
12 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
13
14 Copyright 2007-2014 Semochkin Vitaliy Evgenevich aka Yilativs
15
16 */
17
18 package net.sf.aspect4log;
19
20 import java.lang.annotation.ElementType;
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 import java.lang.annotation.Target;
24
25 /**
26 *
27 * This annotation defines logging rules on method, constructor or on the entire class.
28 *
29 * Annotation placed on constructor/method overrides all values of annotation placed on class.
30 *
31 * @author Vitaliy S <a href="mailto:vitaliy.se@gmail.com">
32 *
33 */
34 @Retention(RetentionPolicy.RUNTIME)
35 @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR })
36 public @interface Log {
37
38 public enum Level {
39 NONE, TRACE, DEBUG, INFO, WARN, ERROR
40 }
41
42 /**
43 * Allows to specify {@link Level} and exceptionTemplate to apply for a given group of exceptions.
44 */
45 @Target(ElementType.ANNOTATION_TYPE)
46 public @interface Exceptions {
47 public static final String EXCEPTION_DEFAULT_TEMPLATE = "${exception}";
48
49 /**
50 *
51 * @return {@link Level} to apply for a given group of exceptions
52 */
53 Level level() default Level.ERROR;
54
55 /**
56 * A group of exceptions.
57 *
58 * @return
59 */
60 Class<? extends Throwable>[] exceptions() default { Exception.class };
61
62 /**
63 * @return true if printing stack trace is needed
64 */
65 boolean stackTrace() default true;
66
67 /**
68 * default value is $exception
69 *
70 * @return $exception
71 */
72 String template() default EXCEPTION_DEFAULT_TEMPLATE;
73 }
74
75 public static final String ARGUMENTS_DEFAULT_TEMPLATE = "${args}";
76 public static final String RESULT_DEFAULT_TEMPLATE = "${result}";
77
78 /**
79 * @return {@link Level} to use on method enter
80 */
81 Level enterLevel() default Level.DEBUG;
82
83 /**
84 * WARNING: making exitLevel smaller than enterLevel can make the log hard to read.
85 *
86 * @return {@link Level} to use on successful method exit.
87 *
88 */
89 Level exitLevel() default Level.DEBUG;
90
91 /**
92 * @return an array of {@link Exceptions} that defines how exit on different exceptions is logged. For each exception it is possible to specify by default all runtime exceptions print a stack trace, all checked exception do not print a stack trace.
93 */
94 Exceptions[] on() default { @Exceptions(level = Level.ERROR, exceptions = { RuntimeException.class }, stackTrace = true),
95 @Exceptions(level = Level.WARN, exceptions = { Exception.class }, stackTrace = false) };
96
97 /**
98 * specifies template for logging arguments
99 * by default it is ${args} which means all arguments are logged.
100 * you can write it yourself by referencing to arguments by index. E.g ${args[0]},${args[1]} etc..
101 * @return arguments template
102 */
103 String argumentsTemplate() default ARGUMENTS_DEFAULT_TEMPLATE;
104
105 /**
106 *
107 * @return A pattern representing value returned from the method. The default value it is $result.
108 */
109 String resultTemplate() default RESULT_DEFAULT_TEMPLATE;
110
111 /**
112 * @return true if indent is needed, returns false otherwise.
113 *
114 * NOTE: You may consider not to use indent in case the method level in stack trace will be too high, or in case you log recursive method.
115 */
116 boolean indent() default true;
117
118 /**
119 *
120 * @return if specified will be set as MDC key.
121 *
122 * NOTE: The typical use case for mdc key is identification method (e.g. in a filter). The typical key will be user's login.
123 *
124 */
125 String mdcKey() default "";
126
127 /**
128 *
129 * @return An mdc patter. Can be any expression using $args bean
130 */
131 String mdcTemplate() default "";
132
133 }