home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / Method.java < prev    next >
Text File  |  1997-08-30  |  10KB  |  287 lines
  1. /*
  2.  * @(#)Method.java    1.14 97/02/10
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.lang.reflect;
  24.  
  25. /**
  26.  * A Method provides information about, and access to, a single method
  27.  * on a class or interface.  The reflected method may be a class method
  28.  * or an instance method (including an abstract method).
  29.  *
  30.  * <p>A Method permits widening conversions to occur when matching the
  31.  * actual parameters to invokewith the underlying method's formal
  32.  * parameters, but it throws an IllegalArgumentException if a
  33.  * narrowing conversion would occur.
  34.  *
  35.  * @see Member
  36.  * @see java.lang.Class
  37.  * @see java.lang.Class#getMethods()
  38.  * @see java.lang.Class#getMethod()
  39.  * @see java.lang.Class#getDeclaredMethods()
  40.  * @see java.lang.Class#getDeclaredMethod()
  41.  *
  42.  * @author Nakul Saraiya
  43.  */
  44. public final
  45. class Method implements Member {
  46.  
  47.     private Class        clazz;
  48.     private int            slot;
  49.     private String        name;
  50.     private Class        returnType;
  51.     private Class[]        parameterTypes;
  52.     private Class[]        exceptionTypes;
  53.  
  54.     /**
  55.      * Constructor.  Only the Java Virtual Machine may construct a Method.
  56.      */
  57.     private Method() {}
  58.  
  59.     /**
  60.      * Returns the Class object representing the class or interface
  61.      * that declares the method represented by this Method object.
  62.      */
  63.     public Class getDeclaringClass() {
  64.     return clazz;
  65.     }
  66.  
  67.     /**
  68.      * Returns the name of the method represented by this Method
  69.      * object, as a String.
  70.      */
  71.     public String getName() {
  72.     return name;
  73.     }
  74.  
  75.     /**
  76.      * Returns the Java language modifiers for the method represented
  77.      * by this Method object, as an integer. The Modifier class should
  78.      * be used to decode the modifiers.
  79.      *
  80.      * @see Modifier
  81.      */
  82.     public native int getModifiers();
  83.  
  84.     /**
  85.      * Returns a Class object that represents the formal return type
  86.      * of the method represented by this Method object.
  87.      */
  88.     public Class getReturnType() {
  89.     return returnType;
  90.     }
  91.  
  92.     /**
  93.      * Returns an array of Class objects that represent the formal
  94.      * parameter types, in declaration order, of the method
  95.      * represented by this Method object.  Returns an array of length
  96.      * 0 if the underlying method takes no parameters.
  97.      */
  98.     public Class[] getParameterTypes() {
  99.     return copy(parameterTypes);
  100.     }
  101.  
  102.     /**
  103.      * Returns an array of Class objects that represent the types of
  104.      * the checked exceptions thrown by the underlying method
  105.      * represented by this Method object.  Returns an array of length
  106.      * 0 if the method throws no checked exceptions.
  107.      */
  108.     public Class[] getExceptionTypes() {
  109.     return copy(exceptionTypes);
  110.     }
  111.  
  112.     /**
  113.      * Compares this Method against the specified object.  Returns
  114.      * true if the objects are the same.  Two Methods are the same if
  115.      * they were declared by the same class and have the same name
  116.      * and formal parameter types.
  117.      */
  118.     public boolean equals(Object obj) {
  119.     if (obj != null && obj instanceof Method) {
  120.         Method other = (Method)obj;
  121.         if ((getDeclaringClass() == other.getDeclaringClass())
  122.         && (getName().equals(other.getName()))) {
  123.         /* Avoid unnecessary cloning */
  124.         Class[] params1 = parameterTypes;
  125.         Class[] params2 = other.parameterTypes;
  126.         if (params1.length == params2.length) {
  127.             for (int i = 0; i < params1.length; i++) {
  128.             if (params1[i] != params2[i])
  129.                 return false;
  130.             }
  131.             return true;
  132.         }
  133.         }
  134.     }
  135.     return false;
  136.     }
  137.  
  138.     /**
  139.      * Returns a hashcode for this Method.  The hashcode is computed
  140.      * as the exclusive-or of the hashcodes for the underlying
  141.      * method's declaring class name and the method's name.
  142.      */
  143.     public int hashCode() {
  144.     return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
  145.     }
  146.  
  147.     /**
  148.      * Returns a string describing this Method.  The string is
  149.      * formatted as the method access modifiers, if any, followed by
  150.      * the method return type, followed by a space, followed by the
  151.      * class declaring the method, followed by a period, followed by
  152.      * the method name, followed by a parenthesized, comma-separated
  153.      * list of the method's formal parameter types. If the method
  154.      * throws checked exceptions, the parameter list is followed by a
  155.      * space, followed by the word throws followed by a
  156.      * comma-separated list of the thrown exception types.
  157.      * For example:
  158.      * <pre>
  159.      *    public boolean java.lang.Object.equals(java.lang.Object)
  160.      * </pre>
  161.      *
  162.      * <p>The access modifiers are placed in canonical order as
  163.      * specified by "The Java Language Specification".  This is
  164.      * <tt>public</tt>, <tt>protected</tt> or <tt>private</tt> first,
  165.      * and then other modifiers in the following order:
  166.      * <tt>abstract</tt>, <tt>static</tt>, <tt>final</tt>,
  167.      * <tt>synchronized</tt> <tt>native</tt>.
  168.      */
  169.     public String toString() {
  170.     try {
  171.         StringBuffer sb = new StringBuffer();
  172.         int mod = getModifiers();
  173.         if (mod != 0) {
  174.         sb.append(Modifier.toString(mod) + " ");
  175.         }
  176.         sb.append(Field.getTypeName(getReturnType()) + " ");
  177.         sb.append(Field.getTypeName(getDeclaringClass()) + ".");
  178.         sb.append(getName() + "(");
  179.         Class[] params = parameterTypes; // avoid clone
  180.         for (int j = 0; j < params.length; j++) {
  181.         sb.append(Field.getTypeName(params[j]));
  182.         if (j < (params.length - 1))
  183.             sb.append(",");
  184.         }
  185.         sb.append(")");
  186.         Class[] exceptions = exceptionTypes; // avoid clone
  187.         if (exceptions.length > 0) {
  188.         sb.append(" throws ");
  189.         for (int k = 0; k < exceptions.length; k++) {
  190.             sb.append(exceptions[k].getName());
  191.             if (k < (exceptions.length - 1))
  192.             sb.append(",");
  193.         }
  194.         }
  195.         return sb.toString();
  196.     } catch (Exception e) {
  197.         return "<" + e + ">";
  198.     }
  199.     }
  200.  
  201.     /**
  202.      * Invokes the underlying method represented by this Method
  203.      * object, on the specified object with the specified parameters.
  204.      * Individual parameters are automatically unwrapped to match
  205.      * primitive formal parameters, and both primitive and reference
  206.      * parameters are subject to widening conversions as
  207.      * necessary. The value returned by the underlying method is
  208.      * automatically wrapped in an object if it has a primitive type.
  209.      *
  210.      * <p>Method invocation proceeds with the following steps, in order:
  211.      *
  212.      * <p>If the underlying method is static, then the specified object
  213.      * argument is ignored. It may be null.
  214.      *
  215.      * <p>Otherwise, the method is an instance method.  If the specified
  216.      * object argument is null, the invocation throws a
  217.      * NullPointerException.  Otherwise, if the specified object
  218.      * argument is not an instance of the class or interface declaring
  219.      * the underlying method, the invocation throws an
  220.      * IllegalArgumentException.
  221.      *
  222.      * <p>If this Method object enforces Java language access control and
  223.      * the underlying method is inaccessible, the invocation throws an
  224.      * IllegalAccessException.
  225.      *
  226.      * <p>If the number of actual parameters supplied via args is
  227.      * different from the number of formal parameters required by the
  228.      * underlying method, the invocation throws an
  229.      * IllegalArgumentException.
  230.      *
  231.      * <p>For each actual parameter in the supplied args array:
  232.      *
  233.      * <p>If the corresponding formal parameter has a primitive type, an
  234.      * unwrapping conversion is attempted to convert the object value
  235.      * to a value of a primitive type.  If this attempt fails, the
  236.      * invocation throws an IllegalArgumentException.
  237.      *
  238.      * <p>If, after possible unwrapping, the parameter value cannot be
  239.      * converted to the corresponding formal parameter type by an
  240.      * identity or widening conversion, the invocation throws an
  241.      * IllegalArgumentException.
  242.      *
  243.      * <p>If the underlying method is an instance method, it is invoked
  244.      * using dynamic method lookup as documented in The Java Language
  245.      * Specification, section 15.11.4.4; in particular, overriding
  246.      * based on the runtime type of the target object will occur.
  247.      *
  248.      * <p>If the underlying method is static, it is invoked as exactly
  249.      * the method on the declaring class.
  250.      *
  251.      * <p>Control transfers to the underlying method.  If the method
  252.      * completes abruptly by throwing an exception, the exception is
  253.      * placed in an InvocationTargetException and thrown in turn to
  254.      * the caller of invoke.
  255.      *
  256.      * <p>If the method completes normally, the value it returns is
  257.      * returned to the caller of invoke; if the value has a primitive
  258.      * type, it is first appropriately wrapped in an object. If the
  259.      * underlying method return type is void, the invocation returns
  260.      * null.
  261.      *
  262.      * @exception IllegalAccessException    if the underlying method
  263.      *              is inaccessible.
  264.      * @exception IllegalArgumentException  if the number of actual and formal
  265.      *              parameters differ, or if an unwrapping conversion fails.
  266.      * @exception InvocationTargetException if the underlying method
  267.      *              throws an exception.
  268.      * @exception NullPointerException      if the specified object is null.
  269.      */
  270.     public native Object invoke(Object obj, Object[] args)
  271.     throws IllegalAccessException, IllegalArgumentException,
  272.         InvocationTargetException;
  273.  
  274.     /*
  275.      * Avoid clone()
  276.      */
  277.     static Class[] copy(Class[] in) {
  278.     int l = in.length;
  279.     if (l == 0)
  280.         return in;
  281.     Class[] out = new Class[l];
  282.     for (int i = 0; i < l; i++)
  283.         out[i] = in[i];
  284.     return out;
  285.     }
  286. }
  287.