001: /**
002: * Redistribution and use of this software and associated documentation
003: * ("Software"), with or without modification, are permitted provided
004: * that the following conditions are met:
005: *
006: * 1. Redistributions of source code must retain copyright
007: * statements and notices. Redistributions must also contain a
008: * copy of this document.
009: *
010: * 2. Redistributions in binary form must reproduce the
011: * above copyright notice, this list of conditions and the
012: * following disclaimer in the documentation and/or other
013: * materials provided with the distribution.
014: *
015: * 3. The name "Exolab" must not be used to endorse or promote
016: * products derived from this Software without prior written
017: * permission of Intalio, Inc. For written permission,
018: * please contact info@exolab.org.
019: *
020: * 4. Products derived from this Software may not be called "Exolab"
021: * nor may "Exolab" appear in their names without prior written
022: * permission of Intalio, Inc. Exolab is a registered
023: * trademark of Intalio, Inc.
024: *
025: * 5. Due credit should be given to the Exolab Project
026: * (http://www.exolab.org/).
027: *
028: * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS
029: * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
030: * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
031: * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
032: * INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
033: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
034: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
035: * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
036: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
037: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
038: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
039: * OF THE POSSIBILITY OF SUCH DAMAGE.
040: *
041: * Copyright 1999-2002 (C) Intalio, Inc. All Rights Reserved.
042: */package org.exolab.javasource;
043:
044: /**
045: * Defines methods for manipulating annotations held against various
046: * program code elements, such as classes, fields, methods etc. This interface
047: * is similar to the java.lang.reflect.AnnotatedElement except that it also
048: * allows modifications of associated annotations. It is implemented by the
049: * classes within this package that represent applicable code elements.
050: * <p>
051: * Adding the class annotations
052: * <pre>
053: * JClass lollipop = new JClass("Lollipop");
054: * JAnnotationType endorsersType = new JAnnotationType("Endorsers");
055: * JAnnotation endorsers = new JAnnotation(endorsersType);
056: * endorsers.setValue(new String[] { "\"Children\"", "\"Unscrupulous dentists\""});
057: * lollipop.addAnnotation(endorsers);
058: * </pre>
059: * outputs
060: * <pre>
061: * @Endorsers(
062: * {
063: * "Children",
064: * "Unscrupulous dentists"
065: * })
066: * public class Lollipop {
067: * }
068: * </pre>
069: * Adding the method annotations
070: * <pre>
071: * JClass timeMachine = new JClass("TimeMachine");
072: * JAnnotationType requestType = new JAnnotationType("RequestForEnhancement");
073: * JAnnotation request = new JAnnotation(requestType);
074: * request.setElementValue("id", "2868724");
075: * request.setElementValue("synopsis", "\"Provide time-travel functionality\"");
076: * request.setElementValue("engineer", "\"Mr. Peabody\"");
077: * request.setElementValue("date", "\"4/1/2004\"");
078: * JMethod travelThroughTime = new JMethod(null, "travelThroughTime");
079: * travelThroughTime.addAnnotation(request);
080: * travelThroughTime.addParameter(new JParameter(new JClass("Date"), "date"));
081: * timeMachine.addMethod(travelThroughTime);
082: * </pre>
083: * outputs
084: * <pre>
085: * @RequestForEnhancement(
086: * id = 2868724,
087: * synopsis = "Provide time-travel functionality",
088: * engineer = "Mr. Peabody",
089: * date = "4/1/2004")
090: * public void travelThroughTime(Date date)
091: * {
092: * }
093: * </pre>
094: * Adding the field annotations
095: * <pre>
096: * JClass timeMachine = new JClass("EventProducer");
097: * JAnnotationType suppressWarningsType = new JAnnotationType("SuppressWarnings");
098: * JAnnotation suppressWarnings = new JAnnotation(suppressWarningsType);
099: * JField field = new JField(new JClass("DocumentHandler"), "documentHandler");
100: * field.addAnnotation(suppressWarnings);
101: * timeMachine.addField(field);
102: * </pre>
103: * outputs
104: * <pre>
105: * @SuppressWarnings()
106: * private DocumentHandler documentHandler;
107: * </pre>
108: *
109: * @author <a href="mailto:andrew DOT fawcett AT coda DOTcom">Andrew Fawcett</a>
110: * @version $Revision: 6669 $ $Date: 2006-04-25 16:09:10 -0600 (Tue, 25 Apr 2006) $
111: */
112: public interface JAnnotatedElement {
113: //--------------------------------------------------------------------------
114:
115: /**
116: * Retrieves a JAnnotation for the given JAnnotationType, returns null if no
117: * annotation has been set.
118: *
119: * @param annotationType Annotation type to retrieve.
120: * @return A JAnnotation for the given JAnnotationType.
121: */
122: JAnnotation getAnnotation(JAnnotationType annotationType);
123:
124: /**
125: * Returns a list of JAnnotation's already set on this source element.
126: *
127: * @return A list of all JAnnotations associated with this source element.
128: */
129: JAnnotation[] getAnnotations();
130:
131: /**
132: * Returns true if a JAnnotation exists for the given JAnnotationType.
133: *
134: * @param annotationType Annotation type to check for presence or absense.
135: * @return True if a JAnnotation has been added for the given JAnnotationType.
136: */
137: boolean isAnnotationPresent(JAnnotationType annotationType);
138:
139: /**
140: * Adds a JAnnotation to this source element. An IllegalArgumentException is
141: * thrown if one already exists for the associated JAnnotationType.
142: *
143: * @param annotation A JAnnotation to add to this source element.
144: */
145: void addAnnotation(JAnnotation annotation);
146:
147: /**
148: * Removes the JAnnotation from this source element for the given
149: * JAnnotationType. An IllegalArgumentException is thrown if the provided
150: * JAnnotation isn't present.
151: *
152: * @param annotationType Annotation type to remove.
153: * @return The JAnnotation that was associated with this source element.
154: */
155: JAnnotation removeAnnotation(JAnnotationType annotationType);
156:
157: /**
158: * Returns true if this source element has any annotations.
159: *
160: * @return Returns true if this source element has any annotations.
161: */
162: boolean hasAnnotations();
163:
164: //--------------------------------------------------------------------------
165: }
|