src/classes/gnu/java/lang/reflect/Method.java

   1 /* java.lang.reflect.Method - reflection of Java methods
   2    Copyright (C) 1998, 2001, 2002, 2005, 2007, 2008 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   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)
   9 any later version.
  10
  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.
  15
  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
  19 02110-1301 USA.
  20
  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
  24 combination.
  25
  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. */
  37
  38
  39 package java.lang.reflect;
  40
  41 import gnu.java.lang.ClassHelper;
  42 import gnu.java.lang.CPStringBuilder;
  43
  44 import gnu.java.lang.reflect.MethodSignatureParser;
  45
  46 import java.lang.annotation.Annotation;
  47
  48 /**
  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>
  57  *
  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
  64  * real classes.<p>
  65  *
  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
  68  * on Sun, not me.
  69  *
  70  * @author John Keiser
  71  * @author Eric Blake <ebb9@email.byu.edu>
  72  * @see Member
  73  * @see Class
  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()
  78  * @since 1.1
  79  * @status updated to 1.4
  80  */
  81 public final class Method
  82 extends AccessibleObject implements Member, GenericDeclaration
  83 {
  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;
  88
  89   private MethodSignatureParser p;
  90
  91   VMMethod m;
  92
  93   /**
  94    * This class is uninstantiable outside this package.
  95    */
  96   Method(VMMethod m)
  97   {
  98     this.m = m;
  99     m.m = this;
 100   }
 101
 102   /**
 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
 106    */
 107   @SuppressWarnings("unchecked")
 108   public Class<?> getDeclaringClass()
 109   {
 110     return (Class<?>) m.getDeclaringClass();
 111   }
 112
 113   /**
 114    * Gets the name of this method.
 115    * @return the name of this method
 116    */
 117   public String getName()
 118   {
 119     return m.getName();
 120   }
 121
 122   /**
 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.
 127    *
 128    * @return an integer representing the modifiers to this Member
 129    * @see Modifier
 130    */
 131   public int getModifiers()
 132   {
 133     return m.getModifiersInternal() & METHOD_MODIFIERS;
 134   }
 135
 136   /**
 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.
 140    * @since 1.5
 141    */
 142   public boolean isBridge()
 143   {
 144     return (m.getModifiersInternal() & Modifier.BRIDGE) != 0;
 145   }
 146
 147   /**
 148    * Return true if this method is synthetic, false otherwise.
 149    * @since 1.5
 150    */
 151   public boolean isSynthetic()
 152   {
 153     return (m.getModifiersInternal() & Modifier.SYNTHETIC) != 0;
 154   }
 155
 156   /**
 157    * Return true if this is a varargs method, that is if
 158    * the method takes a variable number of arguments.
 159    * @since 1.5
 160    */
 161   public boolean isVarArgs()
 162   {
 163     return (m.getModifiersInternal() & Modifier.VARARGS) != 0;
 164   }
 165
 166   /**
 167    * Gets the return type of this method.
 168    * @return the type of this method
 169    */
 170   @SuppressWarnings("unchecked")
 171   public Class<?> getReturnType()
 172   {
 173     return (Class<?>) m.getReturnType();
 174   }
 175
 176   /**
 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).
 179    *
 180    * @return a list of the types of the method's parameters
 181    */
 182   @SuppressWarnings("unchecked")
 183   public Class<?>[] getParameterTypes()
 184   {
 185     return (Class<?>[]) m.getParameterTypes();
 186   }
 187
 188   /**
 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
 191    * (not null).
 192    *
 193    * @return a list of the types in the method's throws clause
 194    */
 195   @SuppressWarnings("unchecked")
 196   public Class<?>[] getExceptionTypes()
 197   {
 198     return (Class<?>[]) m.getExceptionTypes();
 199   }
 200
 201   /**
 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.
 205    *
 206    * @param o the object to compare to
 207    * @return <code>true</code> if they are equal; <code>false</code> if not
 208    */
 209   public boolean equals(Object o)
 210   {
 211     return m.equals(o);
 212   }
 213
 214   /**
 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.
 217    *
 218    * @return the hash code for the object
 219    */
 220   public int hashCode()
 221   {
 222     return m.getDeclaringClass().getName().hashCode() ^ m.getName().hashCode();
 223   }
 224
 225   /**
 226    * Get a String representation of the Method. A Method's String
 227    * representation is "&lt;modifiers&gt; &lt;returntype&gt;
 228    * &lt;methodname&gt;(&lt;paramtypes&gt;) throws &lt;exceptions&gt;", where
 229    * everything after ')' is omitted if there are no exceptions.<br> Example:
 230    * <code>public static int run(java.lang.Runnable,int)</code>
 231    *
 232    * @return the String representation of the Method
 233    */
 234   public String toString()
 235   {
 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();
 243     if (c.length > 0)
 244       {
 245         sb.append(ClassHelper.getUserName(c[0]));
 246         for (int i = 1; i < c.length; i++)
 247           sb.append(',').append(ClassHelper.getUserName(c[i]));
 248       }
 249     sb.append(')');
 250     c = getExceptionTypes();
 251     if (c.length > 0)
 252       {
 253         sb.append(" throws ").append(c[0].getName());
 254         for (int i = 1; i < c.length; i++)
 255           sb.append(',').append(c[i].getName());
 256       }
 257     return sb.toString();
 258   }
 259
 260   public String toGenericString()
 261   {
 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)
 271       {
 272         sb.append(types[0]);
 273         for (int i = 1; i < types.length; i++)
 274           sb.append(',').append(types[i]);
 275       }
 276     sb.append(')');
 277     types = getGenericExceptionTypes();
 278     if (types.length > 0)
 279       {
 280         sb.append(" throws ").append(types[0]);
 281         for (int i = 1; i < types.length; i++)
 282           sb.append(',').append(types[i]);
 283       }
 284     return sb.toString();
 285   }
 286
 287   /**
 288    * Invoke the method. Arguments are automatically unwrapped and widened,
 289    * and the result is automatically wrapped, if needed.<p>
 290    *
 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>
 298    *
 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>
 305    *
 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>.
 311    *
 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
 327    */
 328   public Object invoke(Object o, Object... args)
 329     throws IllegalAccessException, InvocationTargetException
 330   {
 331     return m.invoke(o, args);
 332   }
 333
 334   /**
 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
 338    * variables.
 339    *
 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.
 344    * @since 1.5
 345    */
 346   public TypeVariable<Method>[] getTypeParameters()
 347   {
 348     if (p == null)
 349       {
 350         String sig = m.getSignature();
 351         if (sig == null)
 352           return (TypeVariable<Method>[]) new TypeVariable[0];
 353         p = new MethodSignatureParser(this, sig);
 354       }
 355     return p.getTypeParameters();
 356   }
 357
 358   /**
 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
 362    * exceptions.
 363    *
 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.
 368    * @since 1.5
 369    */
 370   public Type[] getGenericExceptionTypes()
 371   {
 372     if (p == null)
 373       {
 374         String sig = m.getSignature();
 375         if (sig == null)
 376           return getExceptionTypes();
 377         p = new MethodSignatureParser(this, sig);
 378       }
 379     return p.getGenericExceptionTypes();
 380   }
 381
 382   /**
 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
 386    * parameters.
 387    *
 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.
 392    * @since 1.5
 393    */
 394   public Type[] getGenericParameterTypes()
 395   {
 396     if (p == null)
 397       {
 398         String sig = m.getSignature();
 399         if (sig == null)
 400           return getParameterTypes();
 401         p = new MethodSignatureParser(this, sig);
 402       }
 403     return p.getGenericParameterTypes();
 404   }
 405
 406   /**
 407    * Returns the return type of this method.
 408    *
 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.
 413    * @since 1.5
 414    */
 415   public Type getGenericReturnType()
 416   {
 417     if (p == null)
 418       {
 419         String sig = m.getSignature();
 420         if (sig == null)
 421           return getReturnType();
 422         p = new MethodSignatureParser(this, sig);
 423       }
 424     return p.getGenericReturnType();
 425   }
 426
 427   /**
 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.
 432    *
 433    * @throws TypeNotPresentException if the method returns a Class,
 434    * and the class cannot be found
 435    *
 436    * @since 1.5
 437    */
 438   public Object getDefaultValue()
 439   {
 440     return m.getDefaultValue();
 441   }
 442
 443   /**
 444    * <p>
 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.
 452    * </p>
 453    * <p>
 454    * The returned annotations are serialized.  Changing the annotations has
 455    * no affect on the return value of future calls to this method.
 456    * </p>
 457    *
 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.
 461    * @since 1.5
 462    */
 463   public Annotation[][] getParameterAnnotations()
 464   {
 465     return m.getParameterAnnotations();
 466   }
 467
 468   /**
 469    * Returns the element's annotation for the specified annotation type,
 470    * or <code>null</code> if no such annotation exists.
 471    *
 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>.
 476    */
 477   @SuppressWarnings("unchecked")
 478   public <T extends Annotation> T getAnnotation(Class<T> annotationClass)
 479   {
 480     return (T) m.getAnnotation(annotationClass);
 481   }
 482
 483   /**
 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
 489    * future callers.
 490    *
 491    * @return the annotations directly defined by the element.
 492    * @since 1.5
 493    */
 494   public Annotation[] getDeclaredAnnotations()
 495   {
 496     return m.getDeclaredAnnotations();
 497   }
 498
 499 }