/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.bsf.util;

import java.lang.reflect.Constructor;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.Enumeration;
import java.util.Vector;

/**
 * This file is a collection of reflection utilities for dealing with
 * methods and constructors.
 * 
 * @author   Sanjiva Weerawarana
 * @author   Joseph Kesselman
 */
public class MethodUtils {

  /** Internal Class for getEntryPoint(). Implements 15.11.2.2 MORE
    SPECIFIC rules.

    Retains a list of methods (already known to match the
    arguments). As each method is added, we check against past entries
    to determine which if any is "more specific" -- defined as having
    _all_ its arguments (not just a preponderance) be
    method-convertable into those of another. If such a relationship
    is found, the more-specific method is retained and the
    less-specific method is discarded. At the end, if this has yielded
    a single winner it is considered the Most Specific Method and
    hence the one that should be invoked.  Otherwise, a
    NoSuchMethodException is thrown.
    
    PERFORMANCE VERSUS ARCHITECTURE: Arguably, this should "have-a"
    Vector. But the code is 6% smaller, and possibly faster, if we
    code it as "is-a" Vector. Since it's an inner class, nobody's
    likely to abuse the privilage.
    
    Note: "Static" in the case of an inner class means "Does not
    reference instance data in the outer class", and is required since
    our caller is a static method. */
  private static class MoreSpecific
  extends Vector
  {
    /** Submit an entry-point to the list. May be discarded if a past
      entry is more specific, or may cause others to be discarded it
      if is more specific.

      newEntry: Method or Constructor under consideration.
      */
    void addItem (Object newEntry)
    {
      if(size()==0)
        addElement(newEntry);
      else
        {
          Class[] newargs=entryGetParameterTypes(newEntry);
          boolean keep=true;
          for (Enumeration e = elements();
               keep & e.hasMoreElements() ;
                )
            {
              Object oldEntry=e.nextElement();
              // CAVEAT: Implicit references to enclosing class!
              Class[] oldargs=entryGetParameterTypes(oldEntry);
              if(areMethodConvertable(oldargs,newargs))
                removeElement(oldEntry); // New more specific; discard old
              else if(areMethodConvertable(newargs,oldargs))
                keep=false;     // Old more specific; discard new
              // Else they're tied. Keep both and hope someone beats both.
            }
          if(keep)
            addElement(newEntry);
        }
    }

    /** Obtain the single Most Specific entry-point. If there is no clear
      winner, or if the list is empty, throw NoSuchMethodException.

      Arguments describe the call we were hoping to resolve. They are
      used to throw a nice verbose exception if something goes wrong.
      */
    Object getMostSpecific(Class targetClass,String methodName,
                           Class[] argTypes,boolean isStaticReference)
         throws NoSuchMethodException
    {
      if(size()==1)
        return firstElement();
      if(size()>1)
        {
          StringBuffer buf=new StringBuffer();
          Enumeration e=elements();
          buf.append(e.nextElement());
          while(e.hasMoreElements())
            buf.append(" and ").append(e.nextElement());
          throw new NoSuchMethodException (callToString(targetClass,
                                                        methodName,
                                                        argTypes,
                                                        isStaticReference)+
                                           " is ambiguous. It matches "+
                                           buf.toString());
        }
      return null;
    }
  }

  /** Convenience method: Test an entire parameter-list/argument-list pair
    for isMethodConvertable(), qv. 
    */
  static private boolean areMethodConvertable(Class[] parms,Class[] args)
  {
    if(parms.length!=args.length)
      return false;
    
    for(int i=0;i<parms.length;++i)
      if(!isMethodConvertable(parms[i],args[i]))
        return false;
    
    return true;
  }
  /** Internal subroutine for getEntryPoint(): Format arguments as a
      string describing the function being searched for. Used in
      verbose exceptions. */
  private static String callToString(Class targetClass,String methodName,
                                    Class[] argTypes,boolean isStaticReference)
  {
    StringBuffer buf = new StringBuffer();
    if(isStaticReference)
      buf.append("static ");
    buf.append(StringUtils.getClassName(targetClass));
    if(methodName!=null)
      buf.append(".").append(methodName);
    buf.append("(");
    if (argTypes != null && argTypes.length>0) {
      if(false)
        {
          // ????? Sanjiva has an ArrayToString method. Using it would
          // save a few bytes, at cost of giving up some reusability.
        }
      else
        {
          buf.append(StringUtils.getClassName(argTypes[0]));
          for (int i = 1; i < argTypes.length; i++) {
            buf.append(",").append(StringUtils.getClassName(argTypes[i]));
          }
        }
    }
    else
      buf.append("[none]");
    buf.append(")");
    return buf.toString();
  }
  /** Utility function: obtain common data from either Method or
      Constructor. (In lieu of an EntryPoint interface.) */
  static int entryGetModifiers(Object entry)
  {
    return (entry instanceof Method)
      ? ((Method)entry).getModifiers()
      : ((Constructor)entry).getModifiers();
  }
  // The common lookup code would be much easier if Method and
  // Constructor shared an "EntryPoint" Interface. Unfortunately, even
  // though their APIs are almost identical, they don't. These calls
  // are a workaround...  at the cost of additional runtime overhead
  // and some extra bytecodes.
  //
  // (A JDK bug report has been submitted requesting that they add the
  // Interface; it would be easy, harmless, and useful.)

  /** Utility function: obtain common data from either Method or
      Constructor. (In lieu of an EntryPoint interface.) */
  static String entryGetName(Object entry)
  {
    return (entry instanceof Method)
      ? ((Method)entry).getName()
      : ((Constructor)entry).getName();
  }
  /** Utility function: obtain common data from either Method or
      Constructor. (In lieu of an EntryPoint interface.) */
  static Class[] entryGetParameterTypes(Object entry)
  {
    return (entry instanceof Method)
      ? ((Method)entry).getParameterTypes()
      : ((Constructor)entry).getParameterTypes();
  }
  /** Utility function: obtain common data from either Method or
      Constructor. (In lieu of an EntryPoint interface.) */
  static String entryToString(Object entry)
  {
    return (entry instanceof Method)
      ? ((Method)entry).toString()
      : ((Constructor)entry).toString();
  }
  //////////////////////////////////////////////////////////////////////////

  /** Class.getConstructor() finds only the entry point (if any)
    _exactly_ matching the specified argument types. Our implmentation
    can decide between several imperfect matches, using the same
    search algorithm as the Java compiler.

    Note that all constructors are static by definition, so
    isStaticReference is true.

    @exception NoSuchMethodException if constructor not found.
    */
  static public Constructor getConstructor(Class targetClass, Class[] argTypes)
       throws SecurityException, NoSuchMethodException
  {
    return (Constructor) getEntryPoint(targetClass,null,argTypes,true);
  }
  //////////////////////////////////////////////////////////////////////////

  /**
   * Search for entry point, per  Java Language Spec 1.0
   * as amended, verified by comparison against compiler behavior.
   *
   * @param targetClass Class object for the class to be queried.
   * @param methodName  Name of method to invoke, or null for constructor.
   *                    Only Public methods will be accepted.
   * @param argTypes    Classes of intended arguments.  Note that primitives
   *                    must be specified via their TYPE equivalents, 
   *                    rather than as their wrapper classes -- Integer.TYPE
   *                    rather than Integer. "null" may be passed in as an
   *                    indication that you intend to invoke the method with
   *                    a literal null argument and therefore can accept
   *                    any object type in this position.
   * @param isStaticReference  If true, and if the target is a Class object,
   *                    only static methods will be accepted as valid matches.
   *
   * @return a Method or Constructor of the appropriate signature
   *
   * @exception SecurityException     if security violation
   * @exception NoSuchMethodException if no such method
   */
  static private Object getEntryPoint(Class targetClass,
                                      String methodName,
                                      Class[] argTypes,
                                      boolean isStaticReference) 
       throws SecurityException, NoSuchMethodException
  {
    // 15.11.1: OBTAIN STARTING CLASS FOR SEARCH
    Object m=null;
    
    // 15.11.2 DETERMINE ARGUMENT SIGNATURE
    // (Passed in as argTypes array.)
    
    // Shortcut: If an exact match exists, return it.
    try {
      if(methodName!=null)
        {
          m=targetClass.getMethod (methodName, argTypes);
          if(isStaticReference &&
             !Modifier.isStatic(entryGetModifiers(m)) )
            {
              throw 
                new NoSuchMethodException (callToString (targetClass,
                                                         methodName,
                                                         argTypes,
                                                         isStaticReference)+
                                           " resolved to instance " + m);
            }
          return m;
        }
      else
        return targetClass.getConstructor (argTypes);
          
    } catch (NoSuchMethodException e) {
      // no-args has no alternatives!
      if(argTypes==null || argTypes.length==0)
      {
        throw 
          new NoSuchMethodException (callToString (targetClass,
                                                   methodName,
                                                   argTypes,
                                                   isStaticReference)+
                                     " not found.");
      }
      // Else fall through.
    }
    
    // Well, _that_ didn't work. Time to search for the Most Specific
    // matching function. NOTE that conflicts are possible!
    
    // 15.11.2.1 ACCESSIBLE: We apparently need to gather from two
    // sources to be sure we have both instance and static methods.
    Object[] methods;
    if(methodName!=null)
      {
        methods=targetClass.getMethods();
      }
    else
      {
        methods=targetClass.getConstructors();
      }
    if(0==methods.length)
      {
        throw new NoSuchMethodException("No methods!");
      }

    MoreSpecific best=new MoreSpecific();
    for(int i=0;i<methods.length;++i)
      {
        Object mi=methods[i];
        if (
            // 15.11.2.1 ACCESSIBLE: Method is public.
            Modifier.isPublic(entryGetModifiers(mi))
            &&
            // 15.11.2.1 APPLICABLE: Right method name (or c'tor)
            (methodName==null || entryGetName(mi).equals(methodName) )
            &&
            // 15.11.2.1 APPLICABLE: Parameters match arguments
            areMethodConvertable(entryGetParameterTypes(mi),argTypes)
             )
          // 15.11.2.2 MORE SPECIFIC displace less specific.
          best.addItem(mi);
      }

    // May throw NoSuchMethodException; we pass in info needed to
    // create a useful exception
    m=best.getMostSpecific(targetClass,methodName,argTypes,isStaticReference);
  
    // 15.11.3 APPROPRIATE: Class invocation can call only static
    // methods. Note that the defined order of evaluation permits a
    // call to be resolved to an inappropriate method and then
    // rejected, rather than finding the best of the appropriate
    // methods.
    //
    // Constructors are never static, so we don't test them.
    if(m==null)
      {
        throw new NoSuchMethodException (callToString(targetClass,
                                                      methodName,
                                                      argTypes,
                                                      isStaticReference)+
                                         " -- no signature match");
      }

    if( methodName!=null &&
        isStaticReference &&
        !Modifier.isStatic(entryGetModifiers(m)) )
      {
        throw new NoSuchMethodException (callToString(targetClass,
                                                      methodName,
                                                      argTypes,
                                                      isStaticReference)+
                                         " resolved to instance: "+m);
      }

    return m;
  }
  //////////////////////////////////////////////////////////////////////////

  /* Class.getMethod() finds only the entry point (if any) _exactly_
    matching the specified argument types. Our implmentation can
    decide between several imperfect matches, using the same search
    algorithm as the Java compiler.

    This version more closely resembles Class.getMethod() -- we always
    ask the Class for the method. It differs in testing for
    appropriateness before returning the method; if the query is
    being made via a static reference, only static methods will be
    found and returned. */
  static public Method getMethod(Class target,String methodName,
                                 Class[] argTypes,boolean isStaticReference)
       throws SecurityException, NoSuchMethodException
  {
    return (Method)getEntryPoint(target,methodName,argTypes,isStaticReference);
  }
  //////////////////////////////////////////////////////////////////////////

  /**
   * Class.getMethod() finds only the entry point (if any) _exactly_
   * matching the specified argument types. Our implmentation can
   * decide between several imperfect matches, using the same search
   * algorithm as the Java compiler.
   *
   * This version emulates the compiler behavior by allowing lookup to
   * be performed against either a class or an instance -- classname.foo()
   * must be a static method call, instance.foo() can invoke either static
   * or instance methods.
   *
   * @param target     object on which call is to be made
   * @param methodName name of method I'm lookin' for
   * @param argTypes   array of argument types of method
   *
   * @return the desired method
   *
   * @exception SecurityException     if security violation
   * @exception NoSuchMethodException if no such method
   */
  static public Method getMethod(Object target,String methodName,
                                 Class[] argTypes)
       throws SecurityException, NoSuchMethodException
  {
    boolean staticRef=target instanceof Class;
    return getMethod( staticRef ? (Class)target : target.getClass(),
                      methodName,argTypes,staticRef);
  }
  /** Determine whether a given type can accept assignments of another
    type. Note that class.isAssignable() is _not_ a complete test!
    (This method is not needed by getMethod() or getConstructor(), but
    is provided as a convenience for other users.)
    
    parm: The type given in the method's signature.
    arg: The type we want to pass in.

    Legal ASSIGNMENT CONVERSIONS (5.2) are METHOD CONVERSIONS (5.3)
    plus implicit narrowing of int to byte, short or char.  */
  static private boolean isAssignmentConvertable(Class parm,Class arg)
  {
    return
      (arg.equals(Integer.TYPE) &&
       (parm.equals(Byte.TYPE) ||
        parm.equals(Short.TYPE) ||
        parm.equals(Character.TYPE)
         )
        ) ||
      isMethodConvertable(parm,arg);
  }
  /** Determine whether a given method parameter type can accept
    arguments of another type.

    parm: The type given in the method's signature.
    arg: The type we want to pass in.

    Legal METHOD CONVERSIONS (5.3) are Identity, Widening Primitive
    Conversion, or Widening Reference Conversion. NOTE that this is a
    subset of the legal ASSIGNMENT CONVERSIONS (5.2) -- in particular,
    we can't implicitly narrow int to byte, short or char.

    SPECIAL CASE: In order to permit invoking methods with literal
    "null" values, setting the arg Class to null will be taken as a
    request to match any Class type. POSSIBLE PROBLEM: This may match
    a primitive type, which really should not accept a null value... but
    I'm not sure how best to distinguish those, short of enumerating them
    */
  static private boolean isMethodConvertable(Class parm, Class arg)
  {
    if (parm.equals(arg))       // If same class, short-circuit now!
      return true;

    // Accept any type EXCEPT primitives (which can't have null values).
    if (arg == null)
    {
      return !parm.isPrimitive();
    }

    // Arrays are convertable if their elements are convertable
    // ????? Does this have to be done before isAssignableFrom, or
    // does it successfully handle arrays of primatives?
    while(parm.isArray())
      {
        if(!arg.isArray())
          return false;         // Unequal array depth
        else
          {
            parm=parm.getComponentType();
            arg=arg.getComponentType();
          }
      }
    if(arg.isArray())
      return false;             // Unequal array depth
    
    // Despite its name, the 1.1.6 docs say that this function does
    // NOT return true for all legal ASSIGNMENT CONVERSIONS
    // (5.2):
    //   "Specifically, this method tests whether the type
    //   represented by the specified class can be converted
    //   to the type represented by this Class object via
    //   an identity conversion or via a widening reference
    //   conversion."
    if(parm.isAssignableFrom(arg))
      return true;

    // That leaves us the Widening Primitives case. Four possibilities:
    // void (can only convert to void), boolean (can only convert to boolean),
    // numeric (which are sequenced) and char (which inserts itself into the
    // numerics by promoting to int or larger)

    if(parm.equals(Void.TYPE) || parm.equals(Boolean.TYPE) ||
       arg.equals(Void.TYPE) || arg.equals(Boolean.TYPE))
      return false;
    
    Class[] primTypes={ Character.TYPE, Byte.TYPE, Short.TYPE, Integer.TYPE,
                        Long.TYPE, Float.TYPE, Double.TYPE };
    int parmscore,argscore;
    
    for(parmscore=0;parmscore<primTypes.length;++parmscore)
      if (parm.equals(primTypes[parmscore]))
        break;
    if(parmscore>=primTypes.length)
      return false;             // Off the end
    
    for(argscore=0;argscore<primTypes.length;++argscore)
      if (arg.equals(primTypes[argscore]))
        break;
    if(argscore>=primTypes.length)
      return false;             // Off the end
    
    // OK if ordered AND NOT char-to-smaller-than-int
    return (argscore<parmscore && (argscore!=0 || parmscore>2) );
  }
}