View Javadoc
1   /*
2    * Copyright (c) 1996, 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  
26  package java.lang.reflect;
27  
28  import sun.reflect.CallerSensitive;
29  import sun.reflect.MethodAccessor;
30  import sun.reflect.Reflection;
31  import sun.reflect.generics.repository.MethodRepository;
32  import sun.reflect.generics.factory.CoreReflectionFactory;
33  import sun.reflect.generics.factory.GenericsFactory;
34  import sun.reflect.generics.scope.MethodScope;
35  import sun.reflect.annotation.AnnotationType;
36  import sun.reflect.annotation.AnnotationParser;
37  import java.lang.annotation.Annotation;
38  import java.lang.annotation.AnnotationFormatError;
39  import java.nio.ByteBuffer;
40  
41  /**
42   * A {@code Method} provides information about, and access to, a single method
43   * on a class or interface.  The reflected method may be a class method
44   * or an instance method (including an abstract method).
45   *
46   * <p>A {@code Method} permits widening conversions to occur when matching the
47   * actual parameters to invoke with the underlying method's formal
48   * parameters, but it throws an {@code IllegalArgumentException} if a
49   * narrowing conversion would occur.
50   *
51   * @see Member
52   * @see java.lang.Class
53   * @see java.lang.Class#getMethods()
54   * @see java.lang.Class#getMethod(String, Class[])
55   * @see java.lang.Class#getDeclaredMethods()
56   * @see java.lang.Class#getDeclaredMethod(String, Class[])
57   *
58   * @author Kenneth Russell
59   * @author Nakul Saraiya
60   */
61  public final class Method extends Executable {
62      private Class<?>            clazz;
63      private int                 slot;
64      // This is guaranteed to be interned by the VM in the 1.4
65      // reflection implementation
66      private String              name;
67      private Class<?>            returnType;
68      private Class<?>[]          parameterTypes;
69      private Class<?>[]          exceptionTypes;
70      private int                 modifiers;
71      // Generics and annotations support
72      private transient String              signature;
73      // generic info repository; lazily initialized
74      private transient MethodRepository genericInfo;
75      private byte[]              annotations;
76      private byte[]              parameterAnnotations;
77      private byte[]              annotationDefault;
78      private volatile MethodAccessor methodAccessor;
79      // For sharing of MethodAccessors. This branching structure is
80      // currently only two levels deep (i.e., one root Method and
81      // potentially many Method objects pointing to it.)
82      private Method              root;
83  
84      // Generics infrastructure
85      private String getGenericSignature() {return signature;}
86  
87      // Accessor for factory
88      private GenericsFactory getFactory() {
89          // create scope and factory
90          return CoreReflectionFactory.make(this, MethodScope.make(this));
91      }
92  
93      // Accessor for generic info repository
94      @Override
95      MethodRepository getGenericInfo() {
96          // lazily initialize repository if necessary
97          if (genericInfo == null) {
98              // create and cache generic info repository
99              genericInfo = MethodRepository.make(getGenericSignature(),
100                                                 getFactory());
101         }
102         return genericInfo; //return cached repository
103     }
104 
105     /**
106      * Package-private constructor used by ReflectAccess to enable
107      * instantiation of these objects in Java code from the java.lang
108      * package via sun.reflect.LangReflectAccess.
109      */
110     Method(Class<?> declaringClass,
111            String name,
112            Class<?>[] parameterTypes,
113            Class<?> returnType,
114            Class<?>[] checkedExceptions,
115            int modifiers,
116            int slot,
117            String signature,
118            byte[] annotations,
119            byte[] parameterAnnotations,
120            byte[] annotationDefault) {
121         this.clazz = declaringClass;
122         this.name = name;
123         this.parameterTypes = parameterTypes;
124         this.returnType = returnType;
125         this.exceptionTypes = checkedExceptions;
126         this.modifiers = modifiers;
127         this.slot = slot;
128         this.signature = signature;
129         this.annotations = annotations;
130         this.parameterAnnotations = parameterAnnotations;
131         this.annotationDefault = annotationDefault;
132     }
133 
134     /**
135      * Package-private routine (exposed to java.lang.Class via
136      * ReflectAccess) which returns a copy of this Method. The copy's
137      * "root" field points to this Method.
138      */
139     Method copy() {
140         // This routine enables sharing of MethodAccessor objects
141         // among Method 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         Method res = new Method(clazz, name, parameterTypes, returnType,
148                                 exceptionTypes, modifiers, slot, signature,
149                                 annotations, parameterAnnotations, annotationDefault);
150         res.root = this;
151         // Might as well eagerly propagate this if already present
152         res.methodAccessor = methodAccessor;
153         return res;
154     }
155 
156     @Override
157     boolean hasGenericInformation() {
158         return (getGenericSignature() != null);
159     }
160 
161     @Override
162     byte[] getAnnotationBytes() {
163         return annotations;
164     }
165 
166     /**
167      * {@inheritDoc}
168      */
169     @Override
170     public Class<?> getDeclaringClass() {
171         return clazz;
172     }
173 
174     /**
175      * Returns the name of the method represented by this {@code Method}
176      * object, as a {@code String}.
177      */
178     @Override
179     public String getName() {
180         return name;
181     }
182 
183     /**
184      * {@inheritDoc}
185      */
186     @Override
187     public int getModifiers() {
188         return modifiers;
189     }
190 
191     /**
192      * {@inheritDoc}
193      * @throws GenericSignatureFormatError {@inheritDoc}
194      * @since 1.5
195      */
196     @Override
197     @SuppressWarnings({"rawtypes", "unchecked"})
198     public TypeVariable<Method>[] getTypeParameters() {
199         if (getGenericSignature() != null)
200             return (TypeVariable<Method>[])getGenericInfo().getTypeParameters();
201         else
202             return (TypeVariable<Method>[])new TypeVariable[0];
203     }
204 
205     /**
206      * Returns a {@code Class} object that represents the formal return type
207      * of the method represented by this {@code Method} object.
208      *
209      * @return the return type for the method this object represents
210      */
211     public Class<?> getReturnType() {
212         return returnType;
213     }
214 
215     /**
216      * Returns a {@code Type} object that represents the formal return
217      * type of the method represented by this {@code Method} object.
218      *
219      * <p>If the return type is a parameterized type,
220      * the {@code Type} object returned must accurately reflect
221      * the actual type parameters used in the source code.
222      *
223      * <p>If the return type is a type variable or a parameterized type, it
224      * is created. Otherwise, it is resolved.
225      *
226      * @return  a {@code Type} object that represents the formal return
227      *     type of the underlying  method
228      * @throws GenericSignatureFormatError
229      *     if the generic method signature does not conform to the format
230      *     specified in
231      *     <cite>The Java&trade; Virtual Machine Specification</cite>
232      * @throws TypeNotPresentException if the underlying method's
233      *     return type refers to a non-existent type declaration
234      * @throws MalformedParameterizedTypeException if the
235      *     underlying method's return typed refers to a parameterized
236      *     type that cannot be instantiated for any reason
237      * @since 1.5
238      */
239     public Type getGenericReturnType() {
240       if (getGenericSignature() != null) {
241         return getGenericInfo().getReturnType();
242       } else { return getReturnType();}
243     }
244 
245     /**
246      * {@inheritDoc}
247      */
248     @Override
249     public Class<?>[] getParameterTypes() {
250         return parameterTypes.clone();
251     }
252 
253     /**
254      * {@inheritDoc}
255      */
256     public int getParameterCount() { return parameterTypes.length; }
257 
258 
259     /**
260      * {@inheritDoc}
261      * @throws GenericSignatureFormatError {@inheritDoc}
262      * @throws TypeNotPresentException {@inheritDoc}
263      * @throws MalformedParameterizedTypeException {@inheritDoc}
264      * @since 1.5
265      */
266     @Override
267     public Type[] getGenericParameterTypes() {
268         return super.getGenericParameterTypes();
269     }
270 
271     /**
272      * {@inheritDoc}
273      */
274     @Override
275     public Class<?>[] getExceptionTypes() {
276         return exceptionTypes.clone();
277     }
278 
279     /**
280      * {@inheritDoc}
281      * @throws GenericSignatureFormatError {@inheritDoc}
282      * @throws TypeNotPresentException {@inheritDoc}
283      * @throws MalformedParameterizedTypeException {@inheritDoc}
284      * @since 1.5
285      */
286     @Override
287     public Type[] getGenericExceptionTypes() {
288         return super.getGenericExceptionTypes();
289     }
290 
291     /**
292      * Compares this {@code Method} against the specified object.  Returns
293      * true if the objects are the same.  Two {@code Methods} are the same if
294      * they were declared by the same class and have the same name
295      * and formal parameter types and return type.
296      */
297     public boolean equals(Object obj) {
298         if (obj != null && obj instanceof Method) {
299             Method other = (Method)obj;
300             if ((getDeclaringClass() == other.getDeclaringClass())
301                 && (getName() == other.getName())) {
302                 if (!returnType.equals(other.getReturnType()))
303                     return false;
304                 return equalParamTypes(parameterTypes, other.parameterTypes);
305             }
306         }
307         return false;
308     }
309 
310     /**
311      * Returns a hashcode for this {@code Method}.  The hashcode is computed
312      * as the exclusive-or of the hashcodes for the underlying
313      * method's declaring class name and the method's name.
314      */
315     public int hashCode() {
316         return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
317     }
318 
319     /**
320      * Returns a string describing this {@code Method}.  The string is
321      * formatted as the method access modifiers, if any, followed by
322      * the method return type, followed by a space, followed by the
323      * class declaring the method, followed by a period, followed by
324      * the method name, followed by a parenthesized, comma-separated
325      * list of the method's formal parameter types. If the method
326      * throws checked exceptions, the parameter list is followed by a
327      * space, followed by the word throws followed by a
328      * comma-separated list of the thrown exception types.
329      * For example:
330      * <pre>
331      *    public boolean java.lang.Object.equals(java.lang.Object)
332      * </pre>
333      *
334      * <p>The access modifiers are placed in canonical order as
335      * specified by "The Java Language Specification".  This is
336      * {@code public}, {@code protected} or {@code private} first,
337      * and then other modifiers in the following order:
338      * {@code abstract}, {@code default}, {@code static}, {@code final},
339      * {@code synchronized}, {@code native}, {@code strictfp}.
340      *
341      * @return a string describing this {@code Method}
342      *
343      * @jls 8.4.3 Method Modifiers
344      */
345     public String toString() {
346         return sharedToString(Modifier.methodModifiers(),
347                               isDefault(),
348                               parameterTypes,
349                               exceptionTypes);
350     }
351 
352     @Override
353     void specificToStringHeader(StringBuilder sb) {
354         sb.append(getReturnType().getTypeName()).append(' ');
355         sb.append(getDeclaringClass().getTypeName()).append('.');
356         sb.append(getName());
357     }
358 
359     /**
360      * Returns a string describing this {@code Method}, including
361      * type parameters.  The string is formatted as the method access
362      * modifiers, if any, followed by an angle-bracketed
363      * comma-separated list of the method's type parameters, if any,
364      * followed by the method's generic return type, followed by a
365      * space, followed by the class declaring the method, followed by
366      * a period, followed by the method name, followed by a
367      * parenthesized, comma-separated list of the method's generic
368      * formal parameter types.
369      *
370      * If this method was declared to take a variable number of
371      * arguments, instead of denoting the last parameter as
372      * "<tt><i>Type</i>[]</tt>", it is denoted as
373      * "<tt><i>Type</i>...</tt>".
374      *
375      * A space is used to separate access modifiers from one another
376      * and from the type parameters or return type.  If there are no
377      * type parameters, the type parameter list is elided; if the type
378      * parameter list is present, a space separates the list from the
379      * class name.  If the method is declared to throw exceptions, the
380      * parameter list is followed by a space, followed by the word
381      * throws followed by a comma-separated list of the generic thrown
382      * exception types.
383      *
384      * <p>The access modifiers are placed in canonical order as
385      * specified by "The Java Language Specification".  This is
386      * {@code public}, {@code protected} or {@code private} first,
387      * and then other modifiers in the following order:
388      * {@code abstract}, {@code default}, {@code static}, {@code final},
389      * {@code synchronized}, {@code native}, {@code strictfp}.
390      *
391      * @return a string describing this {@code Method},
392      * include type parameters
393      *
394      * @since 1.5
395      *
396      * @jls 8.4.3 Method Modifiers
397      */
398     @Override
399     public String toGenericString() {
400         return sharedToGenericString(Modifier.methodModifiers(), isDefault());
401     }
402 
403     @Override
404     void specificToGenericStringHeader(StringBuilder sb) {
405         Type genRetType = getGenericReturnType();
406         sb.append(genRetType.getTypeName()).append(' ');
407         sb.append(getDeclaringClass().getTypeName()).append('.');
408         sb.append(getName());
409     }
410 
411     /**
412      * Invokes the underlying method represented by this {@code Method}
413      * object, on the specified object with the specified parameters.
414      * Individual parameters are automatically unwrapped to match
415      * primitive formal parameters, and both primitive and reference
416      * parameters are subject to method invocation conversions as
417      * necessary.
418      *
419      * <p>If the underlying method is static, then the specified {@code obj}
420      * argument is ignored. It may be null.
421      *
422      * <p>If the number of formal parameters required by the underlying method is
423      * 0, the supplied {@code args} array may be of length 0 or null.
424      *
425      * <p>If the underlying method is an instance method, it is invoked
426      * using dynamic method lookup as documented in The Java Language
427      * Specification, Second Edition, section 15.12.4.4; in particular,
428      * overriding based on the runtime type of the target object will occur.
429      *
430      * <p>If the underlying method is static, the class that declared
431      * the method is initialized if it has not already been initialized.
432      *
433      * <p>If the method completes normally, the value it returns is
434      * returned to the caller of invoke; if the value has a primitive
435      * type, it is first appropriately wrapped in an object. However,
436      * if the value has the type of an array of a primitive type, the
437      * elements of the array are <i>not</i> wrapped in objects; in
438      * other words, an array of primitive type is returned.  If the
439      * underlying method return type is void, the invocation returns
440      * null.
441      *
442      * @param obj  the object the underlying method is invoked from
443      * @param args the arguments used for the method call
444      * @return the result of dispatching the method represented by
445      * this object on {@code obj} with parameters
446      * {@code args}
447      *
448      * @exception IllegalAccessException    if this {@code Method} object
449      *              is enforcing Java language access control and the underlying
450      *              method is inaccessible.
451      * @exception IllegalArgumentException  if the method is an
452      *              instance method and the specified object argument
453      *              is not an instance of the class or interface
454      *              declaring the underlying method (or of a subclass
455      *              or implementor thereof); if the number of actual
456      *              and formal parameters differ; if an unwrapping
457      *              conversion for primitive arguments fails; or if,
458      *              after possible unwrapping, a parameter value
459      *              cannot be converted to the corresponding formal
460      *              parameter type by a method invocation conversion.
461      * @exception InvocationTargetException if the underlying method
462      *              throws an exception.
463      * @exception NullPointerException      if the specified object is null
464      *              and the method is an instance method.
465      * @exception ExceptionInInitializerError if the initialization
466      * provoked by this method fails.
467      */
468     @CallerSensitive
469     public Object invoke(Object obj, Object... args)
470         throws IllegalAccessException, IllegalArgumentException,
471            InvocationTargetException
472     {
473         if (!override) {
474             if (!Reflection.quickCheckMemberAccess(clazz, modifiers)) {
475                 Class<?> caller = Reflection.getCallerClass();
476                 checkAccess(caller, clazz, obj, modifiers);
477             }
478         }
479         MethodAccessor ma = methodAccessor;             // read volatile
480         if (ma == null) {
481             ma = acquireMethodAccessor();
482         }
483         return ma.invoke(obj, args);
484     }
485 
486     /**
487      * Returns {@code true} if this method is a bridge
488      * method; returns {@code false} otherwise.
489      *
490      * @return true if and only if this method is a bridge
491      * method as defined by the Java Language Specification.
492      * @since 1.5
493      */
494     public boolean isBridge() {
495         return (getModifiers() & Modifier.BRIDGE) != 0;
496     }
497 
498     /**
499      * {@inheritDoc}
500      * @since 1.5
501      */
502     @Override
503     public boolean isVarArgs() {
504         return super.isVarArgs();
505     }
506 
507     /**
508      * {@inheritDoc}
509      * @jls 13.1 The Form of a Binary
510      * @since 1.5
511      */
512     @Override
513     public boolean isSynthetic() {
514         return super.isSynthetic();
515     }
516 
517     /**
518      * Returns {@code true} if this method is a default
519      * method; returns {@code false} otherwise.
520      *
521      * A default method is a public non-abstract instance method, that
522      * is, a non-static method with a body, declared in an interface
523      * type.
524      *
525      * @return true if and only if this method is a default
526      * method as defined by the Java Language Specification.
527      * @since 1.8
528      */
529     public boolean isDefault() {
530         // Default methods are public non-abstract instance methods
531         // declared in an interface.
532         return ((getModifiers() & (Modifier.ABSTRACT | Modifier.PUBLIC | Modifier.STATIC)) ==
533                 Modifier.PUBLIC) && getDeclaringClass().isInterface();
534     }
535 
536     // NOTE that there is no synchronization used here. It is correct
537     // (though not efficient) to generate more than one MethodAccessor
538     // for a given Method. However, avoiding synchronization will
539     // probably make the implementation more scalable.
540     private MethodAccessor acquireMethodAccessor() {
541         // First check to see if one has been created yet, and take it
542         // if so
543         MethodAccessor tmp = null;
544         if (root != null) tmp = root.getMethodAccessor();
545         if (tmp != null) {
546             methodAccessor = tmp;
547         } else {
548             // Otherwise fabricate one and propagate it up to the root
549             tmp = reflectionFactory.newMethodAccessor(this);
550             setMethodAccessor(tmp);
551         }
552 
553         return tmp;
554     }
555 
556     // Returns MethodAccessor for this Method object, not looking up
557     // the chain to the root
558     MethodAccessor getMethodAccessor() {
559         return methodAccessor;
560     }
561 
562     // Sets the MethodAccessor for this Method object and
563     // (recursively) its root
564     void setMethodAccessor(MethodAccessor accessor) {
565         methodAccessor = accessor;
566         // Propagate up
567         if (root != null) {
568             root.setMethodAccessor(accessor);
569         }
570     }
571 
572     /**
573      * Returns the default value for the annotation member represented by
574      * this {@code Method} instance.  If the member is of a primitive type,
575      * an instance of the corresponding wrapper type is returned. Returns
576      * null if no default is associated with the member, or if the method
577      * instance does not represent a declared member of an annotation type.
578      *
579      * @return the default value for the annotation member represented
580      *     by this {@code Method} instance.
581      * @throws TypeNotPresentException if the annotation is of type
582      *     {@link Class} and no definition can be found for the
583      *     default class value.
584      * @since  1.5
585      */
586     public Object getDefaultValue() {
587         if  (annotationDefault == null)
588             return null;
589         Class<?> memberType = AnnotationType.invocationHandlerReturnType(
590             getReturnType());
591         Object result = AnnotationParser.parseMemberValue(
592             memberType, ByteBuffer.wrap(annotationDefault),
593             sun.misc.SharedSecrets.getJavaLangAccess().
594                 getConstantPool(getDeclaringClass()),
595             getDeclaringClass());
596         if (result instanceof sun.reflect.annotation.ExceptionProxy)
597             throw new AnnotationFormatError("Invalid default: " + this);
598         return result;
599     }
600 
601     /**
602      * {@inheritDoc}
603      * @throws NullPointerException  {@inheritDoc}
604      * @since 1.5
605      */
606     public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
607         return super.getAnnotation(annotationClass);
608     }
609 
610     /**
611      * {@inheritDoc}
612      * @since 1.5
613      */
614     public Annotation[] getDeclaredAnnotations()  {
615         return super.getDeclaredAnnotations();
616     }
617 
618     /**
619      * {@inheritDoc}
620      * @since 1.5
621      */
622     @Override
623     public Annotation[][] getParameterAnnotations() {
624         return sharedGetParameterAnnotations(parameterTypes, parameterAnnotations);
625     }
626 
627     /**
628      * {@inheritDoc}
629      * @since 1.8
630      */
631     @Override
632     public AnnotatedType getAnnotatedReturnType() {
633         return getAnnotatedReturnType0(getGenericReturnType());
634     }
635 
636     @Override
637     void handleParameterNumberMismatch(int resultLength, int numParameters) {
638         throw new AnnotationFormatError("Parameter annotations don't match number of parameters");
639     }
640 }