1 /* java.lang.reflect.Method - reflection of Java methods
2 Copyright (C) 1998, 2001, 2002, 2005, 2007, 2008 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
39 package java.lang.reflect;
41 import gnu.java.lang.ClassHelper;
42 import gnu.java.lang.CPStringBuilder;
44 import gnu.java.lang.reflect.MethodSignatureParser;
46 import java.lang.annotation.Annotation;
49 * The Method class represents a member method of a class. It also allows
50 * dynamic invocation, via reflection. This works for both static and
51 * instance methods. Invocation on Method objects knows how to do
52 * widening conversions, but throws {@link IllegalArgumentException} if
53 * a narrowing conversion would be necessary. You can query for information
54 * on this Method regardless of location, but invocation access may be limited
55 * by Java language access controls. If you can't do it in the compiler, you
56 * can't normally do it here either.<p>
58 * <B>Note:</B> This class returns and accepts types as Classes, even
59 * primitive types; there are Class types defined that represent each
60 * different primitive type. They are <code>java.lang.Boolean.TYPE,
61 * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
62 * byte.class</code>, etc. These are not to be confused with the
63 * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
66 * Also note that this is not a serializable class. It is entirely feasible
67 * to make it serializable using the Externalizable interface, but this is
71 * @author Eric Blake <ebb9@email.byu.edu>
74 * @see java.lang.Class#getMethod(String,Class[])
75 * @see java.lang.Class#getDeclaredMethod(String,Class[])
76 * @see java.lang.Class#getMethods()
77 * @see java.lang.Class#getDeclaredMethods()
79 * @status updated to 1.4
81 public final class Method
82 extends AccessibleObject implements Member, GenericDeclaration
84 private static final int METHOD_MODIFIERS
85 = Modifier.ABSTRACT | Modifier.FINAL | Modifier.NATIVE
86 | Modifier.PRIVATE | Modifier.PROTECTED | Modifier.PUBLIC
87 | Modifier.STATIC | Modifier.STRICT | Modifier.SYNCHRONIZED;
89 private MethodSignatureParser p;
94 * This class is uninstantiable outside this package.
103 * Gets the class that declared this method, or the class where this method
104 * is a non-inherited member.
105 * @return the class that declared this member
107 @SuppressWarnings("unchecked")
108 public Class<?> getDeclaringClass()
110 return (Class<?>) m.getDeclaringClass();
114 * Gets the name of this method.
115 * @return the name of this method
117 public String getName()
123 * Gets the modifiers this method uses. Use the <code>Modifier</code>
124 * class to interpret the values. A method can only have a subset of the
125 * following modifiers: public, private, protected, abstract, static,
126 * final, synchronized, native, and strictfp.
128 * @return an integer representing the modifiers to this Member
131 public int getModifiers()
133 return m.getModifiersInternal() & METHOD_MODIFIERS;
137 * Return true if this method is a bridge method. A bridge method
138 * is generated by the compiler in some situations involving
139 * generics and inheritance.
142 public boolean isBridge()
144 return (m.getModifiersInternal() & Modifier.BRIDGE) != 0;
148 * Return true if this method is synthetic, false otherwise.
151 public boolean isSynthetic()
153 return (m.getModifiersInternal() & Modifier.SYNTHETIC) != 0;
157 * Return true if this is a varargs method, that is if
158 * the method takes a variable number of arguments.
161 public boolean isVarArgs()
163 return (m.getModifiersInternal() & Modifier.VARARGS) != 0;
167 * Gets the return type of this method.
168 * @return the type of this method
170 @SuppressWarnings("unchecked")
171 public Class<?> getReturnType()
173 return (Class<?>) m.getReturnType();
177 * Get the parameter list for this method, in declaration order. If the
178 * method takes no parameters, returns a 0-length array (not null).
180 * @return a list of the types of the method's parameters
182 @SuppressWarnings("unchecked")
183 public Class<?>[] getParameterTypes()
185 return (Class<?>[]) m.getParameterTypes();
189 * Get the exception types this method says it throws, in no particular
190 * order. If the method has no throws clause, returns a 0-length array
193 * @return a list of the types in the method's throws clause
195 @SuppressWarnings("unchecked")
196 public Class<?>[] getExceptionTypes()
198 return (Class<?>[]) m.getExceptionTypes();
202 * Compare two objects to see if they are semantically equivalent.
203 * Two Methods are semantically equivalent if they have the same declaring
204 * class, name, parameter list, and return type.
206 * @param o the object to compare to
207 * @return <code>true</code> if they are equal; <code>false</code> if not
209 public boolean equals(Object o)
215 * Get the hash code for the Method. The Method hash code is the hash code
216 * of its name XOR'd with the hash code of its class name.
218 * @return the hash code for the object
220 public int hashCode()
222 return m.getDeclaringClass().getName().hashCode() ^ m.getName().hashCode();
226 * Get a String representation of the Method. A Method's String
227 * representation is "<modifiers> <returntype>
228 * <methodname>(<paramtypes>) throws <exceptions>", where
229 * everything after ')' is omitted if there are no exceptions.<br> Example:
230 * <code>public static int run(java.lang.Runnable,int)</code>
232 * @return the String representation of the Method
234 public String toString()
236 // 128 is a reasonable buffer initial size for constructor
237 CPStringBuilder sb = new CPStringBuilder(128);
238 Modifier.toString(getModifiers(), sb).append(' ');
239 sb.append(ClassHelper.getUserName(getReturnType())).append(' ');
240 sb.append(getDeclaringClass().getName()).append('.');
241 sb.append(getName()).append('(');
242 Class[] c = getParameterTypes();
245 sb.append(ClassHelper.getUserName(c[0]));
246 for (int i = 1; i < c.length; i++)
247 sb.append(',').append(ClassHelper.getUserName(c[i]));
250 c = getExceptionTypes();
253 sb.append(" throws ").append(c[0].getName());
254 for (int i = 1; i < c.length; i++)
255 sb.append(',').append(c[i].getName());
257 return sb.toString();
260 public String toGenericString()
262 // 128 is a reasonable buffer initial size for constructor
263 CPStringBuilder sb = new CPStringBuilder(128);
264 Modifier.toString(getModifiers(), sb).append(' ');
265 Constructor.addTypeParameters(sb, getTypeParameters());
266 sb.append(getGenericReturnType()).append(' ');
267 sb.append(getDeclaringClass().getName()).append('.');
268 sb.append(getName()).append('(');
269 Type[] types = getGenericParameterTypes();
270 if (types.length > 0)
273 for (int i = 1; i < types.length; i++)
274 sb.append(',').append(types[i]);
277 types = getGenericExceptionTypes();
278 if (types.length > 0)
280 sb.append(" throws ").append(types[0]);
281 for (int i = 1; i < types.length; i++)
282 sb.append(',').append(types[i]);
284 return sb.toString();
288 * Invoke the method. Arguments are automatically unwrapped and widened,
289 * and the result is automatically wrapped, if needed.<p>
291 * If the method is static, <code>o</code> will be ignored. Otherwise,
292 * the method uses dynamic lookup as described in JLS 15.12.4.4. You cannot
293 * mimic the behavior of nonvirtual lookup (as in super.foo()). This means
294 * you will get a <code>NullPointerException</code> if <code>o</code> is
295 * null, and an <code>IllegalArgumentException</code> if it is incompatible
296 * with the declaring class of the method. If the method takes 0 arguments,
297 * you may use null or a 0-length array for <code>args</code>.<p>
299 * Next, if this Method enforces access control, your runtime context is
300 * evaluated, and you may have an <code>IllegalAccessException</code> if
301 * you could not acces this method in similar compiled code. If the method
302 * is static, and its class is uninitialized, you trigger class
303 * initialization, which may end in a
304 * <code>ExceptionInInitializerError</code>.<p>
306 * Finally, the method is invoked. If it completes normally, the return value
307 * will be null for a void method, a wrapped object for a primitive return
308 * method, or the actual return of an Object method. If it completes
309 * abruptly, the exception is wrapped in an
310 * <code>InvocationTargetException</code>.
312 * @param o the object to invoke the method on
313 * @param args the arguments to the method
314 * @return the return value of the method, wrapped in the appropriate
315 * wrapper if it is primitive
316 * @throws IllegalAccessException if the method could not normally be called
317 * by the Java code (i.e. it is not public)
318 * @throws IllegalArgumentException if the number of arguments is incorrect;
319 * if the arguments types are wrong even with a widening conversion;
320 * or if <code>o</code> is not an instance of the class or interface
321 * declaring this method
322 * @throws InvocationTargetException if the method throws an exception
323 * @throws NullPointerException if <code>o</code> is null and this field
324 * requires an instance
325 * @throws ExceptionInInitializerError if accessing a static method triggered
326 * class initialization, which then failed
328 public Object invoke(Object o, Object... args)
329 throws IllegalAccessException, InvocationTargetException
331 return m.invoke(o, args);
335 * Returns an array of <code>TypeVariable</code> objects that represents
336 * the type variables declared by this constructor, in declaration order.
337 * An array of size zero is returned if this class has no type
340 * @return the type variables associated with this class.
341 * @throws GenericSignatureFormatError if the generic signature does
342 * not conform to the format specified in the Virtual Machine
343 * specification, version 3.
346 public TypeVariable<Method>[] getTypeParameters()
350 String sig = m.getSignature();
352 return (TypeVariable<Method>[]) new TypeVariable[0];
353 p = new MethodSignatureParser(this, sig);
355 return p.getTypeParameters();
359 * Returns an array of <code>Type</code> objects that represents
360 * the exception types declared by this method, in declaration order.
361 * An array of size zero is returned if this method declares no
364 * @return the exception types declared by this method.
365 * @throws GenericSignatureFormatError if the generic signature does
366 * not conform to the format specified in the Virtual Machine
367 * specification, version 3.
370 public Type[] getGenericExceptionTypes()
374 String sig = m.getSignature();
376 return getExceptionTypes();
377 p = new MethodSignatureParser(this, sig);
379 return p.getGenericExceptionTypes();
383 * Returns an array of <code>Type</code> objects that represents
384 * the parameter list for this method, in declaration order.
385 * An array of size zero is returned if this method takes no
388 * @return a list of the types of the method's parameters
389 * @throws GenericSignatureFormatError if the generic signature does
390 * not conform to the format specified in the Virtual Machine
391 * specification, version 3.
394 public Type[] getGenericParameterTypes()
398 String sig = m.getSignature();
400 return getParameterTypes();
401 p = new MethodSignatureParser(this, sig);
403 return p.getGenericParameterTypes();
407 * Returns the return type of this method.
409 * @return the return type of this method
410 * @throws GenericSignatureFormatError if the generic signature does
411 * not conform to the format specified in the Virtual Machine
412 * specification, version 3.
415 public Type getGenericReturnType()
419 String sig = m.getSignature();
421 return getReturnType();
422 p = new MethodSignatureParser(this, sig);
424 return p.getGenericReturnType();
428 * If this method is an annotation method, returns the default
429 * value for the method. If there is no default value, or if the
430 * method is not a member of an annotation type, returns null.
431 * Primitive types are wrapped.
433 * @throws TypeNotPresentException if the method returns a Class,
434 * and the class cannot be found
438 public Object getDefaultValue()
440 return m.getDefaultValue();
445 * Return an array of arrays representing the annotations on each
446 * of the method's parameters. The outer array is aligned against
447 * the parameters of the method and is thus equal in length to
448 * the number of parameters (thus having a length zero if there are none).
449 * Each array element in the outer array contains an inner array which
450 * holds the annotations. This array has a length of zero if the parameter
451 * has no annotations.
454 * The returned annotations are serialized. Changing the annotations has
455 * no affect on the return value of future calls to this method.
458 * @return an array of arrays which represents the annotations used on the
459 * parameters of this method. The order of the array elements
460 * matches the declaration order of the parameters.
463 public Annotation[][] getParameterAnnotations()
465 return m.getParameterAnnotations();
469 * Returns the element's annotation for the specified annotation type,
470 * or <code>null</code> if no such annotation exists.
472 * @param annotationClass the type of annotation to look for.
473 * @return this element's annotation for the specified type, or
474 * <code>null</code> if no such annotation exists.
475 * @throws NullPointerException if the annotation class is <code>null</code>.
477 @SuppressWarnings("unchecked")
478 public <T extends Annotation> T getAnnotation(Class<T> annotationClass)
480 return (T) m.getAnnotation(annotationClass);
484 * Returns all annotations directly defined by the element. If there are
485 * no annotations directly associated with the element, then a zero-length
486 * array will be returned. The returned array may be modified by the client
487 * code, but this will have no effect on the annotation content of this
488 * class, and hence no effect on the return value of this method for
491 * @return the annotations directly defined by the element.
494 public Annotation[] getDeclaredAnnotations()
496 return m.getDeclaredAnnotations();