Source for java.lang.reflect.Method

   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: }