1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.lang.reflect;
27
28 import sun.reflect.ConstructorAccessor;
29 import sun.reflect.Reflection;
30 import sun.reflect.generics.repository.ConstructorRepository;
31 import sun.reflect.generics.factory.CoreReflectionFactory;
32 import sun.reflect.generics.factory.GenericsFactory;
33 import sun.reflect.generics.scope.ConstructorScope;
34 import java.lang.annotation.Annotation;
35 import java.util.Map;
36 import sun.reflect.annotation.AnnotationParser;
37 import java.lang.annotation.AnnotationFormatError;
38 import java.lang.reflect.Modifier;
39
40 /**
41 * {@code Constructor} provides information about, and access to, a single
42 * constructor for a class.
43 *
44 * <p>{@code Constructor} permits widening conversions to occur when matching the
45 * actual parameters to newInstance() with the underlying
46 * constructor's formal parameters, but throws an
47 * {@code IllegalArgumentException} if a narrowing conversion would occur.
48 *
49 * @param <T> the class in which the constructor is declared
50 *
51 * @see Member
52 * @see java.lang.Class
53 * @see java.lang.Class#getConstructors()
54 * @see java.lang.Class#getConstructor(Class[])
55 * @see java.lang.Class#getDeclaredConstructors()
56 *
57 * @author Kenneth Russell
58 * @author Nakul Saraiya
59 */
60 public final
61 class Constructor<T> extends AccessibleObject implements
62 GenericDeclaration,
63 Member {
64
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 // For non-public members or members in package-private classes,
78 // it is necessary to perform somewhat expensive security checks.
79 // If the security check succeeds for a given class, it will
80 // always succeed (it is not affected by the granting or revoking
81 // of permissions); we speed up the check in the common case by
82 // remembering the last Class for which the check succeeded.
83 private volatile Class securityCheckCache;
84
85 // Generics infrastructure
86 // Accessor for factory
87 private GenericsFactory getFactory() {
88 // create scope and factory
89 return CoreReflectionFactory.make(this, ConstructorScope.make(this));
90 }
91
92 // Accessor for generic info repository
93 private ConstructorRepository getGenericInfo() {
94 // lazily initialize repository if necessary
95 if (genericInfo == null) {
96 // create and cache generic info repository
97 genericInfo =
98 ConstructorRepository.make(getSignature(),
99 getFactory());
100 }
101 return genericInfo; //return cached repository
102 }
103
104 private volatile ConstructorAccessor constructorAccessor;
105 // For sharing of ConstructorAccessors. This branching structure
106 // is currently only two levels deep (i.e., one root Constructor
107 // and potentially many Constructor objects pointing to it.)
108 private Constructor<T> root;
109
110 /**
111 * Package-private constructor used by ReflectAccess to enable
112 * instantiation of these objects in Java code from the java.lang
113 * package via sun.reflect.LangReflectAccess.
114 */
115 Constructor(Class<T> declaringClass,
116 Class[] parameterTypes,
117 Class[] checkedExceptions,
118 int modifiers,
119 int slot,
120 String signature,
121 byte[] annotations,
122 byte[] parameterAnnotations)
123 {
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 Constructor<T> res = new Constructor<T>(clazz,
148 parameterTypes,
149 exceptionTypes, modifiers, slot,
150 signature,
151 annotations,
152 parameterAnnotations);
153 res.root = this;
154 // Might as well eagerly propagate this if already present
155 res.constructorAccessor = constructorAccessor;
156 return res;
157 }
158
159 /**
160 * Returns the {@code Class} object representing the class that declares
161 * the constructor represented by this {@code Constructor} object.
162 */
163 public Class<T> getDeclaringClass() {
164 return clazz;
165 }
166
167 /**
168 * Returns the name of this constructor, as a string. This is
169 * always the same as the simple name of the constructor's declaring
170 * class.
171 */
172 public String getName() {
173 return getDeclaringClass().getName();
174 }
175
176 /**
177 * Returns the Java language modifiers for the constructor
178 * represented by this {@code Constructor} object, as an integer. The
179 * {@code Modifier} class should be used to decode the modifiers.
180 *
181 * @see Modifier
182 */
183 public int getModifiers() {
184 return modifiers;
185 }
186
187 /**
188 * Returns an array of {@code TypeVariable} objects that represent the
189 * type variables declared by the generic declaration represented by this
190 * {@code GenericDeclaration} object, in declaration order. Returns an
191 * array of length 0 if the underlying generic declaration declares no type
192 * variables.
193 *
194 * @return an array of {@code TypeVariable} objects that represent
195 * the type variables declared by this generic declaration
196 * @throws GenericSignatureFormatError if the generic
197 * signature of this generic declaration does not conform to
198 * the format specified in the Java Virtual Machine Specification,
199 * 3rd edition
200 * @since 1.5
201 */
202 public TypeVariable<Constructor<T>>[] getTypeParameters() {
203 if (getSignature() != null) {
204 return (TypeVariable<Constructor<T>>[])getGenericInfo().getTypeParameters();
205 } else
206 return (TypeVariable<Constructor<T>>[])new TypeVariable[0];
207 }
208
209
210 /**
211 * Returns an array of {@code Class} objects that represent the formal
212 * parameter types, in declaration order, of the constructor
213 * represented by this {@code Constructor} object. Returns an array of
214 * length 0 if the underlying constructor takes no parameters.
215 *
216 * @return the parameter types for the constructor this object
217 * represents
218 */
219 public Class<?>[] getParameterTypes() {
220 return (Class<?>[]) parameterTypes.clone();
221 }
222
223
224 /**
225 * Returns an array of {@code Type} objects that represent the formal
226 * parameter types, in declaration order, of the method represented by
227 * this {@code Constructor} object. Returns an array of length 0 if the
228 * underlying method takes no parameters.
229 *
230 * <p>If a formal parameter type is a parameterized type,
231 * the {@code Type} object returned for it must accurately reflect
232 * the actual type parameters used in the source code.
233 *
234 * <p>If a formal parameter type is a type variable or a parameterized
235 * type, it is created. Otherwise, it is resolved.
236 *
237 * @return an array of {@code Type}s that represent the formal
238 * parameter types of the underlying method, in declaration order
239 * @throws GenericSignatureFormatError
240 * if the generic method signature does not conform to the format
241 * specified in the Java Virtual Machine Specification, 3rd edition
242 * @throws TypeNotPresentException if any of the parameter
243 * types of the underlying method refers to a non-existent type
244 * declaration
245 * @throws MalformedParameterizedTypeException if any of
246 * the underlying method's parameter types refer to a parameterized
247 * type that cannot be instantiated for any reason
248 * @since 1.5
249 */
250 public Type[] getGenericParameterTypes() {
251 if (getSignature() != null)
252 return getGenericInfo().getParameterTypes();
253 else
254 return getParameterTypes();
255 }
256
257
258 /**
259 * Returns an array of {@code Class} objects that represent the types
260 * of exceptions declared to be thrown by the underlying constructor
261 * represented by this {@code Constructor} object. Returns an array of
262 * length 0 if the constructor declares no exceptions in its {@code throws} clause.
263 *
264 * @return the exception types declared as being thrown by the
265 * constructor this object represents
266 */
267 public Class<?>[] getExceptionTypes() {
268 return (Class<?>[])exceptionTypes.clone();
269 }
270
271
272 /**
273 * Returns an array of {@code Type} objects that represent the
274 * exceptions declared to be thrown by this {@code Constructor} object.
275 * Returns an array of length 0 if the underlying method declares
276 * no exceptions in its {@code throws} clause.
277 *
278 * <p>If an exception type is a parameterized type, the {@code Type}
279 * object returned for it must accurately reflect the actual type
280 * parameters used in the source code.
281 *
282 * <p>If an exception type is a type variable or a parameterized
283 * type, it is created. Otherwise, it is resolved.
284 *
285 * @return an array of Types that represent the exception types
286 * thrown by the underlying method
287 * @throws GenericSignatureFormatError
288 * if the generic method signature does not conform to the format
289 * specified in the Java Virtual Machine Specification, 3rd edition
290 * @throws TypeNotPresentException if the underlying method's
291 * {@code throws} clause refers to a non-existent type declaration
292 * @throws MalformedParameterizedTypeException if
293 * the underlying method's {@code throws} clause refers to a
294 * parameterized type that cannot be instantiated for any reason
295 * @since 1.5
296 */
297 public Type[] getGenericExceptionTypes() {
298 Type[] result;
299 if (getSignature() != null &&
300 ( (result = getGenericInfo().getExceptionTypes()).length > 0 ))
301 return result;
302 else
303 return getExceptionTypes();
304 }
305
306 /**
307 * Compares this {@code Constructor} against the specified object.
308 * Returns true if the objects are the same. Two {@code Constructor} objects are
309 * the same if they were declared by the same class and have the
310 * same formal parameter types.
311 */
312 public boolean equals(Object obj) {
313 if (obj != null && obj instanceof Constructor) {
314 Constructor other = (Constructor)obj;
315 if (getDeclaringClass() == other.getDeclaringClass()) {
316 /* Avoid unnecessary cloning */
317 Class[] params1 = parameterTypes;
318 Class[] params2 = other.parameterTypes;
319 if (params1.length == params2.length) {
320 for (int i = 0; i < params1.length; i++) {
321 if (params1[i] != params2[i])
322 return false;
323 }
324 return true;
325 }
326 }
327 }
328 return false;
329 }
330
331 /**
332 * Returns a hashcode for this {@code Constructor}. The hashcode is
333 * the same as the hashcode for the underlying constructor's
334 * declaring class name.
335 */
336 public int hashCode() {
337 return getDeclaringClass().getName().hashCode();
338 }
339
340 /**
341 * Returns a string describing this {@code Constructor}. The string is
342 * formatted as the constructor access modifiers, if any,
343 * followed by the fully-qualified name of the declaring class,
344 * followed by a parenthesized, comma-separated list of the
345 * constructor's formal parameter types. For example:
346 * <pre>
347 * public java.util.Hashtable(int,float)
348 * </pre>
349 *
350 * <p>The only possible modifiers for constructors are the access
351 * modifiers {@code public}, {@code protected} or
352 * {@code private}. Only one of these may appear, or none if the
353 * constructor has default (package) access.
354 */
355 public String toString() {
356 try {
357 StringBuffer sb = new StringBuffer();
358 int mod = getModifiers() & Modifier.constructorModifiers();
359 if (mod != 0) {
360 sb.append(Modifier.toString(mod) + " ");
361 }
362 sb.append(Field.getTypeName(getDeclaringClass()));
363 sb.append("(");
364 Class[] params = parameterTypes; // avoid clone
365 for (int j = 0; j < params.length; j++) {
366 sb.append(Field.getTypeName(params[j]));
367 if (j < (params.length - 1))
368 sb.append(",");
369 }
370 sb.append(")");
371 Class[] exceptions = exceptionTypes; // avoid clone
372 if (exceptions.length > 0) {
373 sb.append(" throws ");
374 for (int k = 0; k < exceptions.length; k++) {
375 sb.append(exceptions[k].getName());
376 if (k < (exceptions.length - 1))
377 sb.append(",");
378 }
379 }
380 return sb.toString();
381 } catch (Exception e) {
382 return "<" + e + ">";
383 }
384 }
385
386 /**
387 * Returns a string describing this {@code Constructor},
388 * including type parameters. The string is formatted as the
389 * constructor access modifiers, if any, followed by an
390 * angle-bracketed comma separated list of the constructor's type
391 * parameters, if any, followed by the fully-qualified name of the
392 * declaring class, followed by a parenthesized, comma-separated
393 * list of the constructor's generic formal parameter types.
394 *
395 * If this constructor was declared to take a variable number of
396 * arguments, instead of denoting the last parameter as
397 * "<tt><i>Type</i>[]</tt>", it is denoted as
398 * "<tt><i>Type</i>...</tt>".
399 *
400 * A space is used to separate access modifiers from one another
401 * and from the type parameters or return type. If there are no
402 * type parameters, the type parameter list is elided; if the type
403 * parameter list is present, a space separates the list from the
404 * class name. If the constructor is declared to throw
405 * exceptions, the parameter list is followed by a space, followed
406 * by the word "{@code throws}" followed by a
407 * comma-separated list of the thrown exception types.
408 *
409 * <p>The only possible modifiers for constructors are the access
410 * modifiers {@code public}, {@code protected} or
411 * {@code private}. Only one of these may appear, or none if the
412 * constructor has default (package) access.
413 *
414 * @return a string describing this {@code Constructor},
415 * include type parameters
416 *
417 * @since 1.5
418 */
419 public String toGenericString() {
420 try {
421 StringBuilder sb = new StringBuilder();
422 int mod = getModifiers() & Modifier.constructorModifiers();
423 if (mod != 0) {
424 sb.append(Modifier.toString(mod) + " ");
425 }
426 TypeVariable<?>[] typeparms = getTypeParameters();
427 if (typeparms.length > 0) {
428 boolean first = true;
429 sb.append("<");
430 for(TypeVariable<?> typeparm: typeparms) {
431 if (!first)
432 sb.append(",");
433 // Class objects can't occur here; no need to test
434 // and call Class.getName().
435 sb.append(typeparm.toString());
436 first = false;
437 }
438 sb.append("> ");
439 }
440 sb.append(Field.getTypeName(getDeclaringClass()));
441 sb.append("(");
442 Type[] params = getGenericParameterTypes();
443 for (int j = 0; j < params.length; j++) {
444 String param = (params[j] instanceof Class<?>)?
445 Field.getTypeName((Class<?>)params[j]):
446 (params[j].toString());
447 if (isVarArgs() && (j == params.length - 1)) // replace T[] with T...
448 param = param.replaceFirst("\\[\\]$", "...");
449 sb.append(param);
450 if (j < (params.length - 1))
451 sb.append(",");
452 }
453 sb.append(")");
454 Type[] exceptions = getGenericExceptionTypes();
455 if (exceptions.length > 0) {
456 sb.append(" throws ");
457 for (int k = 0; k < exceptions.length; k++) {
458 sb.append((exceptions[k] instanceof Class)?
459 ((Class)exceptions[k]).getName():
460 exceptions[k].toString());
461 if (k < (exceptions.length - 1))
462 sb.append(",");
463 }
464 }
465 return sb.toString();
466 } catch (Exception e) {
467 return "<" + e + ">";
468 }
469 }
470
471 /**
472 * Uses the constructor represented by this {@code Constructor} object to
473 * create and initialize a new instance of the constructor's
474 * declaring class, with the specified initialization parameters.
475 * Individual parameters are automatically unwrapped to match
476 * primitive formal parameters, and both primitive and reference
477 * parameters are subject to method invocation conversions as necessary.
478 *
479 * <p>If the number of formal parameters required by the underlying constructor
480 * is 0, the supplied {@code initargs} array may be of length 0 or null.
481 *
482 * <p>If the constructor's declaring class is an inner class in a
483 * non-static context, the first argument to the constructor needs
484 * to be the enclosing instance; see <i>The Java Language
485 * Specification</i>, section 15.9.3.
486 *
487 * <p>If the required access and argument checks succeed and the
488 * instantiation will proceed, the constructor's declaring class
489 * is initialized if it has not already been initialized.
490 *
491 * <p>If the constructor completes normally, returns the newly
492 * created and initialized instance.
493 *
494 * @param initargs array of objects to be passed as arguments to
495 * the constructor call; values of primitive types are wrapped in
496 * a wrapper object of the appropriate type (e.g. a {@code float}
497 * in a {@link java.lang.Float Float})
498 *
499 * @return a new object created by calling the constructor
500 * this object represents
501 *
502 * @exception IllegalAccessException if this {@code Constructor} object
503 * enforces Java language access control and the underlying
504 * constructor is inaccessible.
505 * @exception IllegalArgumentException if the number of actual
506 * and formal parameters differ; if an unwrapping
507 * conversion for primitive arguments fails; or if,
508 * after possible unwrapping, a parameter value
509 * cannot be converted to the corresponding formal
510 * parameter type by a method invocation conversion; if
511 * this constructor pertains to an enum type.
512 * @exception InstantiationException if the class that declares the
513 * underlying constructor represents an abstract class.
514 * @exception InvocationTargetException if the underlying constructor
515 * throws an exception.
516 * @exception ExceptionInInitializerError if the initialization provoked
517 * by this method fails.
518 */
519 public T newInstance(Object ... initargs)
520 throws InstantiationException, IllegalAccessException,
521 IllegalArgumentException, InvocationTargetException
522 {
523 if (!override) {
524 if (!Reflection.quickCheckMemberAccess(clazz, modifiers)) {
525 Class caller = Reflection.getCallerClass(2);
526 if (securityCheckCache != caller) {
527 Reflection.ensureMemberAccess(caller, clazz, null, modifiers);
528 securityCheckCache = caller;
529 }
530 }
531 }
532 if ((clazz.getModifiers() & Modifier.ENUM) != 0)
533 throw new IllegalArgumentException("Cannot reflectively create enum objects");
534 if (constructorAccessor == null) acquireConstructorAccessor();
535 return (T) constructorAccessor.newInstance(initargs);
536 }
537
538 /**
539 * Returns {@code true} if this constructor was declared to take
540 * a variable number of arguments; returns {@code false}
541 * otherwise.
542 *
543 * @return {@code true} if an only if this constructor was declared to
544 * take a variable number of arguments.
545 * @since 1.5
546 */
547 public boolean isVarArgs() {
548 return (getModifiers() & Modifier.VARARGS) != 0;
549 }
550
551 /**
552 * Returns {@code true} if this constructor is a synthetic
553 * constructor; returns {@code false} otherwise.
554 *
555 * @return true if and only if this constructor is a synthetic
556 * constructor as defined by the Java Language Specification.
557 * @since 1.5
558 */
559 public boolean isSynthetic() {
560 return Modifier.isSynthetic(getModifiers());
561 }
562
563 // NOTE that there is no synchronization used here. It is correct
564 // (though not efficient) to generate more than one
565 // ConstructorAccessor for a given Constructor. However, avoiding
566 // synchronization will probably make the implementation more
567 // scalable.
568 private void acquireConstructorAccessor() {
569 // First check to see if one has been created yet, and take it
570 // if so.
571 ConstructorAccessor tmp = null;
572 if (root != null) tmp = root.getConstructorAccessor();
573 if (tmp != null) {
574 constructorAccessor = tmp;
575 return;
576 }
577 // Otherwise fabricate one and propagate it up to the root
578 tmp = reflectionFactory.newConstructorAccessor(this);
579 setConstructorAccessor(tmp);
580 }
581
582 // Returns ConstructorAccessor for this Constructor object, not
583 // looking up the chain to the root
584 ConstructorAccessor getConstructorAccessor() {
585 return constructorAccessor;
586 }
587
588 // Sets the ConstructorAccessor for this Constructor object and
589 // (recursively) its root
590 void setConstructorAccessor(ConstructorAccessor accessor) {
591 constructorAccessor = accessor;
592 // Propagate up
593 if (root != null) {
594 root.setConstructorAccessor(accessor);
595 }
596 }
597
598 int getSlot() {
599 return slot;
600 }
601
602 String getSignature() {
603 return signature;
604 }
605
606 byte[] getRawAnnotations() {
607 return annotations;
608 }
609
610 byte[] getRawParameterAnnotations() {
611 return parameterAnnotations;
612 }
613
614 /**
615 * @throws NullPointerException {@inheritDoc}
616 * @since 1.5
617 */
618 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
619 if (annotationClass == null)
620 throw new NullPointerException();
621
622 return (T) declaredAnnotations().get(annotationClass);
623 }
624
625 /**
626 * @since 1.5
627 */
628 public Annotation[] getDeclaredAnnotations() {
629 return AnnotationParser.toArray(declaredAnnotations());
630 }
631
632 private transient Map<Class, Annotation> declaredAnnotations;
633
634 private synchronized Map<Class, Annotation> declaredAnnotations() {
635 if (declaredAnnotations == null) {
636 declaredAnnotations = AnnotationParser.parseAnnotations(
637 annotations, sun.misc.SharedSecrets.getJavaLangAccess().
638 getConstantPool(getDeclaringClass()),
639 getDeclaringClass());
640 }
641 return declaredAnnotations;
642 }
643
644 /**
645 * Returns an array of arrays that represent the annotations on the formal
646 * parameters, in declaration order, of the method represented by
647 * this {@code Constructor} object. (Returns an array of length zero if the
648 * underlying method is parameterless. If the method has one or more
649 * parameters, a nested array of length zero is returned for each parameter
650 * with no annotations.) The annotation objects contained in the returned
651 * arrays are serializable. The caller of this method is free to modify
652 * the returned arrays; it will have no effect on the arrays returned to
653 * other callers.
654 *
655 * @return an array of arrays that represent the annotations on the formal
656 * parameters, in declaration order, of the method represented by this
657 * Constructor object
658 * @since 1.5
659 */
660 public Annotation[][] getParameterAnnotations() {
661 int numParameters = parameterTypes.length;
662 if (parameterAnnotations == null)
663 return new Annotation[numParameters][0];
664
665 Annotation[][] result = AnnotationParser.parseParameterAnnotations(
666 parameterAnnotations,
667 sun.misc.SharedSecrets.getJavaLangAccess().
668 getConstantPool(getDeclaringClass()),
669 getDeclaringClass());
670 if (result.length != numParameters) {
671 Class<?> declaringClass = getDeclaringClass();
672 if (declaringClass.isEnum() ||
673 declaringClass.isAnonymousClass() ||
674 declaringClass.isLocalClass() )
675 ; // Can't do reliable parameter counting
676 else {
677 if (!declaringClass.isMemberClass() || // top-level
678 // Check for the enclosing instance parameter for
679 // non-static member classes
680 (declaringClass.isMemberClass() &&
681 ((declaringClass.getModifiers() & Modifier.STATIC) == 0) &&
682 result.length + 1 != numParameters) ) {
683 throw new AnnotationFormatError(
684 "Parameter annotations don't match number of parameters");
685 }
686 }
687 }
688 return result;
689 }
690 }