1 /**
2 * Redistribution and use of this software and associated documentation ("Software"), with or
3 * without modification, are permitted provided that the following conditions are met:
4 *
5 * 1. Redistributions of source code must retain copyright statements and notices. Redistributions
6 * must also contain a copy of this document.
7 *
8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
9 * conditions and the following disclaimer in the documentation and/or other materials provided with
10 * the distribution.
11 *
12 * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software
13 * without prior written permission of Intalio, Inc. For written permission, please contact
14 * info@exolab.org.
15 *
16 * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in
17 * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of
18 * Intalio, Inc.
19 *
20 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
21 *
22 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR
23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
24 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS
25 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
29 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 *
31 * Copyright 1999-2002 (C) Intalio, Inc. All Rights Reserved.
32 */
33 package org.exolab.javasource;
34
35 /**
36 * Defines methods for manipulating annotations held against various program code elements, such as
37 * classes, fields, methods etc. This interface is similar to the java.lang.reflect.AnnotatedElement
38 * except that it also allows modifications of associated annotations. It is implemented by the
39 * classes within this package that represent applicable code elements.
40 * <p>
41 * Adding the class annotations
42 *
43 * <pre>
44 * JClass lollipop = new JClass("Lollipop");
45 * JAnnotationType endorsersType = new JAnnotationType("Endorsers");
46 * JAnnotation endorsers = new JAnnotation(endorsersType);
47 * endorsers.setValue(new String[] {"\"Children\"", "\"Unscrupulous dentists\""});
48 * lollipop.addAnnotation(endorsers);
49 * </pre>
50 *
51 * outputs
52 *
53 * <pre>
54 * @Endorsers({"Children", "Unscrupulous dentists"})
55 * public class Lollipop {
56 * }
57 * </pre>
58 *
59 * Adding the method annotations
60 *
61 * <pre>
62 * JClass timeMachine = new JClass("TimeMachine");
63 * JAnnotationType requestType = new JAnnotationType("RequestForEnhancement");
64 * JAnnotation request = new JAnnotation(requestType);
65 * request.setElementValue("id", "2868724");
66 * request.setElementValue("synopsis", "\"Provide time-travel functionality\"");
67 * request.setElementValue("engineer", "\"Mr. Peabody\"");
68 * request.setElementValue("date", "\"4/1/2004\"");
69 * JMethod travelThroughTime = new JMethod(null, "travelThroughTime");
70 * travelThroughTime.addAnnotation(request);
71 * travelThroughTime.addParameter(new JParameter(new JClass("Date"), "date"));
72 * timeMachine.addMethod(travelThroughTime);
73 * </pre>
74 *
75 * outputs
76 *
77 * <pre>
78 * @RequestForEnhancement(id = 2868724, synopsis = "Provide time-travel functionality",
79 * engineer = "Mr. Peabody", date = "4/1/2004")
80 * public void travelThroughTime(Date date) {}
81 * </pre>
82 *
83 * Adding the field annotations
84 *
85 * <pre>
86 * JClass timeMachine = new JClass("EventProducer");
87 * JAnnotationType suppressWarningsType = new JAnnotationType("SuppressWarnings");
88 * JAnnotation suppressWarnings = new JAnnotation(suppressWarningsType);
89 * JField field = new JField(new JClass("DocumentHandler"), "documentHandler");
90 * field.addAnnotation(suppressWarnings);
91 * timeMachine.addField(field);
92 * </pre>
93 *
94 * outputs
95 *
96 * <pre>
97 * @SuppressWarnings()
98 * private DocumentHandler documentHandler;
99 * </pre>
100 *
101 * @author <a href="mailto:andrew DOT fawcett AT coda DOTcom">Andrew Fawcett</a>
102 * @version $Revision$ $Date: 2006-04-25 16:09:10 -0600 (Tue, 25 Apr 2006) $
103 */
104 public interface JAnnotatedElement {
105 // --------------------------------------------------------------------------
106
107 /**
108 * Retrieves a JAnnotation for the given JAnnotationType, returns null if no annotation has been
109 * set.
110 *
111 * @param annotationType Annotation type to retrieve.
112 * @return A JAnnotation for the given JAnnotationType.
113 */
114 JAnnotation getAnnotation(JAnnotationType annotationType);
115
116 /**
117 * Returns a list of JAnnotation's already set on this source element.
118 *
119 * @return A list of all JAnnotations associated with this source element.
120 */
121 JAnnotation[] getAnnotations();
122
123 /**
124 * Returns true if a JAnnotation exists for the given JAnnotationType.
125 *
126 * @param annotationType Annotation type to check for presence or absense.
127 * @return True if a JAnnotation has been added for the given JAnnotationType.
128 */
129 boolean isAnnotationPresent(JAnnotationType annotationType);
130
131 /**
132 * Adds a JAnnotation to this source element. An IllegalArgumentException is thrown if one already
133 * exists for the associated JAnnotationType.
134 *
135 * @param annotation A JAnnotation to add to this source element.
136 */
137 void addAnnotation(JAnnotation annotation);
138
139 /**
140 * Removes the JAnnotation from this source element for the given JAnnotationType. An
141 * IllegalArgumentException is thrown if the provided JAnnotation isn't present.
142 *
143 * @param annotationType Annotation type to remove.
144 * @return The JAnnotation that was associated with this source element.
145 */
146 JAnnotation removeAnnotation(JAnnotationType annotationType);
147
148 /**
149 * Returns true if this source element has any annotations.
150 *
151 * @return Returns true if this source element has any annotations.
152 */
153 boolean hasAnnotations();
154
155 // --------------------------------------------------------------------------
156 }