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 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 */
32 @Retention(RetentionPolicy.RUNTIME)
33 @Documented
34 @Target(ElementType.TYPE)
35 public @interface ParentMessageParam
36 {
37 /**
38 * The index of the place holder in the message text the field provides
39 * information for.
40 * <p>
41 * <p>
42 * If the index is not sufficient, because there is a certain property within
43 * the referenced entity, an <a
44 * href="http://www.opensymphony.com/ognl/">OGNL</a> (Object-Graph Navigation
45 * Language may be added to access a particular value.
46 * </p>
47 * <p>
48 * {@markupSource "Syntax"
49 * <code>property=index:ognl-path</code>}
50 * </p>
51 * <p>
52 * {@markupExample "Example" <code>cause=1:message</code>}
53 * </p>
54 * <p>
55 * If several properties of a referenced entity are to be displayed at
56 * different indices, separate them by commas and the information for
57 * different properties separate by colons (<code>;</code>).
58 * </p>
59 * <p>
60 * {@markupExample "Example"
61 * <code><b>cause</b>=1:message,3:message,4:localizedMessage; <b>message</b>=5</code>}
62 * </p>
63 * <p>
64 * <b>Example 1</b>
65 * </p>
66 * <p>
67 * {@example {@annotation ParentMessageParam("cause=0:message")} public class
68 * MethodAccessConfigurationException extends
69 * PropertyAccessConfigurationException}
70 * </p>
71 * <p>
72 * The parent property <code>cause</code> provides the information for
73 * placeholder <code>1</code> by the throwable's <code>message</code> text.
74 * </p>
75 * <p>
76 * <b>Example 2</b>
77 * </p>
78 * <p>
79 * {@example {@annotation ParentMessageParam(
80 * "cause=1:message,3:message,4:localizedMessage; message=5")} public class
81 * ExampleException extends AbstractLocalizedRuntimeException}
82 * </p>
83 * <p>
84 * The parent property <code>{@link Throwable#getCause() cause}</code>
85 * provides the information (
86 * <code>{@link Throwable#getMessage() message}</code>) for placeholder
87 * <code>1</code> and <code>3</code> (just to show how the same information
88 * can be used for different placeholders), the
89 * <code>{@link Throwable#getLocalizedMessage() localizedMessage}</code>
90 * provides information for placeholder <code>4</code> and the parent's
91 * <code>{@link Throwable#getMessage() message}</code> is used to supply a
92 * value for placeholder <code>5</code>.
93 * </p>
94 */
95 String value() default "";
96 }