001 /*
002 * Copyright 2003-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang.reflect;
027
028 import java.lang.annotation.Annotation;
029
030 /**
031 * Represents an annotated element of the program currently running in this
032 * VM. This interface allows annotations to be read reflectively. All
033 * annotations returned by methods in this interface are immutable and
034 * serializable. It is permissible for the caller to modify the
035 * arrays returned by accessors for array-valued enum members; it will
036 * have no affect on the arrays returned to other callers.
037 *
038 * <p>If an annotation returned by a method in this interface contains
039 * (directly or indirectly) a {@link Class}-valued member referring to
040 * a class that is not accessible in this VM, attempting to read the class
041 * by calling the relevant Class-returning method on the returned annotation
042 * will result in a {@link TypeNotPresentException}.
043 *
044 * <p>Similarly, attempting to read an enum-valued member will result in
045 * a {@link EnumConstantNotPresentException} if the enum constant in the
046 * annotation is no longer present in the enum type.
047 *
048 * <p>Finally, Attempting to read a member whose definition has evolved
049 * incompatibly will result in a {@link
050 * java.lang.annotation.AnnotationTypeMismatchException} or an
051 * {@link java.lang.annotation.IncompleteAnnotationException}.
052 *
053 * @since 1.5
054 * @author Josh Bloch
055 */
056 public interface AnnotatedElement {
057 /**
058 * Returns true if an annotation for the specified type
059 * is present on this element, else false. This method
060 * is designed primarily for convenient access to marker annotations.
061 *
062 * @param annotationClass the Class object corresponding to the
063 * annotation type
064 * @return true if an annotation for the specified annotation
065 * type is present on this element, else false
066 * @throws NullPointerException if the given annotation class is null
067 * @since 1.5
068 */
069 boolean isAnnotationPresent(
070 Class<? extends Annotation> annotationClass);
071
072 /**
073 * Returns this element's annotation for the specified type if
074 * such an annotation is present, else null.
075 *
076 * @param annotationClass the Class object corresponding to the
077 * annotation type
078 * @return this element's annotation for the specified annotation type if
079 * present on this element, else null
080 * @throws NullPointerException if the given annotation class is null
081 * @since 1.5
082 */
083 <T extends Annotation> T getAnnotation(Class<T> annotationClass);
084
085 /**
086 * Returns all annotations present on this element. (Returns an array
087 * of length zero if this element has no annotations.) The caller of
088 * this method is free to modify the returned array; it will have no
089 * effect on the arrays returned to other callers.
090 *
091 * @return all annotations present on this element
092 * @since 1.5
093 */
094 Annotation[] getAnnotations();
095
096 /**
097 * Returns all annotations that are directly present on this
098 * element. Unlike the other methods in this interface, this method
099 * ignores inherited annotations. (Returns an array of length zero if
100 * no annotations are directly present on this element.) The caller of
101 * this method is free to modify the returned array; it will have no
102 * effect on the arrays returned to other callers.
103 *
104 * @return All annotations directly present on this element
105 * @since 1.5
106 */
107 Annotation[] getDeclaredAnnotations();
108 }
|