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 an exception about which parameter in a
26 * message it provides information.
27 *
28 * @see ParentMessageParam
29 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
30 * @version $Revision$
31 */
32 @Retention(RetentionPolicy.RUNTIME)
33 @Documented
34 @Target(ElementType.FIELD)
35 public @interface MessageParam
36 {
37 /**
38 * The index of the place holder in the message text the field provides
39 * information for. The index is zero based.
40 * <p>
41 * If the index is not the same for every message text, use
42 * <ul>
43 * <li>{@link #headerParamIndex()}</li>
44 * <li>{@link #summaryParamIndex()}</li>
45 * <li>{@link #detailsParamIndex()}</li>
46 * <li>{@link #implicationsParamIndex()}</li>
47 * <li>{@link #todoParamIndex()}</li>
48 * <li>{@link #urlParamIndex()}</li>
49 * </ul>
50 * to override this (default) index.
51 * <p>
52 * If the index is not sufficient, because there is a certain property within
53 * the referenced entity/value object, an <a
54 * href="http://www.opensymphony.com/ognl/">OGNL</a> (Object-Graph Navigation
55 * Language) expression is added to access a particular value. The basic
56 * syntax for this is
57 * <p>
58 * {@markupSource "Syntax: Index with OGNL expression"
59 * <code>index:ognl-expression</code>}
60 * <p>
61 * {@markupExample "Index with OGNL Expression"
62 * <code>1:user.name</code>}
63 * <p>
64 * Here we show some examples on how this annotation is used.
65 * <p>
66 * <b>Example 1</b>
67 * <p>
68 * You want to include the value of a property. {@example
69 * "Annotation: Index without OGNL Path" {@annotation MessageParam("0")}
70 * protected final String name; {@annotation MessageParam("1")} protected
71 * final String description;}
72 * <p>
73 * {@markupSource "Message bundle content" msgX=For ''{0}''
74 * this is the description: {1}}
75 * <p>
76 * The placeholder at index zero (<code>0</code>) is replaced by the name the
77 * placeholder at index one (<code>1</code>) is replaced by the description.
78 * <p>
79 * <b>Example 2</b>
80 * <p>
81 * You want to display the canonical name of a referenced class.
82 * <p>
83 * {@example "Annotation: Index and OGNL Path" {@annotation
84 * MessageParam("0:canonicalName")} protected final Class<?> clazz;}
85 * <p>
86 * {@markupSource "Message bundle content" msgY=The class with
87 * name '' 0}'' cannot be found.}
88 * <p>
89 * The placeholder at index zero (<code>0</code>) is replaced by the
90 * {@link Class#getCanonicalName() canonical name} of the referenced class.
91 * <p>
92 * <b>Example 3</b>
93 * <p>
94 * If several properties of a referenced entity are to be displayed at
95 * different indices, separate them by commas.
96 * <p>
97 * {@example "Annotation: Several Properties" {@annotation
98 * MessageParam("0:user.name,2:user.id,3:description")} protected final
99 * Context context; {@annotation MessageParam("1")}
100 * protected final Date date;}
101 * <p>
102 * {@markupSource "Message bundle content" msgZ= 1,date} at
103 * {1,time}: For user ''{0}'' (ID={2}) this is the description: {3}}
104 * <p>
105 * This uses the user's <code>name</code> for the placeholder with index
106 * <code>0</code>, the identifier (<code>id</code>) of the user at index
107 * <code>2</code> and the descriptive text of the context (
108 * <code>description</code>) at index <code>3</code>. The <code>Context</code>
109 * class in this example provides a property <code>user</code> and
110 * <code>description</code>, the user provides the properties
111 * <code>name</code> and <code>id</code>. The date provides information for
112 * index <code>1</code> to show that the indices of several message parameters
113 * are not required to be consecutive.
114 *
115 * @return the index of the parameter in the message text.
116 */
117 String value() default "";
118
119 /**
120 * The index of the place holder in the header message text the field provides
121 * information for.
122 *
123 * @return the index of the parameter in the header message text.
124 */
125 String headerParamIndex() default "";
126
127 /**
128 * The index of the place holder in the summary message text the field
129 * provides information for.
130 *
131 * @return the index of the parameter in the summary message text.
132 */
133 String summaryParamIndex() default "";
134
135 /**
136 * The index of the place holder in the details message text the field
137 * provides information for.
138 *
139 * @return the index of the parameter in the details message text.
140 */
141 String detailsParamIndex() default "";
142
143 /**
144 * The index of the place holder in the implications message text the field
145 * provides information for.
146 *
147 * @return the index of the parameter in the implications message text.
148 */
149 String implicationsParamIndex() default "";
150
151 /**
152 * The index of the place holder in the todo message text the field provides
153 * information for.
154 *
155 * @return the index of the parameter in the todo message text.
156 */
157 String todoParamIndex() default "";
158
159 /**
160 * The index of the place holder in the URL message text the field provides
161 * information for.
162 *
163 * @return the index of the parameter in the URL message text.
164 */
165 String urlParamIndex() default "";
166 }