/*

 * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.lang.reflect;

import java.lang.annotation.Annotation;

/**

 * A {@code Method} provides information about, and access to, a single method

 * on a class or interface.  The reflected method may be a class method

 * or an instance method (including an abstract method).

 *

 * <p>A {@code Method} permits widening conversions to occur when matching the

 * actual parameters to invoke with the underlying method's formal

 * parameters, but it throws an {@code IllegalArgumentException} if a

 * narrowing conversion would occur.

 *

 * @see Member

 * @see java.lang.Class

 * @see java.lang.Class#getMethods()

 * @see java.lang.Class#getMethod(String, Class[])

 * @see java.lang.Class#getDeclaredMethods()

 * @see java.lang.Class#getDeclaredMethod(String, Class[])

 *

 * @author Kenneth Russell

 * @author Nakul Saraiya

 */

public final

    class Method extends AccessibleObject implements GenericDeclaration,

                                                     Member {

    private Class<?>            clazz;

    private int                 slot;

    // This is guaranteed to be interned by the VM in the 1.4

    // reflection implementation

    private String              name;

    private Class<?>            returnType;

    private Class<?>[]          parameterTypes;

    private Class<?>[]          exceptionTypes;

    private int                 modifiers;

    // Generics and annotations support

    private transient String              signature;

    private byte[]              annotations;

    private byte[]              parameterAnnotations;

    private byte[]              annotationDefault;

    // For sharing of MethodAccessors. This branching structure is

    // currently only two levels deep (i.e., one root Method and

    // potentially many Method objects pointing to it.)

    private Method              root;

   // Generics infrastructure

    private String getGenericSignature() {return signature;}

    /**

     * Package-private constructor used by ReflectAccess to enable

     * instantiation of these objects in Java code from the java.lang

     * package via sun.reflect.LangReflectAccess.

     */

    Method(Class<?> declaringClass,

           String name,

           Class<?>[] parameterTypes,

           Class<?> returnType,

           Class<?>[] checkedExceptions,

           int modifiers,

           int slot,

           String signature,

           byte[] annotations,

           byte[] parameterAnnotations,

           byte[] annotationDefault)

    {

        this.clazz = declaringClass;

        this.name = name;

        this.parameterTypes = parameterTypes;

        this.returnType = returnType;

        this.exceptionTypes = checkedExceptions;

        this.modifiers = modifiers;

        this.slot = slot;

        this.signature = signature;

        this.annotations = annotations;

        this.parameterAnnotations = parameterAnnotations;

        this.annotationDefault = annotationDefault;

    }

    /**

     * Package-private routine (exposed to java.lang.Class via

     * ReflectAccess) which returns a copy of this Method. The copy's

     * "root" field points to this Method.

     */

    Method copy() {

        // This routine enables sharing of MethodAccessor objects

        // among Method objects which refer to the same underlying

        // method in the VM. (All of this contortion is only necessary

        // because of the "accessibility" bit in AccessibleObject,

        // which implicitly requires that new java.lang.reflect

        // objects be fabricated for each reflective call on Class

        // objects.)

        Method res = new Method(clazz, name, parameterTypes, returnType,

                                exceptionTypes, modifiers, slot, signature,

                                annotations, parameterAnnotations, annotationDefault);

        res.root = this;

        return res;

    }

    /**

     * Returns the {@code Class} object representing the class or interface

     * that declares the method represented by this {@code Method} object.

     */

    public Class<?> getDeclaringClass() {

        return clazz;

    }

    /**

     * Returns the name of the method represented by this {@code Method}

     * object, as a {@code String}.

     */

    public String getName() {

        return name;

    }

    /**

     * Returns the Java language modifiers for the method represented

     * by this {@code Method} object, as an integer. The {@code Modifier} class should

     * be used to decode the modifiers.

     *

     * @see Modifier

     */

    public int getModifiers() {

        return modifiers;

    }

    /**

     * Returns an array of {@code TypeVariable} objects that represent the

     * type variables declared by the generic declaration represented by this

     * {@code GenericDeclaration} object, in declaration order.  Returns an

     * array of length 0 if the underlying generic declaration declares no type

     * variables.

     *

     * @return an array of {@code TypeVariable} objects that represent

     *     the type variables declared by this generic declaration

     * @throws GenericSignatureFormatError if the generic

     *     signature of this generic declaration does not conform to

     *     the format specified in

     *     <cite>The Java&trade; Virtual Machine Specification</cite>

     * @since 1.5

     */

    public TypeVariable<Method>[] getTypeParameters() {

        throw new UnsupportedOperationException();

    }

    /**

     * Returns a {@code Class} object that represents the formal return type

     * of the method represented by this {@code Method} object.

     *

     * @return the return type for the method this object represents

     */

    public Class<?> getReturnType() {

        return returnType;

    }

    /**

     * Returns a {@code Type} object that represents the formal return

     * type of the method represented by this {@code Method} object.

     *

     * <p>If the return type is a parameterized type,

     * the {@code Type} object returned must accurately reflect

     * the actual type parameters used in the source code.

     *

     * <p>If the return type is a type variable or a parameterized type, it

     * is created. Otherwise, it is resolved.

     *

     * @return  a {@code Type} object that represents the formal return

     *     type of the underlying  method

     * @throws GenericSignatureFormatError

     *     if the generic method signature does not conform to the format

     *     specified in

     *     <cite>The Java&trade; Virtual Machine Specification</cite>

     * @throws TypeNotPresentException if the underlying method's

     *     return type refers to a non-existent type declaration

     * @throws MalformedParameterizedTypeException if the

     *     underlying method's return typed refers to a parameterized

     *     type that cannot be instantiated for any reason

     * @since 1.5

     */

    public Type getGenericReturnType() {

        throw new UnsupportedOperationException();

    }

    /**

     * Returns an array of {@code Class} objects that represent the formal

     * parameter types, in declaration order, of the method

     * represented by this {@code Method} object.  Returns an array of length

     * 0 if the underlying method takes no parameters.

     *

     * @return the parameter types for the method this object

     * represents

     */

    public Class<?>[] getParameterTypes() {

        return (Class<?>[]) parameterTypes.clone();

    }

    /**

     * Returns an array of {@code Type} objects that represent the formal

     * parameter types, in declaration order, of the method represented by

     * this {@code Method} object. Returns an array of length 0 if the

     * underlying method takes no parameters.

     *

     * <p>If a formal parameter type is a parameterized type,

     * the {@code Type} object returned for it must accurately reflect

     * the actual type parameters used in the source code.

     *

     * <p>If a formal parameter type is a type variable or a parameterized

     * type, it is created. Otherwise, it is resolved.

     *

     * @return an array of Types that represent the formal

     *     parameter types of the underlying method, in declaration order

     * @throws GenericSignatureFormatError

     *     if the generic method signature does not conform to the format

     *     specified in

     *     <cite>The Java&trade; Virtual Machine Specification</cite>

     * @throws TypeNotPresentException if any of the parameter

     *     types of the underlying method refers to a non-existent type

     *     declaration

     * @throws MalformedParameterizedTypeException if any of

     *     the underlying method's parameter types refer to a parameterized

     *     type that cannot be instantiated for any reason

     * @since 1.5

     */

    public Type[] getGenericParameterTypes() {

        throw new UnsupportedOperationException();

    }

    /**

     * Returns an array of {@code Class} objects that represent

     * the types of the exceptions declared to be thrown

     * by the underlying method

     * represented by this {@code Method} object.  Returns an array of length

     * 0 if the method declares no exceptions in its {@code throws} clause.

     *

     * @return the exception types declared as being thrown by the

     * method this object represents

     */

    public Class<?>[] getExceptionTypes() {

        return (Class<?>[]) exceptionTypes.clone();

    }

    /**

     * Returns an array of {@code Type} objects that represent the

     * exceptions declared to be thrown by this {@code Method} object.

     * Returns an array of length 0 if the underlying method declares

     * no exceptions in its {@code throws} clause.

     *

     * <p>If an exception type is a type variable or a parameterized

     * type, it is created. Otherwise, it is resolved.

     *

     * @return an array of Types that represent the exception types

     *     thrown by the underlying method

     * @throws GenericSignatureFormatError

     *     if the generic method signature does not conform to the format

     *     specified in

     *     <cite>The Java&trade; Virtual Machine Specification</cite>

     * @throws TypeNotPresentException if the underlying method's

     *     {@code throws} clause refers to a non-existent type declaration

     * @throws MalformedParameterizedTypeException if

     *     the underlying method's {@code throws} clause refers to a

     *     parameterized type that cannot be instantiated for any reason

     * @since 1.5

     */

      public Type[] getGenericExceptionTypes() {

        throw new UnsupportedOperationException();

      }

    /**

     * Compares this {@code Method} against the specified object.  Returns

     * true if the objects are the same.  Two {@code Methods} are the same if

     * they were declared by the same class and have the same name

     * and formal parameter types and return type.

     */

    public boolean equals(Object obj) {

        if (obj != null && obj instanceof Method) {

            Method other = (Method)obj;

            if ((getDeclaringClass() == other.getDeclaringClass())

                && (getName() == other.getName())) {

                if (!returnType.equals(other.getReturnType()))

                    return false;

                /* Avoid unnecessary cloning */

                Class<?>[] params1 = parameterTypes;

                Class<?>[] params2 = other.parameterTypes;

                if (params1.length == params2.length) {

                    for (int i = 0; i < params1.length; i++) {

                        if (params1[i] != params2[i])

                            return false;

                    }

                    return true;

                }

            }

        }

        return false;

    }

    /**

     * Returns a hashcode for this {@code Method}.  The hashcode is computed

     * as the exclusive-or of the hashcodes for the underlying

     * method's declaring class name and the method's name.

     */

    public int hashCode() {

        return getDeclaringClass().getName().hashCode() ^ getName().hashCode();

    }

    /**

     * Returns a string describing this {@code Method}.  The string is

     * formatted as the method access modifiers, if any, followed by

     * the method return type, followed by a space, followed by the

     * class declaring the method, followed by a period, followed by

     * the method name, followed by a parenthesized, comma-separated

     * list of the method's formal parameter types. If the method

     * throws checked exceptions, the parameter list is followed by a

     * space, followed by the word throws followed by a

     * comma-separated list of the thrown exception types.

     * For example:

     * <pre>

     *    public boolean java.lang.Object.equals(java.lang.Object)

     * </pre>

     *

     * <p>The access modifiers are placed in canonical order as

     * specified by "The Java Language Specification".  This is

     * {@code public}, {@code protected} or {@code private} first,

     * and then other modifiers in the following order:

     * {@code abstract}, {@code static}, {@code final},

     * {@code synchronized}, {@code native}, {@code strictfp}.

     */

    public String toString() {

        try {

            StringBuilder sb = new StringBuilder();

            int mod = getModifiers() & Modifier.methodModifiers();

            if (mod != 0) {

                sb.append(Modifier.toString(mod)).append(' ');

            }

            sb.append(Field.getTypeName(getReturnType())).append(' ');

            sb.append(Field.getTypeName(getDeclaringClass())).append('.');

            sb.append(getName()).append('(');

            Class<?>[] params = parameterTypes; // avoid clone

            for (int j = 0; j < params.length; j++) {

                sb.append(Field.getTypeName(params[j]));

                if (j < (params.length - 1))

                    sb.append(',');

            }

            sb.append(')');

            Class<?>[] exceptions = exceptionTypes; // avoid clone

            if (exceptions.length > 0) {

                sb.append(" throws ");

                for (int k = 0; k < exceptions.length; k++) {

                    sb.append(exceptions[k].getName());

                    if (k < (exceptions.length - 1))

                        sb.append(',');

                }

            }

            return sb.toString();

        } catch (Exception e) {

            return "<" + e + ">";

        }

    }

    /**

     * Returns a string describing this {@code Method}, including

     * type parameters.  The string is formatted as the method access

     * modifiers, if any, followed by an angle-bracketed

     * comma-separated list of the method's type parameters, if any,

     * followed by the method's generic return type, followed by a

     * space, followed by the class declaring the method, followed by

     * a period, followed by the method name, followed by a

     * parenthesized, comma-separated list of the method's generic

     * formal parameter types.

     *

     * If this method was declared to take a variable number of

     * arguments, instead of denoting the last parameter as

     * "<tt><i>Type</i>[]</tt>", it is denoted as

     * "<tt><i>Type</i>...</tt>".

     *

     * A space is used to separate access modifiers from one another

     * and from the type parameters or return type.  If there are no

     * type parameters, the type parameter list is elided; if the type

     * parameter list is present, a space separates the list from the

     * class name.  If the method is declared to throw exceptions, the

     * parameter list is followed by a space, followed by the word

     * throws followed by a comma-separated list of the generic thrown

     * exception types.  If there are no type parameters, the type

     * parameter list is elided.

     *

     * <p>The access modifiers are placed in canonical order as

     * specified by "The Java Language Specification".  This is

     * {@code public}, {@code protected} or {@code private} first,

     * and then other modifiers in the following order:

     * {@code abstract}, {@code static}, {@code final},

     * {@code synchronized}, {@code native}, {@code strictfp}.

     *

     * @return a string describing this {@code Method},

     * include type parameters

     *

     * @since 1.5

     */

    public String toGenericString() {

        try {

            StringBuilder sb = new StringBuilder();

            int mod = getModifiers() & Modifier.methodModifiers();

            if (mod != 0) {

                sb.append(Modifier.toString(mod)).append(' ');

            }

            TypeVariable<?>[] typeparms = getTypeParameters();

            if (typeparms.length > 0) {

                boolean first = true;

                sb.append('<');

                for(TypeVariable<?> typeparm: typeparms) {

                    if (!first)

                        sb.append(',');

                    // Class objects can't occur here; no need to test

                    // and call Class.getName().

                    sb.append(typeparm.toString());

                    first = false;

                }

                sb.append("> ");

            }

            Type genRetType = getGenericReturnType();

            sb.append( ((genRetType instanceof Class<?>)?

                        Field.getTypeName((Class<?>)genRetType):genRetType.toString()))

                    .append(' ');

            sb.append(Field.getTypeName(getDeclaringClass())).append('.');

            sb.append(getName()).append('(');

            Type[] params = getGenericParameterTypes();

            for (int j = 0; j < params.length; j++) {

                String param = (params[j] instanceof Class)?

                    Field.getTypeName((Class)params[j]):

                    (params[j].toString());

                if (isVarArgs() && (j == params.length - 1)) // replace T[] with T...

                    param = param.replaceFirst("\\[\\]$", "...");

                sb.append(param);

                if (j < (params.length - 1))

                    sb.append(',');

            }

            sb.append(')');

            Type[] exceptions = getGenericExceptionTypes();

            if (exceptions.length > 0) {

                sb.append(" throws ");

                for (int k = 0; k < exceptions.length; k++) {

                    sb.append((exceptions[k] instanceof Class)?

                              ((Class)exceptions[k]).getName():

                              exceptions[k].toString());

                    if (k < (exceptions.length - 1))

                        sb.append(',');

                }

            }

            return sb.toString();

        } catch (Exception e) {

            return "<" + e + ">";

        }

    }

    /**

     * Invokes the underlying method represented by this {@code Method}

     * object, on the specified object with the specified parameters.

     * Individual parameters are automatically unwrapped to match

     * primitive formal parameters, and both primitive and reference

     * parameters are subject to method invocation conversions as

     * necessary.

     *

     * <p>If the underlying method is static, then the specified {@code obj}

     * argument is ignored. It may be null.

     *

     * <p>If the number of formal parameters required by the underlying method is

     * 0, the supplied {@code args} array may be of length 0 or null.

     *

     * <p>If the underlying method is an instance method, it is invoked

     * using dynamic method lookup as documented in The Java Language

     * Specification, Second Edition, section 15.12.4.4; in particular,

     * overriding based on the runtime type of the target object will occur.

     *

     * <p>If the underlying method is static, the class that declared

     * the method is initialized if it has not already been initialized.

     *

     * <p>If the method completes normally, the value it returns is

     * returned to the caller of invoke; if the value has a primitive

     * type, it is first appropriately wrapped in an object. However,

     * if the value has the type of an array of a primitive type, the

     * elements of the array are <i>not</i> wrapped in objects; in

     * other words, an array of primitive type is returned.  If the

     * underlying method return type is void, the invocation returns

     * null.

     *

     * @param obj  the object the underlying method is invoked from

     * @param args the arguments used for the method call

     * @return the result of dispatching the method represented by

     * this object on {@code obj} with parameters

     * {@code args}

     *

     * @exception IllegalAccessException    if this {@code Method} object

     *              is enforcing Java language access control and the underlying

     *              method is inaccessible.

     * @exception IllegalArgumentException  if the method is an

     *              instance method and the specified object argument

     *              is not an instance of the class or interface

     *              declaring the underlying method (or of a subclass

     *              or implementor thereof); if the number of actual

     *              and formal parameters differ; if an unwrapping

     *              conversion for primitive arguments fails; or if,

     *              after possible unwrapping, a parameter value

     *              cannot be converted to the corresponding formal

     *              parameter type by a method invocation conversion.

     * @exception InvocationTargetException if the underlying method

     *              throws an exception.

     * @exception NullPointerException      if the specified object is null

     *              and the method is an instance method.

     * @exception ExceptionInInitializerError if the initialization

     * provoked by this method fails.

     */

    public Object invoke(Object obj, Object... args)

        throws IllegalAccessException, IllegalArgumentException,

           InvocationTargetException

    {

        throw new UnsupportedOperationException();

    }

    /**

     * Returns {@code true} if this method is a bridge

     * method; returns {@code false} otherwise.

     *

     * @return true if and only if this method is a bridge

     * method as defined by the Java Language Specification.

     * @since 1.5

     */

    public boolean isBridge() {

        return (getModifiers() & Modifier.BRIDGE) != 0;

    }

    /**

     * Returns {@code true} if this method was declared to take

     * a variable number of arguments; returns {@code false}

     * otherwise.

     *

     * @return {@code true} if an only if this method was declared to

     * take a variable number of arguments.

     * @since 1.5

     */

    public boolean isVarArgs() {

        return (getModifiers() & Modifier.VARARGS) != 0;

    }

    /**

     * Returns {@code true} if this method is a synthetic

     * method; returns {@code false} otherwise.

     *

     * @return true if and only if this method is a synthetic

     * method as defined by the Java Language Specification.

     * @since 1.5

     */

    public boolean isSynthetic() {

        return Modifier.isSynthetic(getModifiers());

    }

    /**

     * @throws NullPointerException {@inheritDoc}

     * @since 1.5

     */

    public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {

        if (annotationClass == null)

            throw new NullPointerException();

        throw new UnsupportedOperationException();

    }

    /**

     * @since 1.5

     */

    public Annotation[] getDeclaredAnnotations()  {

        throw new UnsupportedOperationException();

    }

    /**

     * Returns the default value for the annotation member represented by

     * this {@code Method} instance.  If the member is of a primitive type,

     * an instance of the corresponding wrapper type is returned. Returns

     * null if no default is associated with the member, or if the method

     * instance does not represent a declared member of an annotation type.

     *

     * @return the default value for the annotation member represented

     *     by this {@code Method} instance.

     * @throws TypeNotPresentException if the annotation is of type

     *     {@link Class} and no definition can be found for the

     *     default class value.

     * @since  1.5

     */

    public Object getDefaultValue() {

        if  (annotationDefault == null)

            return null;

        throw new UnsupportedOperationException();

    }

    /**

     * Returns an array of arrays that represent the annotations on the formal

     * parameters, in declaration order, of the method represented by

     * this {@code Method} object. (Returns an array of length zero if the

     * underlying method is parameterless.  If the method has one or more

     * parameters, a nested array of length zero is returned for each parameter

     * with no annotations.) The annotation objects contained in the returned

     * arrays are serializable.  The caller of this method is free to modify

     * the returned arrays; it will have no effect on the arrays returned to

     * other callers.

     *

     * @return an array of arrays that represent the annotations on the formal

     *    parameters, in declaration order, of the method represented by this

     *    Method object

     * @since 1.5

     */

    public Annotation[][] getParameterAnnotations() {

        int numParameters = parameterTypes.length;

        if (parameterAnnotations == null)

            return new Annotation[numParameters][0];

        throw new UnsupportedOperationException();

    }

}