1 /*
2 * Copyright 2012-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.properties.api.core.annotations;
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 * Defines a set of properties.
26 * <p/>
27 * <h3>Purpose</h3>
28 * <p>
29 * All interfaces that provide access to properties are required to be annotated
30 * by this annotation.
31 * </p>
32 *
33 * <pre>
34 * {@source "Example"
35 * {@annotation}PropertySet("myprops")
36 * public interface MyProperties {
37 * ...
38 * }
39 * }
40 * </pre>
41 *
42 * <h3>Name Values</h3>
43 * <p>
44 * The name of the property set is specified as the {@link #value() value}
45 * element.
46 * </p>
47 * <p>
48 * There are two special values:
49 * </p>
50 * <ul>
51 * <li><i>empty string</i>, the keys will not be prefixed.
52 * <li><i>single space</i>, the default. In this case the fully qualified name
53 * of the annotated interface is the implicit name.</li>
54 * </ul>
55 *
56 * <pre>
57 * {@source "Example: empty string"
58 * {@annotation}PropertySet("")
59 * public interface MyProperties {
60 * ...
61 * }
62 * }
63 * </pre>
64 *
65 * <pre>
66 * {@source "Example: single space (default)"
67 * {@annotation}PropertySet
68 * public interface MyProperties {
69 * ...
70 * }
71 * }
72 * </pre>
73 <h3>Annotated Elements</h3>
74 * <p>
75 * The annotation may be placed at type or method level.
76 * </p>
77 * <h4>Type Level Annotation</h4>
78 * <p>
79 * If the annotation is given at <em>type level</em>, a new property set is
80 * defined. All properties defined in that type belong to the given set, unless
81 * there exists an explicit property set annotation on a method that overrides
82 * it.
83 * </p>
84 * <h4>Method Level Annotation</h4>
85 * <p>
86 * If the annotation is given at <em>method level</em> <strong>no new property
87 * set</strong> is defined. The annotated property is simply switched to belong
88 * to the given type. If a property set is only referenced at method level and
89 * never on type level, it is called <em>virtual property set</em>. Therefore
90 * make sure that there is at least a property set annotation at type level.
91 * </p>
92 * {@stickyNote You may only encounter the difference if you try to select the
93 * set of property sets (e.g. report generators do so). All properties
94 * associated with a virtual property set will not show up. You may use the
95 * concept if you do not want to have a report on these properties (although
96 * this may not be of any value to have properties that do not show up in the
97 * documentation).}
98 */
99 @Documented
100 @Target({ ElementType.TYPE, ElementType.METHOD })
101 @Retention(RetentionPolicy.RUNTIME)
102 public @interface PropertySet
103 {
104 /**
105 * The name of the property set.
106 * <p>
107 * There are two special values:
108 * </p>
109 * <ul>
110 * <li><i>empty string</i>, the keys will not be prefixed-
111 * <li><i>single space</i>, the default. In this case the fully qualified name
112 * of the annotated interface is the implicit name.</li>
113 * </ul>
114 */
115 String value() default " ";
116 }