1 package net.sourceforge.jenesis4java;
2
3 /*
4 * #%L
5 * Jenesis 4 Java Code Generator
6 * %%
7 * Copyright (C) 2000 - 2015 jenesis4java
8 * %%
9 * This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation, either version 3 of the
12 * License, or (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Lesser Public License for more details.
18 *
19 * You should have received a copy of the GNU General Lesser Public
20 * License along with this program. If not, see
21 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
22 * #L%
23 */
24
25 /**
26 * Copyright (C) 2008, 2010 Richard van Nieuwenhoven - ritchie [at] gmx [dot] at
27 * Copyright (C) 2000, 2001 Paul Cody Johnston - pcj@inxar.org <br>
28 * This file is part of Jenesis4java. Jenesis4java is free software: you can
29 * redistribute it and/or modify it under the terms of the GNU Lesser General
30 * Public License as published by the Free Software Foundation, either version 3
31 * of the License, or (at your option) any later version.<br>
32 * Jenesis4java is distributed in the hope that it will be useful, but WITHOUT
33 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
34 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
35 * details.<br>
36 * You should have received a copy of the GNU Lesser General Public License
37 * along with Jenesis4java. If not, see <http://www.gnu.org/licenses/>.
38 */
39 import java.util.List;
40
41 public interface Annotation extends Codeable {
42
43 /**
44 * @deprecated Avoid using this method. Create a new
45 * {@link AnnotationAttribute} instead.
46 */
47 @Deprecated
48 Annotation addAnnotationAttribute(AnnotationAttribute annotation);
49
50 /**
51 * Creates a new {@link AnnotationAttribute} for a given attribute name, but
52 * without value. The attribute is appended at the end.
53 * <p>
54 * Note: AnnotationAttributes without value are not printed during code
55 * generation.
56 * <p>
57 * This feature is useful to create more complex annotations and to force an
58 * the order of attributes.
59 *
60 * @param attributeName
61 * The key of the annotation attribute. A {@code null} value is
62 * interpreted (and set) as an empty String.
63 * @return A new {@link AnnotationAttribute} instance with a name, but
64 * without a value.
65 */
66 AnnotationAttribute addAnnotationAttribute(String attributeName);
67
68 /**
69 * Creates a new {@link AnnotationAttribute} for a given attribute name set
70 * to a given value. The attribute is appended at the end.
71 *
72 * @param attributeName
73 * The key of the annotation attribute. A {@code null} value is
74 * interpreted (and set) as an empty String.
75 * @return A new {@link AnnotationAttribute} instance with a name, but
76 * @param value
77 * The value to which this attribute is set.
78 * @return The newly created {@link AnnotationAttribute}.
79 */
80 AnnotationAttribute addAnnotationAttribute(String attributeName, Expression value);
81
82 /**
83 * Adds a new attribute without a key and with the given expression as
84 * value. This corresponds to an annotation with only one parameter named
85 * {@code "value"}.
86 * <p>
87 * Resulting code looks like {@code @AnnotationName(value)}
88 *
89 * @param values
90 * The expressions to use as value. If none is given, no value is
91 * set. Use the appropriate setter in this case.
92 * @return A newly created {@link AnnotationAttribute} with empty key.
93 */
94 AnnotationAttribute addDefaultValueAttribute(Expression... values);
95
96 AnnotationAttribute getAnnotationAttribute(String string);
97
98 /**
99 * @return An unmodifiable list of all attributes.
100 */
101 List<AnnotationAttribute> getAnnotationAttributes();
102
103 /**
104 * Returns the actual name used for the annotation text.
105 * <p>
106 * Interface ambiguity mumbles the meaning of "text" and "name". So these
107 * are deprecated for now. In the meantime use this method to get the name
108 * effectively used as the name. The name in this context is the simple
109 * class name of the Annotation in use.
110 *
111 * @return The name that will actually be used for printing.
112 */
113 String getEffectiveName();
114
115 /**
116 * @return The value of the "name" field.
117 * @deprecated The meaning of "name" is ill-defined in this interface, use
118 * {@link #getEffectiveName()} instead.
119 */
120 @Deprecated
121 String getName();
122
123 /**
124 * Text can either be the name of the annotation (if the field "name" is
125 * undefined), or the text in the argument (if the field "name" is defined).
126 * <p>
127 * Usage of text is phased out (and "text" will be removed in a future
128 * release), so usage is strongly discouraged. Use
129 * {@link AnnotationAttribute}s instead.
130 *
131 * @return The value of the "text" field.
132 * @deprecated The meaning of "text" is ill-defined in this interface, use
133 * {@link #getEffectiveName()} to get the effective name instead
134 * and {@link #getAnnotationAttributes()} to get the attributes
135 * of this annotation..
136 */
137 @Deprecated
138 String getText();
139
140 /**
141 * @deprecated The concept of "name" and "text" is ill-defined in this
142 * class. Avoid using this method, set the appropriate name
143 * using factory methods instead.
144 */
145 @Deprecated
146 Annotation setName(String name);
147
148 /**
149 * @deprecated The concept of "name" and "text" is ill-defined in this
150 * class. Avoid using this method, set the appropriate name
151 * using factory methods instead. To set attributes, use
152 * {@link #addAnnotationAttribute(String)} instead.
153 */
154 @Deprecated
155 Annotation setText(String text);
156 }