1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/bind/v2/model/annotation/AnnotationReader.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,162 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.xml.internal.bind.v2.model.annotation;
1.30 +
1.31 +import java.lang.annotation.Annotation;
1.32 +import java.lang.reflect.Field;
1.33 +import java.lang.reflect.Method;
1.34 +
1.35 +import com.sun.istack.internal.Nullable;
1.36 +import com.sun.xml.internal.bind.v2.model.core.ErrorHandler;
1.37 +
1.38 +/**
1.39 + * Reads annotations for the given property.
1.40 + *
1.41 + * <p>
1.42 + * This is the lowest abstraction that encapsulates the difference
1.43 + * between reading inline annotations and external binding files.
1.44 + *
1.45 + * <p>
1.46 + * Because the former operates on a {@link Field} and {@link Method}
1.47 + * while the latter operates on a "property", the methods defined
1.48 + * on this interface takes both, and the callee gets to choose which
1.49 + * to use.
1.50 + *
1.51 + * <p>
1.52 + * Most of the get method takes {@link Locatable}, which points to
1.53 + * the place/context in which the annotation is read. The returned
1.54 + * annotation also implements {@link Locatable} (so that it can
1.55 + * point to the place where the annotation is placed), and its
1.56 + * {@link Locatable#getUpstream()} will return the given
1.57 + * {@link Locatable}.
1.58 + *
1.59 + *
1.60 + * <p>
1.61 + * Errors found during reading annotations are reported through the error handler.
1.62 + * A valid {@link ErrorHandler} must be registered before the {@link AnnotationReader}
1.63 + * is used.
1.64 + *
1.65 + * @author Kohsuke Kawaguchi (kk@kohsuke.org)
1.66 + */
1.67 +public interface AnnotationReader<T,C,F,M> {
1.68 +
1.69 + /**
1.70 + * Sets the error handler that receives errors found
1.71 + * during reading annotations.
1.72 + *
1.73 + * @param errorHandler
1.74 + * must not be null.
1.75 + */
1.76 + void setErrorHandler(ErrorHandler errorHandler);
1.77 +
1.78 + /**
1.79 + * Reads an annotation on a property that consists of a field.
1.80 + */
1.81 + <A extends Annotation> A getFieldAnnotation(Class<A> annotation,
1.82 + F field, Locatable srcpos);
1.83 +
1.84 + /**
1.85 + * Checks if the given field has an annotation.
1.86 + */
1.87 + boolean hasFieldAnnotation(Class<? extends Annotation> annotationType, F field);
1.88 +
1.89 + /**
1.90 + * Checks if a class has the annotation.
1.91 + */
1.92 + boolean hasClassAnnotation(C clazz, Class<? extends Annotation> annotationType);
1.93 +
1.94 + /**
1.95 + * Gets all the annotations on a field.
1.96 + */
1.97 + Annotation[] getAllFieldAnnotations(F field, Locatable srcPos);
1.98 +
1.99 + /**
1.100 + * Reads an annotation on a property that consists of a getter and a setter.
1.101 + *
1.102 + */
1.103 + <A extends Annotation> A getMethodAnnotation(Class<A> annotation,
1.104 + M getter, M setter, Locatable srcpos);
1.105 +
1.106 + /**
1.107 + * Checks if the given method has an annotation.
1.108 + */
1.109 + boolean hasMethodAnnotation(Class<? extends Annotation> annotation, String propertyName, M getter, M setter, Locatable srcPos);
1.110 +
1.111 + /**
1.112 + * Gets all the annotations on a method.
1.113 + *
1.114 + * @param srcPos
1.115 + * the location from which this annotation is read.
1.116 + */
1.117 + Annotation[] getAllMethodAnnotations(M method, Locatable srcPos);
1.118 +
1.119 + // TODO: we do need this to read certain annotations,
1.120 + // but that shows inconsistency wrt the spec. consult the spec team about the abstraction.
1.121 + <A extends Annotation> A getMethodAnnotation(Class<A> annotation, M method, Locatable srcpos );
1.122 +
1.123 + boolean hasMethodAnnotation(Class<? extends Annotation> annotation, M method );
1.124 +
1.125 + /**
1.126 + * Reads an annotation on a parameter of the method.
1.127 + *
1.128 + * @return null
1.129 + * if the annotation was not found.
1.130 + */
1.131 + @Nullable
1.132 + <A extends Annotation> A getMethodParameterAnnotation(
1.133 + Class<A> annotation, M method, int paramIndex, Locatable srcPos );
1.134 +
1.135 + /**
1.136 + * Reads an annotation on a class.
1.137 + */
1.138 + @Nullable
1.139 + <A extends Annotation> A getClassAnnotation(Class<A> annotation, C clazz, Locatable srcpos) ;
1.140 +
1.141 + /**
1.142 + * Reads an annotation on the package that the given class belongs to.
1.143 + */
1.144 + @Nullable
1.145 + <A extends Annotation> A getPackageAnnotation(Class<A> annotation, C clazz, Locatable srcpos);
1.146 +
1.147 + /**
1.148 + * Reads a value of an annotation that returns a Class object.
1.149 + *
1.150 + * <p>
1.151 + * Depending on the underlying reflection library, you can't always
1.152 + * obtain the {@link Class} object directly (see the Annotation Processing MirrorTypeException
1.153 + * for example), so use this method to avoid that.
1.154 + *
1.155 + * @param name
1.156 + * The name of the annotation parameter to be read.
1.157 + */
1.158 + T getClassValue( Annotation a, String name );
1.159 +
1.160 + /**
1.161 + * Similar to {@link #getClassValue(Annotation, String)} method but
1.162 + * obtains an array parameter.
1.163 + */
1.164 + T[] getClassArrayValue( Annotation a, String name );
1.165 +}
