1 /*
   2  * Copyright (c) 1996, 2017, 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 
  26 package java.lang.reflect;
  27 
  28 import jdk.internal.misc.SharedSecrets;
  29 import jdk.internal.reflect.CallerSensitive;
  30 import jdk.internal.reflect.ConstructorAccessor;
  31 import jdk.internal.reflect.Reflection;
  32 import jdk.internal.vm.annotation.ForceInline;
  33 import sun.reflect.annotation.TypeAnnotation;
  34 import sun.reflect.annotation.TypeAnnotationParser;
  35 import sun.reflect.generics.repository.ConstructorRepository;
  36 import sun.reflect.generics.factory.CoreReflectionFactory;
  37 import sun.reflect.generics.factory.GenericsFactory;
  38 import sun.reflect.generics.scope.ConstructorScope;
  39 import java.lang.annotation.Annotation;
  40 import java.lang.annotation.AnnotationFormatError;
  41 import java.util.StringJoiner;
  42 
  43 /**
  44  * {@code Constructor} provides information about, and access to, a single
  45  * constructor for a class.
  46  *
  47  * <p>{@code Constructor} permits widening conversions to occur when matching the
  48  * actual parameters to newInstance() with the underlying
  49  * constructor's formal parameters, but throws an
  50  * {@code IllegalArgumentException} if a narrowing conversion would occur.
  51  *
  52  * @param <T> the class in which the constructor is declared
  53  *
  54  * @see Member
  55  * @see java.lang.Class
  56  * @see java.lang.Class#getConstructors()
  57  * @see java.lang.Class#getConstructor(Class[])
  58  * @see java.lang.Class#getDeclaredConstructors()
  59  *
  60  * @author      Kenneth Russell
  61  * @author      Nakul Saraiya
  62  * @since 1.1
  63  */
  64 public final class Constructor<T> extends Executable {
  65     private Class<T>            clazz;
  66     private int                 slot;
  67     private Class<?>[]          parameterTypes;
  68     private Class<?>[]          exceptionTypes;
  69     private int                 modifiers;
  70     // Generics and annotations support
  71     private transient String    signature;
  72     // generic info repository; lazily initialized
  73     private transient ConstructorRepository genericInfo;
  74     private byte[]              annotations;
  75     private byte[]              parameterAnnotations;
  76 
  77     // Generics infrastructure
  78     // Accessor for factory
  79     private GenericsFactory getFactory() {
  80         // create scope and factory
  81         return CoreReflectionFactory.make(this, ConstructorScope.make(this));
  82     }
  83 
  84     // Accessor for generic info repository
  85     @Override
  86     ConstructorRepository getGenericInfo() {
  87         // lazily initialize repository if necessary
  88         if (genericInfo == null) {
  89             // create and cache generic info repository
  90             genericInfo =
  91                 ConstructorRepository.make(getSignature(),
  92                                            getFactory());
  93         }
  94         return genericInfo; //return cached repository
  95     }
  96 
  97     private volatile ConstructorAccessor constructorAccessor;
  98     // For sharing of ConstructorAccessors. This branching structure
  99     // is currently only two levels deep (i.e., one root Constructor
 100     // and potentially many Constructor objects pointing to it.)
 101     //
 102     // If this branching structure would ever contain cycles, deadlocks can
 103     // occur in annotation code.
 104     private Constructor<T>      root;
 105 
 106     @Override
 107     Constructor<T> getRoot() {
 108         return root;
 109     }
 110 
 111     /**
 112      * Package-private constructor used by ReflectAccess to enable
 113      * instantiation of these objects in Java code from the java.lang
 114      * package via sun.reflect.LangReflectAccess.
 115      */
 116     Constructor(Class<T> declaringClass,
 117                 Class<?>[] parameterTypes,
 118                 Class<?>[] checkedExceptions,
 119                 int modifiers,
 120                 int slot,
 121                 String signature,
 122                 byte[] annotations,
 123                 byte[] parameterAnnotations) {
 124         this.clazz = declaringClass;
 125         this.parameterTypes = parameterTypes;
 126         this.exceptionTypes = checkedExceptions;
 127         this.modifiers = modifiers;
 128         this.slot = slot;
 129         this.signature = signature;
 130         this.annotations = annotations;
 131         this.parameterAnnotations = parameterAnnotations;
 132     }
 133 
 134     /**
 135      * Package-private routine (exposed to java.lang.Class via
 136      * ReflectAccess) which returns a copy of this Constructor. The copy's
 137      * "root" field points to this Constructor.
 138      */
 139     Constructor<T> copy() {
 140         // This routine enables sharing of ConstructorAccessor objects
 141         // among Constructor objects which refer to the same underlying
 142         // method in the VM. (All of this contortion is only necessary
 143         // because of the "accessibility" bit in AccessibleObject,
 144         // which implicitly requires that new java.lang.reflect
 145         // objects be fabricated for each reflective call on Class
 146         // objects.)
 147         if (this.root != null)
 148             throw new IllegalArgumentException("Can not copy a non-root Constructor");
 149 
 150         Constructor<T> res = new Constructor<>(clazz,
 151                                                parameterTypes,
 152                                                exceptionTypes, modifiers, slot,
 153                                                signature,
 154                                                annotations,
 155                                                parameterAnnotations);
 156         res.root = this;
 157         // Might as well eagerly propagate this if already present
 158         res.constructorAccessor = constructorAccessor;
 159         return res;
 160     }
 161 
 162     /**
 163      * {@inheritDoc}
 164      *
 165      * <p> A {@code SecurityException} is also thrown if this object is a
 166      * {@code Constructor} object for the class {@code Class} and {@code flag}
 167      * is true. </p>
 168      *
 169      * @param flag {@inheritDoc}
 170      *
 171      * @throws InaccessibleObjectException {@inheritDoc}
 172      * @throws SecurityException if the request is denied by the security manager
 173      *         or this is a constructor for {@code java.lang.Class}
 174      *
 175      * @spec JPMS
 176      */
 177     @Override
 178     @CallerSensitive
 179     public void setAccessible(boolean flag) {
 180         AccessibleObject.checkPermission();
 181         if (flag) {
 182             checkCanSetAccessible(Reflection.getCallerClass());
 183         }
 184         setAccessible0(flag);
 185     }
 186 
 187     @Override
 188     void checkCanSetAccessible(Class<?> caller) {
 189         checkCanSetAccessible(caller, clazz);
 190         if (clazz == Class.class) {
 191             // can we change this to InaccessibleObjectException?
 192             throw new SecurityException("Cannot make a java.lang.Class"
 193                                         + " constructor accessible");
 194         }
 195     }
 196 
 197     @Override
 198     boolean hasGenericInformation() {
 199         return (getSignature() != null);
 200     }
 201 
 202     @Override
 203     byte[] getAnnotationBytes() {
 204         return annotations;
 205     }
 206 
 207     /**
 208      * Returns the {@code Class} object representing the class that
 209      * declares the constructor represented by this object.
 210      */
 211     @Override
 212     public Class<T> getDeclaringClass() {
 213         return clazz;
 214     }
 215 
 216     /**
 217      * Returns the name of this constructor, as a string.  This is
 218      * the binary name of the constructor's declaring class.
 219      */
 220     @Override
 221     public String getName() {
 222         return getDeclaringClass().getName();
 223     }
 224 
 225     /**
 226      * {@inheritDoc}
 227      */
 228     @Override
 229     public int getModifiers() {
 230         return modifiers;
 231     }
 232 
 233     /**
 234      * {@inheritDoc}
 235      * @throws GenericSignatureFormatError {@inheritDoc}
 236      * @since 1.5
 237      */
 238     @Override
 239     @SuppressWarnings({"rawtypes", "unchecked"})
 240     public TypeVariable<Constructor<T>>[] getTypeParameters() {
 241       if (getSignature() != null) {
 242         return (TypeVariable<Constructor<T>>[])getGenericInfo().getTypeParameters();
 243       } else
 244           return (TypeVariable<Constructor<T>>[])new TypeVariable[0];
 245     }
 246 
 247 
 248     @Override
 249     Class<?>[] getSharedParameterTypes() {
 250         return parameterTypes;
 251     }
 252 
 253     @Override
 254     Class<?>[] getSharedExceptionTypes() {
 255         return exceptionTypes;
 256     }
 257 
 258     /**
 259      * {@inheritDoc}
 260      */
 261     @Override
 262     public Class<?>[] getParameterTypes() {
 263         return parameterTypes.clone();
 264     }
 265 
 266     /**
 267      * {@inheritDoc}
 268      * @since 1.8
 269      */
 270     public int getParameterCount() { return parameterTypes.length; }
 271 
 272     /**
 273      * {@inheritDoc}
 274      * @throws GenericSignatureFormatError {@inheritDoc}
 275      * @throws TypeNotPresentException {@inheritDoc}
 276      * @throws MalformedParameterizedTypeException {@inheritDoc}
 277      * @since 1.5
 278      */
 279     @Override
 280     public Type[] getGenericParameterTypes() {
 281         return super.getGenericParameterTypes();
 282     }
 283 
 284     /**
 285      * {@inheritDoc}
 286      */
 287     @Override
 288     public Class<?>[] getExceptionTypes() {
 289         return exceptionTypes.clone();
 290     }
 291 
 292 
 293     /**
 294      * {@inheritDoc}
 295      * @throws GenericSignatureFormatError {@inheritDoc}
 296      * @throws TypeNotPresentException {@inheritDoc}
 297      * @throws MalformedParameterizedTypeException {@inheritDoc}
 298      * @since 1.5
 299      */
 300     @Override
 301     public Type[] getGenericExceptionTypes() {
 302         return super.getGenericExceptionTypes();
 303     }
 304 
 305     /**
 306      * Compares this {@code Constructor} against the specified object.
 307      * Returns true if the objects are the same.  Two {@code Constructor} objects are
 308      * the same if they were declared by the same class and have the
 309      * same formal parameter types.
 310      */
 311     public boolean equals(Object obj) {
 312         if (obj != null && obj instanceof Constructor) {
 313             Constructor<?> other = (Constructor<?>)obj;
 314             if (getDeclaringClass() == other.getDeclaringClass()) {
 315                 return equalParamTypes(parameterTypes, other.parameterTypes);
 316             }
 317         }
 318         return false;
 319     }
 320 
 321     /**
 322      * Returns a hashcode for this {@code Constructor}. The hashcode is
 323      * the same as the hashcode for the underlying constructor's
 324      * declaring class name.
 325      */
 326     public int hashCode() {
 327         return getDeclaringClass().getName().hashCode();
 328     }
 329 
 330     /**
 331      * Returns a string describing this {@code Constructor}.  The string is
 332      * formatted as the constructor access modifiers, if any,
 333      * followed by the fully-qualified name of the declaring class,
 334      * followed by a parenthesized, comma-separated list of the
 335      * constructor's formal parameter types.  For example:
 336      * <pre>{@code
 337      *    public java.util.Hashtable(int,float)
 338      * }</pre>
 339      *
 340      * <p>If the constructor is declared to throw exceptions, the
 341      * parameter list is followed by a space, followed by the word
 342      * "{@code throws}" followed by a comma-separated list of the
 343      * thrown exception types.
 344      *
 345      * <p>The only possible modifiers for constructors are the access
 346      * modifiers {@code public}, {@code protected} or
 347      * {@code private}.  Only one of these may appear, or none if the
 348      * constructor has default (package) access.
 349      *
 350      * @return a string describing this {@code Constructor}
 351      * @jls 8.8.3 Constructor Modifiers
 352      * @jls 8.9.2 Enum Body Declarations
 353      */
 354     public String toString() {
 355         return sharedToString(Modifier.constructorModifiers(),
 356                               false,
 357                               parameterTypes,
 358                               exceptionTypes);
 359     }
 360 
 361     @Override
 362     void specificToStringHeader(StringBuilder sb) {
 363         sb.append(getDeclaringClass().getTypeName());
 364     }
 365 
 366     @Override
 367     String toShortString() {
 368         StringBuilder sb = new StringBuilder("constructor ");
 369         sb.append(getDeclaringClass().getTypeName());
 370         sb.append('(');
 371         StringJoiner sj = new StringJoiner(",");
 372         for (Class<?> parameterType : getParameterTypes()) {
 373             sj.add(parameterType.getTypeName());
 374         }
 375         sb.append(sj);
 376         sb.append(')');
 377         return sb.toString();
 378     }
 379 
 380     /**
 381      * Returns a string describing this {@code Constructor},
 382      * including type parameters.  The string is formatted as the
 383      * constructor access modifiers, if any, followed by an
 384      * angle-bracketed comma separated list of the constructor's type
 385      * parameters, if any, including  informative bounds of the
 386      * type parameters, if any, followed by the fully-qualified name of the
 387      * declaring class, followed by a parenthesized, comma-separated
 388      * list of the constructor's generic formal parameter types.
 389      *
 390      * If this constructor was declared to take a variable number of
 391      * arguments, instead of denoting the last parameter as
 392      * "<code><i>Type</i>[]</code>", it is denoted as
 393      * "<code><i>Type</i>...</code>".
 394      *
 395      * A space is used to separate access modifiers from one another
 396      * and from the type parameters or class name.  If there are no
 397      * type parameters, the type parameter list is elided; if the type
 398      * parameter list is present, a space separates the list from the
 399      * class name.  If the constructor is declared to throw
 400      * exceptions, the parameter list is followed by a space, followed
 401      * by the word "{@code throws}" followed by a
 402      * comma-separated list of the generic thrown exception types.
 403      *
 404      * <p>The only possible modifiers for constructors are the access
 405      * modifiers {@code public}, {@code protected} or
 406      * {@code private}.  Only one of these may appear, or none if the
 407      * constructor has default (package) access.
 408      *
 409      * @return a string describing this {@code Constructor},
 410      * include type parameters
 411      *
 412      * @since 1.5
 413      * @jls 8.8.3 Constructor Modifiers
 414      * @jls 8.9.2 Enum Body Declarations
 415      */
 416     @Override
 417     public String toGenericString() {
 418         return sharedToGenericString(Modifier.constructorModifiers(), false);
 419     }
 420 
 421     @Override
 422     void specificToGenericStringHeader(StringBuilder sb) {
 423         specificToStringHeader(sb);
 424     }
 425 
 426     /**
 427      * Uses the constructor represented by this {@code Constructor} object to
 428      * create and initialize a new instance of the constructor's
 429      * declaring class, with the specified initialization parameters.
 430      * Individual parameters are automatically unwrapped to match
 431      * primitive formal parameters, and both primitive and reference
 432      * parameters are subject to method invocation conversions as necessary.
 433      *
 434      * <p>If the number of formal parameters required by the underlying constructor
 435      * is 0, the supplied {@code initargs} array may be of length 0 or null.
 436      *
 437      * <p>If the constructor's declaring class is an inner class in a
 438      * non-static context, the first argument to the constructor needs
 439      * to be the enclosing instance; see section 15.9.3 of
 440      * <cite>The Java&trade; Language Specification</cite>.
 441      *
 442      * <p>If the required access and argument checks succeed and the
 443      * instantiation will proceed, the constructor's declaring class
 444      * is initialized if it has not already been initialized.
 445      *
 446      * <p>If the constructor completes normally, returns the newly
 447      * created and initialized instance.
 448      *
 449      * @param initargs array of objects to be passed as arguments to
 450      * the constructor call; values of primitive types are wrapped in
 451      * a wrapper object of the appropriate type (e.g. a {@code float}
 452      * in a {@link java.lang.Float Float})
 453      *
 454      * @return a new object created by calling the constructor
 455      * this object represents
 456      *
 457      * @exception IllegalAccessException    if this {@code Constructor} object
 458      *              is enforcing Java language access control and the underlying
 459      *              constructor is inaccessible.
 460      * @exception IllegalArgumentException  if the number of actual
 461      *              and formal parameters differ; if an unwrapping
 462      *              conversion for primitive arguments fails; or if,
 463      *              after possible unwrapping, a parameter value
 464      *              cannot be converted to the corresponding formal
 465      *              parameter type by a method invocation conversion; if
 466      *              this constructor pertains to an enum type.
 467      * @exception InstantiationException    if the class that declares the
 468      *              underlying constructor represents an abstract class.
 469      * @exception InvocationTargetException if the underlying constructor
 470      *              throws an exception.
 471      * @exception ExceptionInInitializerError if the initialization provoked
 472      *              by this method fails.
 473      */
 474     @CallerSensitive
 475     @ForceInline // to ensure Reflection.getCallerClass optimization
 476     public T newInstance(Object ... initargs)
 477         throws InstantiationException, IllegalAccessException,
 478                IllegalArgumentException, InvocationTargetException
 479     {
 480         Class<?> caller = override ? null : Reflection.getCallerClass();
 481         return newInstanceWithCaller(initargs, !override, caller);
 482     }
 483 
 484     /* package-private */
 485     T newInstanceWithCaller(Object[] args, boolean checkAccess, Class<?> caller)
 486         throws InstantiationException, IllegalAccessException,
 487                InvocationTargetException
 488     {
 489         if (checkAccess)
 490             checkAccess(caller, clazz, clazz, modifiers);
 491 
 492         if ((clazz.getModifiers() & Modifier.ENUM) != 0)
 493             throw new IllegalArgumentException("Cannot reflectively create enum objects");
 494 
 495         ConstructorAccessor ca = constructorAccessor;   // read volatile
 496         if (ca == null) {
 497             ca = acquireConstructorAccessor();
 498         }
 499         @SuppressWarnings("unchecked")
 500         T inst = (T) ca.newInstance(args);
 501         return inst;
 502     }
 503 
 504     /**
 505      * {@inheritDoc}
 506      * @since 1.5
 507      */
 508     @Override
 509     public boolean isVarArgs() {
 510         return super.isVarArgs();
 511     }
 512 
 513     /**
 514      * {@inheritDoc}
 515      * @jls 13.1 The Form of a Binary
 516      * @since 1.5
 517      */
 518     @Override
 519     public boolean isSynthetic() {
 520         return super.isSynthetic();
 521     }
 522 
 523     // NOTE that there is no synchronization used here. It is correct
 524     // (though not efficient) to generate more than one
 525     // ConstructorAccessor for a given Constructor. However, avoiding
 526     // synchronization will probably make the implementation more
 527     // scalable.
 528     private ConstructorAccessor acquireConstructorAccessor() {
 529         // First check to see if one has been created yet, and take it
 530         // if so.
 531         ConstructorAccessor tmp = null;
 532         if (root != null) tmp = root.getConstructorAccessor();
 533         if (tmp != null) {
 534             constructorAccessor = tmp;
 535         } else {
 536             // Otherwise fabricate one and propagate it up to the root
 537             tmp = reflectionFactory.newConstructorAccessor(this);
 538             setConstructorAccessor(tmp);
 539         }
 540 
 541         return tmp;
 542     }
 543 
 544     // Returns ConstructorAccessor for this Constructor object, not
 545     // looking up the chain to the root
 546     ConstructorAccessor getConstructorAccessor() {
 547         return constructorAccessor;
 548     }
 549 
 550     // Sets the ConstructorAccessor for this Constructor object and
 551     // (recursively) its root
 552     void setConstructorAccessor(ConstructorAccessor accessor) {
 553         constructorAccessor = accessor;
 554         // Propagate up
 555         if (root != null) {
 556             root.setConstructorAccessor(accessor);
 557         }
 558     }
 559 
 560     int getSlot() {
 561         return slot;
 562     }
 563 
 564     String getSignature() {
 565         return signature;
 566     }
 567 
 568     byte[] getRawAnnotations() {
 569         return annotations;
 570     }
 571 
 572     byte[] getRawParameterAnnotations() {
 573         return parameterAnnotations;
 574     }
 575 
 576 
 577     /**
 578      * {@inheritDoc}
 579      * @throws NullPointerException  {@inheritDoc}
 580      * @since 1.5
 581      */
 582     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
 583         return super.getAnnotation(annotationClass);
 584     }
 585 
 586     /**
 587      * {@inheritDoc}
 588      * @since 1.5
 589      */
 590     public Annotation[] getDeclaredAnnotations()  {
 591         return super.getDeclaredAnnotations();
 592     }
 593 
 594     /**
 595      * {@inheritDoc}
 596      * @since 1.5
 597      */
 598     @Override
 599     public Annotation[][] getParameterAnnotations() {
 600         return sharedGetParameterAnnotations(parameterTypes, parameterAnnotations);
 601     }
 602 
 603     @Override
 604     boolean handleParameterNumberMismatch(int resultLength, int numParameters) {
 605         Class<?> declaringClass = getDeclaringClass();
 606         if (declaringClass.isEnum() ||
 607             declaringClass.isAnonymousClass() ||
 608             declaringClass.isLocalClass() )
 609             return false; // Can't do reliable parameter counting
 610         else {
 611             if (declaringClass.isMemberClass() &&
 612                 ((declaringClass.getModifiers() & Modifier.STATIC) == 0)  &&
 613                 resultLength + 1 == numParameters) {
 614                 return true;
 615             } else {
 616                 throw new AnnotationFormatError(
 617                           "Parameter annotations don't match number of parameters");
 618             }
 619         }
 620     }
 621 
 622     /**
 623      * {@inheritDoc}
 624      * @since 1.8
 625      */
 626     @Override
 627     public AnnotatedType getAnnotatedReturnType() {
 628         return getAnnotatedReturnType0(getDeclaringClass());
 629     }
 630 
 631     /**
 632      * {@inheritDoc}
 633      * @since 1.8
 634      */
 635     @Override
 636     public AnnotatedType getAnnotatedReceiverType() {
 637         Class<?> thisDeclClass = getDeclaringClass();
 638         Class<?> enclosingClass = thisDeclClass.getEnclosingClass();
 639 
 640         if (enclosingClass == null) {
 641             // A Constructor for a top-level class
 642             return null;
 643         }
 644 
 645         Class<?> outerDeclaringClass = thisDeclClass.getDeclaringClass();
 646         if (outerDeclaringClass == null) {
 647             // A constructor for a local or anonymous class
 648             return null;
 649         }
 650 
 651         // Either static nested or inner class
 652         if (Modifier.isStatic(thisDeclClass.getModifiers())) {
 653             // static nested
 654             return null;
 655         }
 656 
 657         // A Constructor for an inner class
 658         return TypeAnnotationParser.buildAnnotatedType(getTypeAnnotationBytes0(),
 659                 SharedSecrets.getJavaLangAccess().
 660                     getConstantPool(thisDeclClass),
 661                 this,
 662                 thisDeclClass,
 663                 enclosingClass,
 664                 TypeAnnotation.TypeAnnotationTarget.METHOD_RECEIVER);
 665     }
 666 }