Java example source code file (AnnotationReader.java)

This example Java source code file (AnnotationReader.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

annotation, annotationreader, class, locatable, nullable, reflection, string

The AnnotationReader.java Java example source code

/*
 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.bind.v2.model.annotation;

import java.lang.annotation.Annotation;
import java.lang.reflect.Field;
import java.lang.reflect.Method;

import com.sun.istack.internal.Nullable;
import com.sun.xml.internal.bind.v2.model.core.ErrorHandler;

/**
 * Reads annotations for the given property.
 *
 * <p>
 * This is the lowest abstraction that encapsulates the difference
 * between reading inline annotations and external binding files.
 *
 * <p>
 * Because the former operates on a {@link Field} and {@link Method}
 * while the latter operates on a "property", the methods defined
 * on this interface takes both, and the callee gets to choose which
 * to use.
 *
 * <p>
 * Most of the get method takes {@link Locatable}, which points to
 * the place/context in which the annotation is read. The returned
 * annotation also implements {@link Locatable} (so that it can
 * point to the place where the annotation is placed), and its
 * {@link Locatable#getUpstream()} will return the given
 * {@link Locatable}.
 *
 *
 * <p>
 * Errors found during reading annotations are reported through the error handler.
 * A valid {@link ErrorHandler} must be registered before the {@link AnnotationReader}
 * is used.
 *
 * @author Kohsuke Kawaguchi (kk@kohsuke.org)
 */
public interface AnnotationReader<T,C,F,M> {

    /**
     * Sets the error handler that receives errors found
     * during reading annotations.
     *
     * @param errorHandler
     *      must not be null.
     */
    void setErrorHandler(ErrorHandler errorHandler);

    /**
     * Reads an annotation on a property that consists of a field.
     */
    <A extends Annotation> A getFieldAnnotation(Class annotation,
                                                F field, Locatable srcpos);

    /**
     * Checks if the given field has an annotation.
     */
    boolean hasFieldAnnotation(Class<? extends Annotation> annotationType, F field);

    /**
     * Checks if a class has the annotation.
     */
    boolean hasClassAnnotation(C clazz, Class<? extends Annotation> annotationType);

    /**
     * Gets all the annotations on a field.
     */
    Annotation[] getAllFieldAnnotations(F field, Locatable srcPos);

    /**
     * Reads an annotation on a property that consists of a getter and a setter.
     *
     */
    <A extends Annotation> A getMethodAnnotation(Class annotation,
                                                 M getter, M setter, Locatable srcpos);

    /**
     * Checks if the given method has an annotation.
     */
    boolean hasMethodAnnotation(Class<? extends Annotation> annotation, String propertyName, M getter, M setter, Locatable srcPos);

    /**
     * Gets all the annotations on a method.
     *
     * @param srcPos
     *      the location from which this annotation is read.
     */
    Annotation[] getAllMethodAnnotations(M method, Locatable srcPos);

    // TODO: we do need this to read certain annotations,
    // but that shows inconsistency wrt the spec. consult the spec team about the abstraction.
    <A extends Annotation> A getMethodAnnotation(Class annotation, M method, Locatable srcpos );

    boolean hasMethodAnnotation(Class<? extends Annotation> annotation, M method );

    /**
     * Reads an annotation on a parameter of the method.
     *
     * @return null
     *      if the annotation was not found.
     */
    @Nullable
    <A extends Annotation> A getMethodParameterAnnotation(
            Class<A> annotation, M method, int paramIndex, Locatable srcPos );

    /**
     * Reads an annotation on a class.
     */
    @Nullable
    <A extends Annotation> A getClassAnnotation(Class annotation, C clazz, Locatable srcpos) ;

    /**
     * Reads an annotation on the package that the given class belongs to.
     */
    @Nullable
    <A extends Annotation> A getPackageAnnotation(Class annotation, C clazz, Locatable srcpos);

    /**
     * Reads a value of an annotation that returns a Class object.
     *
     * <p>
     * Depending on the underlying reflection library, you can't always
     * obtain the {@link Class} object directly (see the Annotation Processing MirrorTypeException
     * for example), so use this method to avoid that.
     *
     * @param name
     *      The name of the annotation parameter to be read.
     */
    T getClassValue( Annotation a, String name );

    /**
     * Similar to {@link #getClassValue(Annotation, String)} method but
     * obtains an array parameter.
     */
    T[] getClassArrayValue( Annotation a, String name );
}