1 /*
   2  * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.lang.reflect;
  26 
  27 import java.lang.annotation.*;
  28 import java.util.HashMap;
  29 import java.util.Map;
  30 import java.util.Objects;
  31 import sun.reflect.annotation.AnnotationSupport;
  32 
  33 /**
  34  * Information about method parameters.
  35  *
  36  * A {@code Parameter} provides information about method parameters,
  37  * including its name and modifiers.  It also provides an alternate
  38  * means of obtaining attributes for the parameter.
  39  *
  40  * @since 1.8
  41  */
  42 public final class Parameter implements AnnotatedElement {
  43 
  44     private final String name;
  45     private final int modifiers;
  46     private final Executable executable;
  47     private final int index;
  48 
  49     /**
  50      * Package-private constructor for {@code Parameter}.
  51      *
  52      * If method parameter data is present in the classfile, then the
  53      * JVM creates {@code Parameter} objects directly.  If it is
  54      * absent, however, then {@code Executable} uses this constructor
  55      * to synthesize them.
  56      *
  57      * @param name The name of the parameter.
  58      * @param modifiers The modifier flags for the parameter.
  59      * @param executable The executable which defines this parameter.
  60      * @param index The index of the parameter.
  61      */
  62     Parameter(String name,
  63               int modifiers,
  64               Executable executable,
  65               int index) {
  66         this.name = name;
  67         this.modifiers = modifiers;
  68         this.executable = executable;
  69         this.index = index;
  70     }
  71 
  72     /**
  73      * Compares based on the executable and the index.
  74      *
  75      * @param obj The object to compare.
  76      * @return Whether or not this is equal to the argument.
  77      */
  78     public boolean equals(Object obj) {
  79         if(obj instanceof Parameter) {
  80             Parameter other = (Parameter)obj;
  81             return (other.executable.equals(executable) &&
  82                     other.index == index);
  83         }
  84         return false;
  85     }
  86 
  87     /**
  88      * Returns a hash code based on the executable's hash code and the
  89      * index.
  90      *
  91      * @return A hash code based on the executable's hash code.
  92      */
  93     public int hashCode() {
  94         return executable.hashCode() ^ index;
  95     }
  96 
  97     /**
  98      * Returns a string describing this parameter.  The format is the
  99      * modifiers for the parameter, if any, in canonical order as
 100      * recommended by <cite>The Java&trade; Language
 101      * Specification</cite>, followed by the fully- qualified type of
 102      * the parameter (excluding the last [] if the parameter is
 103      * variable arity), followed by "..." if the parameter is variable
 104      * arity, followed by a space, followed by the name of the
 105      * parameter.
 106      *
 107      * @return A string representation of the parameter and associated
 108      * information.
 109      */
 110     public String toString() {
 111         final StringBuilder sb = new StringBuilder();
 112         final Type type = getParameterizedType();
 113         final String typename = (type instanceof Class)?
 114             Field.getTypeName((Class)type):
 115             (type.toString());
 116 
 117         sb.append(Modifier.toString(getModifiers()));
 118 
 119         if(0 != modifiers)
 120             sb.append(" ");
 121 
 122         if(isVarArgs())
 123             sb.append(typename.replaceFirst("\\[\\]$", "..."));
 124         else
 125             sb.append(typename);
 126 
 127         sb.append(" ");
 128         sb.append(getName());
 129 
 130         return sb.toString();
 131     }
 132 
 133     /**
 134      * Return the {@code Executable} which declares this parameter.
 135      *
 136      * @return The {@code Executable} declaring this parameter.
 137      */
 138     public Executable getDeclaringExecutable() {
 139         return executable;
 140     }
 141 
 142     /**
 143      * Get the modifier flags for this the parameter represented by
 144      * this {@code Parameter} object.
 145      *
 146      * @return The modifier flags for this parameter.
 147      */
 148     public int getModifiers() {
 149         return modifiers;
 150     }
 151 
 152     /**
 153      * Returns the name of the parameter.  The names of the parameters
 154      * of a single executable must all the be distinct.  When names
 155      * from the originating source are available, they are returned.
 156      * Otherwise, an implementation of this method is free to create a
 157      * name of this parameter, subject to the unquiness requirments.
 158      */
 159     public String getName() {
 160         // As per the spec, if a parameter has no name, return argX,
 161         // where x is the index.
 162         //
 163         // Note: spec updates now outlaw empty strings as parameter
 164         // names.  The .equals("") is for compatibility with current
 165         // JVM behavior.  It may be removed at some point.
 166         if(name == null || name.equals(""))
 167             return "arg" + index;
 168         else
 169             return name;
 170     }
 171 
 172     /**
 173      * Returns a {@code Type} object that identifies the parameterized
 174      * type for the parameter represented by this {@code Parameter}
 175      * object.
 176      *
 177      * @return a {@code Type} object identifying the parameterized
 178      * type of the parameter represented by this object
 179      */
 180     public Type getParameterizedType() {
 181         Type tmp = parameterTypeCache;
 182         if (null == tmp) {
 183             tmp = executable.getGenericParameterTypes()[index];
 184             parameterTypeCache = tmp;
 185         }
 186 
 187         return tmp;
 188     }
 189 
 190     private transient volatile Type parameterTypeCache = null;
 191 
 192     /**
 193      * Returns a {@code Class} object that identifies the
 194      * declared type for the parameter represented by this
 195      * {@code Parameter} object.
 196      *
 197      * @return a {@code Class} object identifying the declared
 198      * type of the parameter represented by this object
 199      */
 200     public Class<?> getType() {
 201         Class<?> tmp = parameterClassCache;
 202         if (null == tmp) {
 203             tmp = executable.getParameterTypes()[index];
 204             parameterClassCache = tmp;
 205         }
 206         return tmp;
 207     }
 208 
 209     private transient volatile Class<?> parameterClassCache = null;
 210 
 211     /**
 212      * Returns {@code true} if this parameter is implicitly declared
 213      * in source code; returns {@code false} otherwise.
 214      *
 215      * @return true if and only if this parameter is implicitly
 216      * declared as defined by <cite>The Java&trade; Language
 217      * Specification</cite>.
 218      */
 219     public boolean isImplicit() {
 220         return Modifier.isMandated(getModifiers());
 221     }
 222 
 223     /**
 224      * Returns {@code true} if this parameter is neither implicitly
 225      * nor explicitly declared in source code; returns {@code false}
 226      * otherwise.
 227      *
 228      * @jls 13.1 The Form of a Binary
 229      * @return true if and only if this parameter is a synthetic
 230      * construct as defined by
 231      * <cite>The Java&trade; Language Specification</cite>.
 232      */
 233     public boolean isSynthetic() {
 234         return Modifier.isSynthetic(getModifiers());
 235     }
 236 
 237     /**
 238      * Returns {@code true} if this parameter represents a variable
 239      * argument list; returns {@code false} otherwise.
 240      *
 241      * @return {@code true} if an only if this parameter represents a
 242      * variable argument list.
 243      */
 244     public boolean isVarArgs() {
 245         return executable.isVarArgs() &&
 246             index == executable.getParameterCount() - 1;
 247     }
 248 
 249 
 250     /**
 251      * {@inheritDoc}
 252      * @throws NullPointerException {@inheritDoc}
 253      */
 254     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
 255         Objects.requireNonNull(annotationClass);
 256         return annotationClass.cast(declaredAnnotations().get(annotationClass));
 257     }
 258 
 259     /**
 260      * {@inheritDoc}
 261      * @throws NullPointerException {@inheritDoc}
 262      */
 263     @Override
 264     public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
 265         Objects.requireNonNull(annotationClass);
 266 
 267         return AnnotationSupport.getMultipleAnnotations(declaredAnnotations(), annotationClass);
 268     }
 269 
 270     /**
 271      * {@inheritDoc}
 272      */
 273     public Annotation[] getDeclaredAnnotations() {
 274         return executable.getParameterAnnotations()[index];
 275     }
 276 
 277     /**
 278      * @throws NullPointerException {@inheritDoc}
 279      */
 280     public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) {
 281         // Only annotations on classes are inherited, for all other
 282         // objects getDeclaredAnnotation is the same as
 283         // getAnnotation.
 284         return getAnnotation(annotationClass);
 285     }
 286 
 287     /**
 288      * @throws NullPointerException {@inheritDoc}
 289      */
 290     @Override
 291     public <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) {
 292         // Only annotations on classes are inherited, for all other
 293         // objects getDeclaredAnnotations is the same as
 294         // getAnnotations.
 295         return getAnnotationsByType(annotationClass);
 296     }
 297 
 298     /**
 299      * {@inheritDoc}
 300      */
 301     public Annotation[] getAnnotations() {
 302         return getDeclaredAnnotations();
 303     }
 304 
 305     private transient Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
 306 
 307     private synchronized Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
 308         if(null == declaredAnnotations) {
 309             declaredAnnotations =
 310                 new HashMap<Class<? extends Annotation>, Annotation>();
 311             Annotation[] ann = getDeclaredAnnotations();
 312             for(int i = 0; i < ann.length; i++)
 313                 declaredAnnotations.put(ann[i].annotationType(), ann[i]);
 314         }
 315         return declaredAnnotations;
 316     }
 317 
 318 }