/*

 * Copyright 1996-2009 Sun Microsystems, Inc.  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.  Sun designates this

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

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.beans;

import com.sun.beans.finder.BeanInfoFinder;

import com.sun.beans.finder.ClassFinder;

import java.lang.reflect.Method;

import java.lang.reflect.Modifier;

import java.util.Map;

import java.util.ArrayList;

import java.util.HashMap;

import java.util.Iterator;

import java.util.EventListener;

import java.util.List;

import java.util.TreeMap;

import sun.awt.AppContext;

import sun.reflect.misc.ReflectUtil;

/**

 * The Introspector class provides a standard way for tools to learn about

 * the properties, events, and methods supported by a target Java Bean.

 * <p>

 * For each of those three kinds of information, the Introspector will

 * separately analyze the bean's class and superclasses looking for

 * either explicit or implicit information and use that information to

 * build a BeanInfo object that comprehensively describes the target bean.

 * <p>

 * For each class "Foo", explicit information may be available if there exists

 * a corresponding "FooBeanInfo" class that provides a non-null value when

 * queried for the information.   We first look for the BeanInfo class by

 * taking the full package-qualified name of the target bean class and

 * appending "BeanInfo" to form a new class name.  If this fails, then

 * we take the final classname component of this name, and look for that

 * class in each of the packages specified in the BeanInfo package search

 * path.

 * <p>

 * Thus for a class such as "sun.xyz.OurButton" we would first look for a

 * BeanInfo class called "sun.xyz.OurButtonBeanInfo" and if that failed we'd

 * look in each package in the BeanInfo search path for an OurButtonBeanInfo

 * class.  With the default search path, this would mean looking for

 * "sun.beans.infos.OurButtonBeanInfo".

 * <p>

 * If a class provides explicit BeanInfo about itself then we add that to

 * the BeanInfo information we obtained from analyzing any derived classes,

 * but we regard the explicit information as being definitive for the current

 * class and its base classes, and do not proceed any further up the superclass

 * chain.

 * <p>

 * If we don't find explicit BeanInfo on a class, we use low-level

 * reflection to study the methods of the class and apply standard design

 * patterns to identify property accessors, event sources, or public

 * methods.  We then proceed to analyze the class's superclass and add

 * in the information from it (and possibly on up the superclass chain).

 *

 * <p>

 * Because the Introspector caches BeanInfo classes for better performance,

 * take care if you use it in an application that uses

 * multiple class loaders.

 * In general, when you destroy a <code>ClassLoader</code>

 * that has been used to introspect classes,

 * you should use the

 * {@link #flushCaches <code>Introspector.flushCaches</code>}

 * or

 * {@link #flushFromCaches <code>Introspector.flushFromCaches</code>} method

 * to flush all of the introspected classes out of the cache.

 *

 * <P>

 * For more information about introspection and design patterns, please

 * consult the

 *  <a href="http://java.sun.com/products/javabeans/docs/index.html">JavaBeans specification</a>.

 */

public class Introspector {

    // Flags that can be used to control getBeanInfo:

    public final static int USE_ALL_BEANINFO           = 1;

    public final static int IGNORE_IMMEDIATE_BEANINFO  = 2;

    public final static int IGNORE_ALL_BEANINFO        = 3;

    // Static Caches to speed up introspection.

    private static final Object BEANINFO_CACHE = new Object();

    private Class beanClass;

    private BeanInfo explicitBeanInfo;

    private BeanInfo superBeanInfo;

    private BeanInfo additionalBeanInfo[];

    private boolean propertyChangeSource = false;

    private static Class eventListenerType = EventListener.class;

    // These should be removed.

    private String defaultEventName;

    private String defaultPropertyName;

    private int defaultEventIndex = -1;

    private int defaultPropertyIndex = -1;

    // Methods maps from Method objects to MethodDescriptors

    private Map methods;

    // properties maps from String names to PropertyDescriptors

    private Map properties;

    // events maps from String names to EventSetDescriptors

    private Map events;

    private final static EventSetDescriptor[] EMPTY_EVENTSETDESCRIPTORS = new EventSetDescriptor[0];

    static final String ADD_PREFIX = "add";

    static final String REMOVE_PREFIX = "remove";

    static final String GET_PREFIX = "get";

    static final String SET_PREFIX = "set";

    static final String IS_PREFIX = "is";

    private static final Object FINDER_KEY = new Object();

    //======================================================================

    //                          Public methods

    //======================================================================

    /**

     * Introspect on a Java Bean and learn about all its properties, exposed

     * methods, and events.

     * <p>

     * If the BeanInfo class for a Java Bean has been previously Introspected

     * then the BeanInfo class is retrieved from the BeanInfo cache.

     *

     * @param beanClass  The bean class to be analyzed.

     * @return  A BeanInfo object describing the target bean.

     * @exception IntrospectionException if an exception occurs during

     *              introspection.

     * @see #flushCaches

     * @see #flushFromCaches

     */

    public static BeanInfo getBeanInfo(Class<?> beanClass)

        throws IntrospectionException

    {

        if (!ReflectUtil.isPackageAccessible(beanClass)) {

            return (new Introspector(beanClass, null, USE_ALL_BEANINFO)).getBeanInfo();

        }

        synchronized (BEANINFO_CACHE) {

            }

        }

    }

    /**

     * Introspect on a Java bean and learn about all its properties, exposed

     * methods, and events, subject to some control flags.

     * <p>

     * If the BeanInfo class for a Java Bean has been previously Introspected

     * based on the same arguments then the BeanInfo class is retrieved

     * from the BeanInfo cache.

     *

     * @param beanClass  The bean class to be analyzed.

     * @param flags  Flags to control the introspection.

     *     If flags == USE_ALL_BEANINFO then we use all of the BeanInfo

     *          classes we can discover.

     *     If flags == IGNORE_IMMEDIATE_BEANINFO then we ignore any

     *           BeanInfo associated with the specified beanClass.

     *     If flags == IGNORE_ALL_BEANINFO then we ignore all BeanInfo

     *           associated with the specified beanClass or any of its

     *           parent classes.

     * @return  A BeanInfo object describing the target bean.

     * @exception IntrospectionException if an exception occurs during

     *              introspection.

     */

    public static BeanInfo getBeanInfo(Class<?> beanClass, int flags)

                                                throws IntrospectionException {

        return getBeanInfo(beanClass, null, flags);

    }

    /**

     * Introspect on a Java bean and learn all about its properties, exposed

     * methods, below a given "stop" point.

     * <p>

     * If the BeanInfo class for a Java Bean has been previously Introspected

     * based on the same arguments, then the BeanInfo class is retrieved

     * from the BeanInfo cache.

     *

     * @param beanClass The bean class to be analyzed.

     * @param stopClass The baseclass at which to stop the analysis.  Any

     *    methods/properties/events in the stopClass or in its baseclasses

     *    will be ignored in the analysis.

     * @exception IntrospectionException if an exception occurs during

     *              introspection.

     */

    public static BeanInfo getBeanInfo(Class<?> beanClass, Class<?> stopClass)

                                                throws IntrospectionException {

        return getBeanInfo(beanClass, stopClass, USE_ALL_BEANINFO);

    }

    /**

     * Introspect on a Java Bean and learn about all its properties,

     * exposed methods and events, below a given {@code stopClass} point

     * subject to some control {@code flags}.

     * <dl>

     *  <dt>USE_ALL_BEANINFO</dt>

     *  <dd>Any BeanInfo that can be discovered will be used.</dd>

     *  <dt>IGNORE_IMMEDIATE_BEANINFO</dt>

     *  <dd>Any BeanInfo associated with the specified {@code beanClass} will be ignored.</dd>

     *  <dt>IGNORE_ALL_BEANINFO</dt>

     *  <dd>Any BeanInfo associated with the specified {@code beanClass}

     *      or any of its parent classes will be ignored.</dd>

     * </dl>

     * Any methods/properties/events in the {@code stopClass}

     * or in its parent classes will be ignored in the analysis.

     * <p>

     * If the BeanInfo class for a Java Bean has been

     * previously introspected based on the same arguments then

     * the BeanInfo class is retrieved from the BeanInfo cache.

     *

     * @param beanClass  the bean class to be analyzed

     * @param stopClass  the parent class at which to stop the analysis

     * @param flags      flags to control the introspection

     * @return a BeanInfo object describing the target bean

     * @exception IntrospectionException if an exception occurs during introspection

     *

     * @since 1.7

     */

    public static BeanInfo getBeanInfo(Class<?> beanClass, Class<?> stopClass,

                                        int flags) throws IntrospectionException {

        BeanInfo bi;

        if (stopClass == null && flags == USE_ALL_BEANINFO) {

            // Same parameters to take advantage of caching.

            bi = getBeanInfo(beanClass);

        } else {

            bi = (new Introspector(beanClass, stopClass, flags)).getBeanInfo();

        }

        return bi;

        // Old behaviour: Make an independent copy of the BeanInfo.

        //return new GenericBeanInfo(bi);

    }

    /**

     * Utility method to take a string and convert it to normal Java variable

     * name capitalization.  This normally means converting the first

     * character from upper case to lower case, but in the (unusual) special

     * case when there is more than one character and both the first and

     * second characters are upper case, we leave it alone.

     * <p>

     * Thus "FooBah" becomes "fooBah" and "X" becomes "x", but "URL" stays

     * as "URL".

     *

     * @param  name The string to be decapitalized.

     * @return  The decapitalized version of the string.

     */

    public static String decapitalize(String name) {

        if (name == null || name.length() == 0) {

            return name;

        }

        if (name.length() > 1 && Character.isUpperCase(name.charAt(1)) &&

                        Character.isUpperCase(name.charAt(0))){

            return name;

        }

        char chars[] = name.toCharArray();

        chars[0] = Character.toLowerCase(chars[0]);

        return new String(chars);

    }

    /**

     * Gets the list of package names that will be used for

     *          finding BeanInfo classes.

     *

     * @return  The array of package names that will be searched in

     *          order to find BeanInfo classes. The default value

     *          for this array is implementation-dependent; e.g.

     *          Sun implementation initially sets to {"sun.beans.infos"}.

     */

    public static String[] getBeanInfoSearchPath() {

        BeanInfoFinder finder = getFinder();

        synchronized (finder) {

            return finder.getPackages();

        }

    }

    /**

     * Change the list of package names that will be used for

     *          finding BeanInfo classes.  The behaviour of

     *          this method is undefined if parameter path

     *          is null.

     *

     * <p>First, if there is a security manager, its <code>checkPropertiesAccess</code>

     * method is called. This could result in a SecurityException.

     *

     * @param path  Array of package names.

     * @exception  SecurityException  if a security manager exists and its

     *             <code>checkPropertiesAccess</code> method doesn't allow setting

     *              of system properties.

     * @see SecurityManager#checkPropertiesAccess

     */

    public static void setBeanInfoSearchPath(String[] path) {

        SecurityManager sm = System.getSecurityManager();

        if (sm != null) {

            sm.checkPropertiesAccess();

        }

        BeanInfoFinder finder = getFinder();

        synchronized (finder) {

            finder.setPackages(path);

        }

    }

    /**

     * Flush all of the Introspector's internal caches.  This method is

     * not normally required.  It is normally only needed by advanced

     * tools that update existing "Class" objects in-place and need

     * to make the Introspector re-analyze existing Class objects.

     */

    public static void flushCaches() {

        }

    }

    /**

     * Flush the Introspector's internal cached information for a given class.

     * This method is not normally required.  It is normally only needed

     * by advanced tools that update existing "Class" objects in-place

     * and need to make the Introspector re-analyze an existing Class object.

     *

     * Note that only the direct state associated with the target Class

     * object is flushed.  We do not flush state for other Class objects

     * with the same name, nor do we flush state for any related Class

     * objects (such as subclasses), even though their state may include

     * information indirectly obtained from the target Class object.

     *

     * @param clz  Class object to be flushed.

     * @throws NullPointerException If the Class object is null.

     */

    public static void flushFromCaches(Class<?> clz) {

        if (clz == null) {

            throw new NullPointerException();

        }

        }

    }

    //======================================================================

    //                  Private implementation methods

    //======================================================================

    private Introspector(Class beanClass, Class stopClass, int flags)

                                            throws IntrospectionException {

        this.beanClass = beanClass;

        // Check stopClass is a superClass of startClass.

        if (stopClass != null) {

            boolean isSuper = false;

            for (Class c = beanClass.getSuperclass(); c != null; c = c.getSuperclass()) {

                if (c == stopClass) {

                    isSuper = true;

                }

            }

            if (!isSuper) {

                throw new IntrospectionException(stopClass.getName() + " not superclass of " +

                                        beanClass.getName());

            }

        }

        if (flags == USE_ALL_BEANINFO) {

            explicitBeanInfo = findExplicitBeanInfo(beanClass);

        }

        Class superClass = beanClass.getSuperclass();

        if (superClass != stopClass) {

            int newFlags = flags;

            if (newFlags == IGNORE_IMMEDIATE_BEANINFO) {

                newFlags = USE_ALL_BEANINFO;

            }

            superBeanInfo = getBeanInfo(superClass, stopClass, newFlags);

        }

        if (explicitBeanInfo != null) {

            additionalBeanInfo = explicitBeanInfo.getAdditionalBeanInfo();

        }

        if (additionalBeanInfo == null) {

            additionalBeanInfo = new BeanInfo[0];

        }

    }

    /**

     * Constructs a GenericBeanInfo class from the state of the Introspector

     */

    private BeanInfo getBeanInfo() throws IntrospectionException {

        // the evaluation order here is import, as we evaluate the

        // event sets and locate PropertyChangeListeners before we

        // look for properties.

        BeanDescriptor bd = getTargetBeanDescriptor();

        MethodDescriptor mds[] = getTargetMethodInfo();

        EventSetDescriptor esds[] = getTargetEventInfo();

        PropertyDescriptor pds[] = getTargetPropertyInfo();

        int defaultEvent = getTargetDefaultEventIndex();

        int defaultProperty = getTargetDefaultPropertyIndex();

        return new GenericBeanInfo(bd, esds, defaultEvent, pds,

                        defaultProperty, mds, explicitBeanInfo);

    }

    /**

     * Looks for an explicit BeanInfo class that corresponds to the Class.

     * First it looks in the existing package that the Class is defined in,

     * then it checks to see if the class is its own BeanInfo. Finally,

     * the BeanInfo search path is prepended to the class and searched.

     *

     * @param beanClass  the class type of the bean

     * @return Instance of an explicit BeanInfo class or null if one isn't found.

     */

    private static BeanInfo findExplicitBeanInfo(Class beanClass) {

        BeanInfoFinder finder = getFinder();

        synchronized (finder) {

            return finder.find(beanClass);

        }

    }

    /**

     * @return An array of PropertyDescriptors describing the editable

     * properties supported by the target bean.

     */

    private PropertyDescriptor[] getTargetPropertyInfo() {

        // Check if the bean has its own BeanInfo that will provide

        // explicit information.

        PropertyDescriptor[] explicitProperties = null;

        if (explicitBeanInfo != null) {

            explicitProperties = getPropertyDescriptors(this.explicitBeanInfo);

        }

        if (explicitProperties == null && superBeanInfo != null) {

            // We have no explicit BeanInfo properties.  Check with our parent.

            addPropertyDescriptors(getPropertyDescriptors(this.superBeanInfo));

        }

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

            addPropertyDescriptors(additionalBeanInfo[i].getPropertyDescriptors());

        }

        if (explicitProperties != null) {

            // Add the explicit BeanInfo data to our results.

            addPropertyDescriptors(explicitProperties);

        } else {

            // Apply some reflection to the current class.

            // First get an array of all the public methods at this level

            Method methodList[] = getPublicDeclaredMethods(beanClass);

            // Now analyze each method.

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

                Method method = methodList[i];

                if (method == null || method.isSynthetic()) {

                    continue;

                }

                // skip static methods.

                int mods = method.getModifiers();

                if (Modifier.isStatic(mods)) {

                    continue;

                }

                String name = method.getName();

                Class argTypes[] = method.getParameterTypes();

                Class resultType = method.getReturnType();

                int argCount = argTypes.length;

                PropertyDescriptor pd = null;

                if (name.length() <= 3 && !name.startsWith(IS_PREFIX)) {