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 true if the parameter has a name according to the class
  99      * file; returns false otherwise. Whether a parameter has a name
 100      * is determined by the {@literal MethodParameters} attribute of
 101      * the method which declares the parameter.
 102      *
 103      * @return true if and only if the parameter has a name according
 104      * to the class file.
 105      */
 106     public boolean isNamePresent() {
 107         return executable.hasRealParameterData() && name != null;
 108     }
 109 
 110     /**
 111      * Returns a string describing this parameter.  The format is the
 112      * modifiers for the parameter, if any, in canonical order as
 113      * recommended by <cite>The Java&trade; Language
 114      * Specification</cite>, followed by the fully- qualified type of
 115      * the parameter (excluding the last [] if the parameter is
 116      * variable arity), followed by "..." if the parameter is variable
 117      * arity, followed by a space, followed by the name of the
 118      * parameter.
 119      *
 120      * @return A string representation of the parameter and associated
 121      * information.
 122      */
 123     public String toString() {
 124         final StringBuilder sb = new StringBuilder();
 125         final Type type = getParameterizedType();
 126         final String typename = type.getTypeName();
 127 
 128         sb.append(Modifier.toString(getModifiers()));
 129 
 130         if(0 != modifiers)
 131             sb.append(' ');
 132 
 133         if(isVarArgs())
 134             sb.append(typename.replaceFirst("\\[\\]$", "..."));
 135         else
 136             sb.append(typename);
 137 
 138         sb.append(' ');
 139         sb.append(getName());
 140 
 141         return sb.toString();
 142     }
 143 
 144     /**
 145      * Return the {@code Executable} which declares this parameter.
 146      *
 147      * @return The {@code Executable} declaring this parameter.
 148      */
 149     public Executable getDeclaringExecutable() {
 150         return executable;
 151     }
 152 
 153     /**
 154      * Get the modifier flags for this the parameter represented by
 155      * this {@code Parameter} object.
 156      *
 157      * @return The modifier flags for this parameter.
 158      */
 159     public int getModifiers() {
 160         return modifiers;
 161     }
 162 
 163     /**
 164      * Returns the name of the parameter.  If the parameter's name is
 165      * {@linkplain #isNamePresent() present}, then this method returns
 166      * the name provided by the class file. Otherwise, this method
 167      * synthesizes a name of the form argN, where N is the index of
 168      * the parameter in the descriptor of the method which declares
 169      * the parameter.
 170      *
 171      * @return The name of the parameter, either provided by the class
 172      *         file or synthesized if the class file does not provide
 173      *         a name.
 174      */
 175     public String getName() {
 176         // Note: empty strings as parameter names are now outlawed.
 177         // The .equals("") is for compatibility with current JVM
 178         // behavior.  It may be removed at some point.
 179         if(name == null || name.equals(""))
 180             return "arg" + index;
 181         else
 182             return name;
 183     }
 184 
 185     // Package-private accessor to the real name field.
 186     String getRealName() {
 187         return name;
 188     }
 189 
 190     /**
 191      * Returns a {@code Type} object that identifies the parameterized
 192      * type for the parameter represented by this {@code Parameter}
 193      * object.
 194      *
 195      * @return a {@code Type} object identifying the parameterized
 196      * type of the parameter represented by this object
 197      */
 198     public Type getParameterizedType() {
 199         Type tmp = parameterTypeCache;
 200         if (null == tmp) {
 201             tmp = executable.getGenericParameterTypes()[index];
 202             parameterTypeCache = tmp;
 203         }
 204 
 205         return tmp;
 206     }
 207 
 208     private transient volatile Type parameterTypeCache = null;
 209 
 210     /**
 211      * Returns a {@code Class} object that identifies the
 212      * declared type for the parameter represented by this
 213      * {@code Parameter} object.
 214      *
 215      * @return a {@code Class} object identifying the declared
 216      * type of the parameter represented by this object
 217      */
 218     public Class<?> getType() {
 219         Class<?> tmp = parameterClassCache;
 220         if (null == tmp) {
 221             tmp = executable.getParameterTypes()[index];
 222             parameterClassCache = tmp;
 223         }
 224         return tmp;
 225     }
 226 
 227     /**
 228      * Returns an AnnotatedType object that represents the use of a type to
 229      * specify the type of the formal parameter represented by this Parameter.
 230      *
 231      * @return an {@code AnnotatedType} object representing the use of a type
 232      *         to specify the type of the formal parameter represented by this
 233      *         Parameter
 234      */
 235     public AnnotatedType getAnnotatedType() {
 236         // no caching for now
 237         return executable.getAnnotatedParameterTypes()[index];
 238     }
 239 
 240     private transient volatile Class<?> parameterClassCache = null;
 241 
 242     /**
 243      * Returns {@code true} if this parameter is implicitly declared
 244      * in source code; returns {@code false} otherwise.
 245      *
 246      * @return true if and only if this parameter is implicitly
 247      * declared as defined by <cite>The Java&trade; Language
 248      * Specification</cite>.
 249      */
 250     public boolean isImplicit() {
 251         return Modifier.isMandated(getModifiers());
 252     }
 253 
 254     /**
 255      * Returns {@code true} if this parameter is neither implicitly
 256      * nor explicitly declared in source code; returns {@code false}
 257      * otherwise.
 258      *
 259      * @jls 13.1 The Form of a Binary
 260      * @return true if and only if this parameter is a synthetic
 261      * construct as defined by
 262      * <cite>The Java&trade; Language Specification</cite>.
 263      */
 264     public boolean isSynthetic() {
 265         return Modifier.isSynthetic(getModifiers());
 266     }
 267 
 268     /**
 269      * Returns {@code true} if this parameter represents a variable
 270      * argument list; returns {@code false} otherwise.
 271      *
 272      * @return {@code true} if an only if this parameter represents a
 273      * variable argument list.
 274      */
 275     public boolean isVarArgs() {
 276         return executable.isVarArgs() &&
 277             index == executable.getParameterCount() - 1;
 278     }
 279 
 280 
 281     /**
 282      * {@inheritDoc}
 283      * @throws NullPointerException {@inheritDoc}
 284      */
 285     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
 286         Objects.requireNonNull(annotationClass);
 287         return annotationClass.cast(declaredAnnotations().get(annotationClass));
 288     }
 289 
 290     /**
 291      * {@inheritDoc}
 292      * @throws NullPointerException {@inheritDoc}
 293      */
 294     @Override
 295     public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
 296         Objects.requireNonNull(annotationClass);
 297 
 298         return AnnotationSupport.getDirectlyAndIndirectlyPresent(declaredAnnotations(), annotationClass);
 299     }
 300 
 301     /**
 302      * {@inheritDoc}
 303      */
 304     public Annotation[] getDeclaredAnnotations() {
 305         return executable.getParameterAnnotations()[index];
 306     }
 307 
 308     /**
 309      * @throws NullPointerException {@inheritDoc}
 310      */
 311     public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) {
 312         // Only annotations on classes are inherited, for all other
 313         // objects getDeclaredAnnotation is the same as
 314         // getAnnotation.
 315         return getAnnotation(annotationClass);
 316     }
 317 
 318     /**
 319      * @throws NullPointerException {@inheritDoc}
 320      */
 321     @Override
 322     public <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) {
 323         // Only annotations on classes are inherited, for all other
 324         // objects getDeclaredAnnotations is the same as
 325         // getAnnotations.
 326         return getAnnotationsByType(annotationClass);
 327     }
 328 
 329     /**
 330      * {@inheritDoc}
 331      */
 332     public Annotation[] getAnnotations() {
 333         return getDeclaredAnnotations();
 334     }
 335 
 336     private transient Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
 337 
 338     private synchronized Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
 339         if(null == declaredAnnotations) {
 340             declaredAnnotations = new HashMap<>();
 341             for (Annotation a : getDeclaredAnnotations())
 342                 declaredAnnotations.put(a.annotationType(), a);
 343         }
 344         return declaredAnnotations;
 345    }
 346 
 347 }