libjava/java/lang/reflect/Method.java

   1 // Method.java - Represent method of class or interface.
   2
   3 /* Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003  Free Software Foundation
   4
   5    This file is part of libgcj.
   6
   7 This software is copyrighted work licensed under the terms of the
   8 Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
   9 details.  */
  10
  11 package java.lang.reflect;
  12
  13 import gnu.gcj.RawData;
  14
  15 /**
  16  * The Method class represents a member method of a class. It also allows
  17  * dynamic invocation, via reflection. This works for both static and
  18  * instance methods. Invocation on Method objects knows how to do
  19  * widening conversions, but throws {@link IllegalArgumentException} if
  20  * a narrowing conversion would be necessary. You can query for information
  21  * on this Method regardless of location, but invocation access may be limited
  22  * by Java language access controls. If you can't do it in the compiler, you
  23  * can't normally do it here either.<p>
  24  *
  25  * <B>Note:</B> This class returns and accepts types as Classes, even
  26  * primitive types; there are Class types defined that represent each
  27  * different primitive type.  They are <code>java.lang.Boolean.TYPE,
  28  * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
  29  * byte.class</code>, etc.  These are not to be confused with the
  30  * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
  31  * real classes.<p>
  32  *
  33  * Also note that this is not a serializable class.  It is entirely feasible
  34  * to make it serializable using the Externalizable interface, but this is
  35  * on Sun, not me.
  36  *
  37  * @author John Keiser
  38  * @author Eric Blake <ebb9@email.byu.edu>
  39  * @author Tom Tromey <tromey@redhat.com>
  40  * @see Member
  41  * @see Class
  42  * @see java.lang.Class#getMethod(String,Object[])
  43  * @see java.lang.Class#getDeclaredMethod(String,Object[])
  44  * @see java.lang.Class#getMethods()
  45  * @see java.lang.Class#getDeclaredMethods()
  46  * @since 1.1
  47  * @status updated to 1.4
  48  */
  49 public final class Method extends AccessibleObject implements Member
  50 {
  51   /**
  52    * This class is uninstantiable.
  53    */
  54   private Method ()
  55   {
  56   }
  57
  58   /**
  59    * Gets the class that declared this method, or the class where this method
  60    * is a non-inherited member.
  61    * @return the class that declared this member
  62    */
  63   public Class getDeclaringClass ()
  64   {
  65     return declaringClass;
  66   }
  67
  68   /**
  69    * Gets the name of this method.
  70    * @return the name of this method
  71    */
  72   public native String getName ();
  73
  74   /**
  75    * Gets the modifiers this method uses.  Use the <code>Modifier</code>
  76    * class to interpret the values.  A method can only have a subset of the
  77    * following modifiers: public, private, protected, abstract, static,
  78    * final, synchronized, native, and strictfp.
  79    *
  80    * @return an integer representing the modifiers to this Member
  81    * @see Modifier
  82    */
  83   public native int getModifiers ();
  84
  85   /**
  86    * Gets the return type of this method.
  87    * @return the type of this method
  88    */
  89   public Class getReturnType ()
  90   {
  91     if (return_type == null)
  92       getType();
  93     return return_type;
  94   }
  95
  96   /**
  97    * Get the parameter list for this method, in declaration order. If the
  98    * method takes no parameters, returns a 0-length array (not null).
  99    *
 100    * @return a list of the types of the method's parameters
 101    */
 102   public Class[] getParameterTypes ()
 103   {
 104     if (parameter_types == null)
 105       getType();
 106     return (Class[]) parameter_types.clone();
 107   }
 108
 109   /**
 110    * Get the exception types this method says it throws, in no particular
 111    * order. If the method has no throws clause, returns a 0-length array
 112    * (not null).
 113    *
 114    * @return a list of the types in the method's throws clause
 115    */
 116   public Class[] getExceptionTypes ()
 117   {
 118     if (exception_types == null)
 119       getType();
 120     return (Class[]) exception_types.clone();
 121   }
 122
 123   /**
 124    * Compare two objects to see if they are semantically equivalent.
 125    * Two Methods are semantically equivalent if they have the same declaring
 126    * class, name, and parameter list.  This ignores different exception
 127    * clauses or return types.
 128    *
 129    * @param o the object to compare to
 130    * @return <code>true</code> if they are equal; <code>false</code> if not
 131    */
 132   public boolean equals (Object obj)
 133   {
 134     if (! (obj instanceof Method))
 135       return false;
 136     Method m = (Method) obj;
 137     return declaringClass == m.declaringClass && offset == m.offset;
 138   }
 139
 140   /**
 141    * Get the hash code for the Method.
 142    *
 143    * @return the hash code for the object
 144    */
 145   public int hashCode ()
 146   {
 147     // FIXME.
 148     return getName().hashCode() + declaringClass.getName().hashCode();
 149   }
 150
 151   /**
 152    * Get a String representation of the Method. A Method's String
 153    * representation is "&lt;modifiers&gt; &lt;returntype&gt;
 154    * &lt;methodname&gt;(&lt;paramtypes&gt;) throws &lt;exceptions&gt;", where
 155    * everything after ')' is omitted if there are no exceptions.<br> Example:
 156    * <code>public static int run(java.lang.Runnable,int)</code>
 157    *
 158    * @return the String representation of the Method
 159    */
 160   public String toString ()
 161   {
 162     if (parameter_types == null)
 163       getType ();
 164
 165     StringBuffer b = new StringBuffer ();
 166     int mods = getModifiers();
 167     if (mods != 0)
 168       {
 169         Modifier.toString(mods, b);
 170         b.append(" ");
 171       }
 172     appendClassName (b, return_type);
 173     b.append(" ");
 174     appendClassName (b, declaringClass);
 175     b.append(".");
 176     b.append(getName());
 177     b.append("(");
 178     for (int i = 0; i < parameter_types.length; ++i)
 179       {
 180         appendClassName (b, parameter_types[i]);
 181         if (i < parameter_types.length - 1)
 182           b.append(",");
 183       }
 184     b.append(")");
 185     if (exception_types.length > 0)
 186       {
 187         b.append(" throws ");
 188         for (int i = 0; i < exception_types.length; ++i)
 189           {
 190             appendClassName (b, exception_types[i]);
 191             if (i < exception_types.length - 1)
 192               b.append(",");
 193           }
 194       }
 195     return b.toString();
 196   }
 197
 198   /**
 199    * Invoke the method. Arguments are automatically unwrapped and widened,
 200    * and the result is automatically wrapped, if needed.<p>
 201    *
 202    * If the method is static, <code>o</code> will be ignored. Otherwise,
 203    * the method uses dynamic lookup as described in JLS 15.12.4.4. You cannot
 204    * mimic the behavior of nonvirtual lookup (as in super.foo()). This means
 205    * you will get a <code>NullPointerException</code> if <code>o</code> is
 206    * null, and an <code>IllegalArgumentException</code> if it is incompatible
 207    * with the declaring class of the method. If the method takes 0 arguments,
 208    * you may use null or a 0-length array for <code>args</code>.<p>
 209    *
 210    * Next, if this Method enforces access control, your runtime context is
 211    * evaluated, and you may have an <code>IllegalAccessException</code> if
 212    * you could not acces this method in similar compiled code. If the method
 213    * is static, and its class is uninitialized, you trigger class
 214    * initialization, which may end in a
 215    * <code>ExceptionInInitializerError</code>.<p>
 216    *
 217    * Finally, the method is invoked. If it completes normally, the return value
 218    * will be null for a void method, a wrapped object for a primitive return
 219    * method, or the actual return of an Object method. If it completes
 220    * abruptly, the exception is wrapped in an
 221    * <code>InvocationTargetException</code>.
 222    *
 223    * @param o the object to invoke the method on
 224    * @param args the arguments to the method
 225    * @return the return value of the method, wrapped in the appropriate
 226    *         wrapper if it is primitive
 227    * @throws IllegalAccessException if the method could not normally be called
 228    *         by the Java code (i.e. it is not public)
 229    * @throws IllegalArgumentException if the number of arguments is incorrect;
 230    *         if the arguments types are wrong even with a widening conversion;
 231    *         or if <code>o</code> is not an instance of the class or interface
 232    *         declaring this method
 233    * @throws InvocationTargetException if the method throws an exception
 234    * @throws NullPointerException if <code>o</code> is null and this field
 235    *         requires an instance
 236    * @throws ExceptionInInitializerError if accessing a static method triggered
 237    *         class initialization, which then failed
 238    */
 239   public native Object invoke (Object obj, Object[] args)
 240     throws IllegalAccessException, IllegalArgumentException,
 241     InvocationTargetException;
 242
 243   private native void getType ();
 244
 245   // Append a class name to a string buffer.  We try to print the
 246   // fully-qualified name, the way that a Java programmer would expect
 247   // it to be written.  Weirdly, Class has no appropriate method for
 248   // this.
 249   static void appendClassName (StringBuffer buf, Class k)
 250   {
 251     if (k.isArray ())
 252       {
 253         appendClassName (buf, k.getComponentType ());
 254         buf.append ("[]");
 255       }
 256     else
 257       {
 258         // This is correct for primitive and reference types.  Really
 259         // we'd like `Main$Inner' to be printed as `Main.Inner', I
 260         // think, but that is a pain.
 261         buf.append (k.getName ());
 262       }
 263   }
 264
 265   // Declaring class.
 266   private Class declaringClass;
 267
 268   // Exception types.
 269   private Class[] exception_types;
 270   // Name cache.  (Initially null.)
 271   private String name;
 272   // Parameter types.
 273   private Class[] parameter_types;
 274   // Return type.
 275   private Class return_type;
 276
 277   // Offset in bytes from the start of declaringClass's methods array.
 278   private int offset;
 279 }