1 /*
2 * Copyright 2007-2011 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.exceptions.i18n.message;
17
18 import java.lang.annotation.Documented;
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23
24 /**
25 * Adds information to a field of the parent exception about which parameter in
26 * a message it provides information. This way the attributes (properties)
27 * 'message' and (more important) cause can be accessed to provide information
28 * for a place holder in a message template.
29 *
30 * @see MessageParam
31 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
32 * @version $Revision$
33 */
34 @Retention(RetentionPolicy.RUNTIME)
35 @Documented
36 @Target(ElementType.TYPE)
37 public @interface ParentMessageParam
38 {
39 /**
40 * The index of the place holder in the message text the field provides
41 * information for.
42 * <p>
43 * If the index is not the same for every message text, use
44 * <ul>
45 * <li>{@link #headerParamIndex()}</li>
46 * <li>{@link #summaryParamIndex()}</li>
47 * <li>{@link #detailsParamIndex()}</li>
48 * <li>{@link #implicationsParamIndex()}</li>
49 * <li>{@link #todoParamIndex()}</li>
50 * <li>{@link #urlParamIndex()}</li>
51 * </ul>
52 * to override this index.
53 * <p>
54 * If the index is not sufficient, because there is a certain property within
55 * the referenced entity, an <a
56 * href="http://www.opensymphony.com/ognl/">OGNL</a> (Object-Graph Navigation
57 * Language may be added to access a particular value.
58 * <p>
59 * {@markupSource "Syntax"
60 * <code>property=index:ognl-path</code>}
61 * <p>
62 * {@markupExample "Example" <code>cause=1:message</code>}
63 * <p>
64 * If several properties of a referenced entity are to be displayed at
65 * different indices, separate them by commas and the information for
66 * different properties separate by colons (<code>;</code>).
67 * <p>
68 * {@markupExample "Example"
69 * <code><b>cause</b>=1:message,3:message,4:localizedMessage; <b>message</b>=5</code>}
70 * <p>
71 * <b>Example 1</b>
72 * <p>
73 * {@example {@annotation ParentMessageParam("cause=0:message")} public class
74 * MethodAccessConfigurationException extends
75 * PropertyAccessConfigurationException}
76 * <p>
77 * The parent property <code>cause</code> provides the information for
78 * placeholder <code>1</code> by the throwable's <code>message</code> text.
79 * <p>
80 * <b>Example 2</b>
81 * <p>
82 * {@example {@annotation ParentMessageParam(
83 * "cause=1:message,3:message,4:localizedMessage; message=5")} public class
84 * ExampleException extends AbstractLocalizedRuntimeException}
85 * <p>
86 * The parent property <code>{@link Throwable#getCause() cause}</code>
87 * provides the information (
88 * <code>{@link Throwable#getMessage() message}</code>) for placeholder
89 * <code>1</code> and <code>3</code> (just to show how the same information
90 * can be used for different placeholders), the
91 * <code>{@link Throwable#getLocalizedMessage() localizedMessage}</code>
92 * provides information for placeholder <code>4</code> and the parent's
93 * <code>{@link Throwable#getMessage() message}</code> is used to supply a
94 * value for placeholder <code>5</code>.
95 *
96 * @return the index of the parameter in the message text.
97 */
98 String value() default "";
99
100 /**
101 * The index of the place holder in the header message text the field provides
102 * information for.
103 *
104 * @return the index of the parameter in the header message text.
105 */
106 String headerParamIndex() default "";
107
108 /**
109 * The index of the place holder in the summary message text the field
110 * provides information for.
111 *
112 * @return the index of the parameter in the summary message text.
113 */
114 String summaryParamIndex() default "";
115
116 /**
117 * The index of the place holder in the details message text the field
118 * provides information for.
119 *
120 * @return the index of the parameter in the details message text.
121 */
122 String detailsParamIndex() default "";
123
124 /**
125 * The index of the place holder in the implications message text the field
126 * provides information for.
127 *
128 * @return the index of the parameter in the implications message text.
129 */
130 String implicationsParamIndex() default "";
131
132 /**
133 * The index of the place holder in the todo message text the field provides
134 * information for.
135 *
136 * @return the index of the parameter in the todo message text.
137 */
138 String todoParamIndex() default "";
139
140 /**
141 * The index of the place holder in the URL message text the field provides
142 * information for.
143 *
144 * @return the index of the parameter in the URL message text.
145 */
146 String urlParamIndex() default "";
147 }