Author: gavin.king(a)jboss.com Date: 2009-10-28 23:33:05 -0400 (Wed, 28 Oct 2009) New Revision: 4372 Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Annotated.java Log: doc Annotated Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Annotated.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Annotated.java 2009-10-29 03:32:40 UTC (rev 4371) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Annotated.java 2009-10-29 03:33:05 UTC (rev 4372) @@ -18,17 +18,26 @@ package javax.enterprise.inject.spi; import java.lang.annotation.Annotation; -import java.lang.reflect.AnnotatedElement; import java.lang.reflect.Type; import java.util.Set; /** - * The metadata for an annotated element which can be parsed by the - * {@link BeanManager}. + * <p>Represents an annotated program element.<p> * - * The semantics are similar to {@link AnnotatedElement}. + * <p>A portable extension may provide an alternative metadata + * source, such as configuration by XML. <tt>Annotated</tt> + * and its subtypes allow a portable extension to specify + * metadata that overrides the annotations that exist on a + * bean class. The portable extension is responsible for + * implementing the interfaces, thereby exposing the metadata + * to the container. The container must use the operations of + * <tt>Annotated</tt> and its subinterfaces to discover program + * element types and annotations, instead of directly calling the + * Java Reflection API.</p> * + * @see java.lang.reflect.AnnotatedElement. * + * @author Gavin King * @author Pete Muir * @author Clint Popetz * @@ -37,43 +46,46 @@ { /** - * Get the type of the annotated element + * <p>Get the type of the annotated program element.</p> * - * @return the type + * @return the type of the annotated program element */ public Type getBaseType(); /** - * Get all types the base type should be considered assignable to + * <p>Get all types to which the base type should be considered + * assignable.</p> * - * @return a set of types the base type should be considered assignable to + * @return a set of all types to which the base type should be considered + * assignable */ public Set<Type> getTypeClosure(); /** - * Get the annotation instance on the annotated element for a given annotation - * type. + * <p>Get program element annotation of a certain annotation type.</p> * * @param <T> the type of the annotation - * @param annotationType the class object of the annotation type - * @return the annotation instance, or null if no annotation is present for - * the given annotationType + * @param annotationType the class of the annotation type + * @return the program element annotation of the given annotation type, + * or a null value */ public <T extends Annotation> T getAnnotation(Class<T> annotationType); /** - * Get all the annotation instances on the annotated element + * <p>Get all annotations of the program element.</p> * - * @return the annotation instances, or an empty set if no annotations are - * present + * @return all annotations of the program element, or an empty set if no + * annotations are present */ public Set<Annotation> getAnnotations(); /** - * Determine if an annotation is present on the annotated element + * <p>Determine if the program element has an annotation of a + * certain annotation type.<p> * * @param annotationType the annotation type to check for - * @return true if the annotation is present + * @return <tt>true</tt> if the program element has an annotation of the + * given annotation type, or <tt>false</tt> otherwise */ public boolean isAnnotationPresent(Class<? extends Annotation> annotationType); }