1 /* java.lang.reflect.Method - reflection of Java methods
2 Copyright (C) 1998, 2001, 2002, 2005, 2007 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;
43 import gnu.java.lang.reflect.MethodSignatureParser;
45 import java.util.Arrays;
48 * The Method class represents a member method of a class. It also allows
49 * dynamic invocation, via reflection. This works for both static and
50 * instance methods. Invocation on Method objects knows how to do
51 * widening conversions, but throws {@link IllegalArgumentException} if
52 * a narrowing conversion would be necessary. You can query for information
53 * on this Method regardless of location, but invocation access may be limited
54 * by Java language access controls. If you can't do it in the compiler, you
55 * can't normally do it here either.<p>
57 * <B>Note:</B> This class returns and accepts types as Classes, even
58 * primitive types; there are Class types defined that represent each
59 * different primitive type. They are <code>java.lang.Boolean.TYPE,
60 * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
61 * byte.class</code>, etc. These are not to be confused with the
62 * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
65 * Also note that this is not a serializable class. It is entirely feasible
66 * to make it serializable using the Externalizable interface, but this is
70 * @author Eric Blake <ebb9@email.byu.edu>
73 * @see java.lang.Class#getMethod(String,Class[])
74 * @see java.lang.Class#getDeclaredMethod(String,Class[])
75 * @see java.lang.Class#getMethods()
76 * @see java.lang.Class#getDeclaredMethods()
78 * @status updated to 1.4
80 public final class Method
81 extends AccessibleObject implements Member, GenericDeclaration
86 private byte[] annotations;
87 private byte[] parameterAnnotations;
88 private byte[] annotationDefault;
90 private static final int METHOD_MODIFIERS
91 = Modifier.ABSTRACT | Modifier.FINAL | Modifier.NATIVE
92 | Modifier.PRIVATE | Modifier.PROTECTED | Modifier.PUBLIC
93 | Modifier.STATIC | Modifier.STRICT | Modifier.SYNCHRONIZED;
96 * This class is uninstantiable.
98 private Method(Class declaringClass, String name, int slot)
100 this.clazz = declaringClass;
106 * Gets the class that declared this method, or the class where this method
107 * is a non-inherited member.
108 * @return the class that declared this member
110 public Class<?> getDeclaringClass()
116 * Gets the name of this method.
117 * @return the name of this method
119 public String getName()
125 * Return the raw modifiers for this method.
126 * @return the method's modifiers
128 private native int getModifiersInternal();
131 * Gets the modifiers this method uses. Use the <code>Modifier</code>
132 * class to interpret the values. A method can only have a subset of the
133 * following modifiers: public, private, protected, abstract, static,
134 * final, synchronized, native, and strictfp.
136 * @return an integer representing the modifiers to this Member
139 public int getModifiers()
141 return getModifiersInternal() & METHOD_MODIFIERS;
145 * Return true if this method is a bridge method. A bridge method
146 * is generated by the compiler in some situations involving
147 * generics and inheritance.
150 public boolean isBridge()
152 return (getModifiersInternal() & Modifier.BRIDGE) != 0;
156 * Return true if this method is synthetic, false otherwise.
159 public boolean isSynthetic()
161 return (getModifiersInternal() & Modifier.SYNTHETIC) != 0;
165 * Return true if this is a varargs method, that is if
166 * the method takes a variable number of arguments.
169 public boolean isVarArgs()
171 return (getModifiersInternal() & Modifier.VARARGS) != 0;
175 * Gets the return type of this method.
176 * @return the type of this method
178 public native Class<?> getReturnType();
181 * Get the parameter list for this method, in declaration order. If the
182 * method takes no parameters, returns a 0-length array (not null).
184 * @return a list of the types of the method's parameters
186 public native Class<?>[] 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 public native Class<?>[] getExceptionTypes();
198 * Compare two objects to see if they are semantically equivalent.
199 * Two Methods are semantically equivalent if they have the same declaring
200 * class, name, parameter list, and return type.
202 * @param o the object to compare to
203 * @return <code>true</code> if they are equal; <code>false</code> if not
205 public boolean equals(Object o)
207 // Implementation note:
208 // The following is a correct but possibly slow implementation.
210 // This class has a private field 'slot' that could be used by
211 // the VM implementation to "link" a particular method to a Class.
212 // In that case equals could be simply implemented as:
214 // if (o instanceof Method)
216 // Method m = (Method)o;
217 // return m.clazz == this.clazz
218 // && m.slot == this.slot;
222 // If a VM uses the Method class as their native/internal representation
223 // then just using the following would be optimal:
227 if (!(o instanceof Method))
229 Method that = (Method)o;
230 if (this.getDeclaringClass() != that.getDeclaringClass())
232 if (!this.getName().equals(that.getName()))
234 if (this.getReturnType() != that.getReturnType())
236 if (!Arrays.equals(this.getParameterTypes(), that.getParameterTypes()))
242 * Get the hash code for the Method. The Method hash code is the hash code
243 * of its name XOR'd with the hash code of its class name.
245 * @return the hash code for the object
247 public int hashCode()
249 return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
253 * Get a String representation of the Method. A Method's String
254 * representation is "<modifiers> <returntype>
255 * <methodname>(<paramtypes>) throws <exceptions>", where
256 * everything after ')' is omitted if there are no exceptions.<br> Example:
257 * <code>public static int run(java.lang.Runnable,int)</code>
259 * @return the String representation of the Method
261 public String toString()
263 // 128 is a reasonable buffer initial size for constructor
264 StringBuilder sb = new StringBuilder(128);
265 Modifier.toString(getModifiers(), sb).append(' ');
266 sb.append(ClassHelper.getUserName(getReturnType())).append(' ');
267 sb.append(getDeclaringClass().getName()).append('.');
268 sb.append(getName()).append('(');
269 Class[] c = getParameterTypes();
272 sb.append(ClassHelper.getUserName(c[0]));
273 for (int i = 1; i < c.length; i++)
274 sb.append(',').append(ClassHelper.getUserName(c[i]));
277 c = getExceptionTypes();
280 sb.append(" throws ").append(c[0].getName());
281 for (int i = 1; i < c.length; i++)
282 sb.append(',').append(c[i].getName());
284 return sb.toString();
287 public String toGenericString()
289 // 128 is a reasonable buffer initial size for constructor
290 StringBuilder sb = new StringBuilder(128);
291 Modifier.toString(getModifiers(), sb).append(' ');
292 Constructor.addTypeParameters(sb, getTypeParameters());
293 sb.append(getGenericReturnType()).append(' ');
294 sb.append(getDeclaringClass().getName()).append('.');
295 sb.append(getName()).append('(');
296 Type[] types = getGenericParameterTypes();
297 if (types.length > 0)
300 for (int i = 1; i < types.length; i++)
301 sb.append(',').append(types[i]);
304 types = getGenericExceptionTypes();
305 if (types.length > 0)
307 sb.append(" throws ").append(types[0]);
308 for (int i = 1; i < types.length; i++)
309 sb.append(',').append(types[i]);
311 return sb.toString();
315 * Invoke the method. Arguments are automatically unwrapped and widened,
316 * and the result is automatically wrapped, if needed.<p>
318 * If the method is static, <code>o</code> will be ignored. Otherwise,
319 * the method uses dynamic lookup as described in JLS 15.12.4.4. You cannot
320 * mimic the behavior of nonvirtual lookup (as in super.foo()). This means
321 * you will get a <code>NullPointerException</code> if <code>o</code> is
322 * null, and an <code>IllegalArgumentException</code> if it is incompatible
323 * with the declaring class of the method. If the method takes 0 arguments,
324 * you may use null or a 0-length array for <code>args</code>.<p>
326 * Next, if this Method enforces access control, your runtime context is
327 * evaluated, and you may have an <code>IllegalAccessException</code> if
328 * you could not acces this method in similar compiled code. If the method
329 * is static, and its class is uninitialized, you trigger class
330 * initialization, which may end in a
331 * <code>ExceptionInInitializerError</code>.<p>
333 * Finally, the method is invoked. If it completes normally, the return value
334 * will be null for a void method, a wrapped object for a primitive return
335 * method, or the actual return of an Object method. If it completes
336 * abruptly, the exception is wrapped in an
337 * <code>InvocationTargetException</code>.
339 * @param o the object to invoke the method on
340 * @param args the arguments to the method
341 * @return the return value of the method, wrapped in the appropriate
342 * wrapper if it is primitive
343 * @throws IllegalAccessException if the method could not normally be called
344 * by the Java code (i.e. it is not public)
345 * @throws IllegalArgumentException if the number of arguments is incorrect;
346 * if the arguments types are wrong even with a widening conversion;
347 * or if <code>o</code> is not an instance of the class or interface
348 * declaring this method
349 * @throws InvocationTargetException if the method throws an exception
350 * @throws NullPointerException if <code>o</code> is null and this field
351 * requires an instance
352 * @throws ExceptionInInitializerError if accessing a static method triggered
353 * class initialization, which then failed
355 public Object invoke(Object o, Object... args)
356 throws IllegalAccessException, InvocationTargetException
358 return invokeNative(o, args, clazz, slot);
365 private native Object invokeNative(Object o, Object[] args,
366 Class declaringClass, int slot)
367 throws IllegalAccessException, InvocationTargetException;
370 * Returns an array of <code>TypeVariable</code> objects that represents
371 * the type variables declared by this constructor, in declaration order.
372 * An array of size zero is returned if this class has no type
375 * @return the type variables associated with this class.
376 * @throws GenericSignatureFormatError if the generic signature does
377 * not conform to the format specified in the Virtual Machine
378 * specification, version 3.
381 public TypeVariable<Method>[] getTypeParameters()
383 String sig = getSignature();
385 return new TypeVariable[0];
386 MethodSignatureParser p = new MethodSignatureParser(this, sig);
387 return p.getTypeParameters();
391 * Return the String in the Signature attribute for this method. If there
392 * is no Signature attribute, return null.
394 private native String getSignature();
397 * Returns an array of <code>Type</code> objects that represents
398 * the exception types declared by this method, in declaration order.
399 * An array of size zero is returned if this method declares no
402 * @return the exception types declared by this method.
403 * @throws GenericSignatureFormatError if the generic signature does
404 * not conform to the format specified in the Virtual Machine
405 * specification, version 3.
408 public Type[] getGenericExceptionTypes()
410 String sig = getSignature();
412 return getExceptionTypes();
413 MethodSignatureParser p = new MethodSignatureParser(this, sig);
414 return p.getGenericExceptionTypes();
418 * Returns an array of <code>Type</code> objects that represents
419 * the parameter list for this method, in declaration order.
420 * An array of size zero is returned if this method takes no
423 * @return a list of the types of the method's parameters
424 * @throws GenericSignatureFormatError if the generic signature does
425 * not conform to the format specified in the Virtual Machine
426 * specification, version 3.
429 public Type[] getGenericParameterTypes()
431 String sig = getSignature();
433 return getParameterTypes();
434 MethodSignatureParser p = new MethodSignatureParser(this, sig);
435 return p.getGenericParameterTypes();
439 * Returns the return type of this method.
441 * @return the return type of this method
442 * @throws GenericSignatureFormatError if the generic signature does
443 * not conform to the format specified in the Virtual Machine
444 * specification, version 3.
447 public Type getGenericReturnType()
449 String sig = getSignature();
451 return getReturnType();
452 MethodSignatureParser p = new MethodSignatureParser(this, sig);
453 return p.getGenericReturnType();
457 * If this method is an annotation method, returns the default
458 * value for the method. If there is no default value, or if the
459 * method is not a member of an annotation type, returns null.
460 * Primitive types are wrapped.
462 * @throws TypeNotPresentException if the method returns a Class,
463 * and the class cannot be found
467 public native Object getDefaultValue();