1 /*
2 * Copyright 2007-2013 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 */
30 @Retention(RetentionPolicy.RUNTIME)
31 @Documented
32 @Target({ElementType.FIELD, ElementType.METHOD})
33 public @interface MessageParam
34 {
35 /**
36 * The index of the place holder in the message text the field provides
37 * information for. The index is zero based.
38 * <p>
39 * If the index is not sufficient, because there is a certain property within
40 * the referenced entity/value object, an <a href="http://commons.apache.org/proper/commons-ognl/">OGNL</a>
41 * (Object-Graph Navigation Language) expression is added to access a particular value. The basic
42 * syntax for this is
43 * </p>
44 * <p>
45 * {@markupSource "Syntax: Index with OGNL expression"
46 * <code>index:ognl-expression</code>}
47 * </p>
48 * <p>
49 * {@markupExample "Index with OGNL Expression"
50 * <code>1:user.name</code>}
51 * <p>
52 * Here we show some examples on how this annotation is used.
53 * </p>
54 * <p>
55 * <b>Example 1</b>
56 * </p>
57 * <p>
58 * You want to include the value of a property. {@example
59 * "Annotation: Index without OGNL Path" {@annotation MessageParam("0")}
60 * protected final String name; {@annotation MessageParam("1")} protected
61 * final String description;}
62 * </p>
63 * <p>
64 * {@markupSource "Message bundle content" msgX=For ''{0}''
65 * this is the description: {1}}
66 * </p>
67 * <p>
68 * The placeholder at index zero (<code>0</code>) is replaced by the name the
69 * placeholder at index one (<code>1</code>) is replaced by the description.
70 * </p>
71 * <p>
72 * <b>Example 2</b>
73 * </p>
74 * <p>
75 * You want to display the canonical name of a referenced class.
76 * </p>
77 * <p>
78 * {@example "Annotation: Index and OGNL Path"
79 * {@annotation MessageParam("0:canonicalName")}
80 * protected final Class<?> clazz;}
81 * </p>
82 * <p>
83 * {@markupSource "Message bundle content"
84 * msgY=The class with name '' 0\}'' cannot be found.}
85 * </p>
86 * <p>
87 * The placeholder at index zero (<code>0</code>) is replaced by the
88 * {@link Class#getCanonicalName() canonical name} of the referenced class.
89 * </p>
90 * <p>
91 * <b>Example 3</b>
92 * </p>
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 * <p>
98 * {@example "Annotation: Several Properties"
99 * {@annotation MessageParam("0:user.name,2:user.id,3:description")}
100 * protected final Context context;
101 * {@annotation MessageParam("1")}
102 * protected final Date date;}
103 * </p>
104 * <p>
105 * {@markupSource "Message bundle content"
106 * msgZ= {1,date} at {1,time}: For user ''{0}'' (ID={2}) this is the description: {3}}
107 * </p>
108 * <p>
109 * This uses the user's <code>name</code> for the placeholder with index
110 * <code>0</code>, the identifier (<code>id</code>) of the user at index
111 * <code>2</code> and the descriptive text of the context (
112 * <code>description</code>) at index <code>3</code>. The <code>Context</code>
113 * class in this example provides a property <code>user</code> and
114 * <code>description</code>, the user provides the properties
115 * <code>name</code> and <code>id</code>. The date provides information for
116 * index <code>1</code> to show that the indices of several message parameters
117 * are not required to be consecutive.
118 * </p>
119 */
120 String value() default "";
121 }