java.beans
Class Introspector

java.lang.Object
  |
  +--java.beans.Introspector

public class Introspector

extends Object

The Introspector class provides a standard way for tools to learn about the properties, events, and methods supported by a target Java Bean.

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.

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.

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".

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.

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).

Field Summary

private BeanInfo[]	additionalBeanInfo
private Class	beanClass
private static Hashtable	beanInfoCache
private static Hashtable	declaredMethodCache
private int	defaultEventIndex
private String	defaultEventName
private int	defaultPropertyIndex
private String	defaultPropertyName
private static Class	eventListenerType
private Hashtable	events
static int	IGNORE_ALL_BEANINFO
static int	IGNORE_IMMEDIATE_BEANINFO
private BeanInfo	informant
private Hashtable	methods
private Hashtable	properties
private boolean	propertyChangeSource
private static String[]	searchPath
private BeanInfo	superBeanInfo
static int	USE_ALL_BEANINFO

Constructor Summary

private

Introspector(Class beanClass, Class stopClass, int flags)

Method Summary

(package private) void	addEvent(EventSetDescriptor esd)
private void	addMethod(MethodDescriptor md)
(package private) void	addProperty(PropertyDescriptor pd)
static String	decapitalize(String name) Utility method to take a string and convert it to normal Java variable name capitalization.
private static BeanInfo	findInformant(Class beanClass)
(package private) static java.lang.reflect.Method	findMethod(Class cls, String methodName, int argCount) Find a target methodName on a given class.
static void	flushCaches() Flush all of the Introspector's internal caches.
static void	flushFromCaches(Class clz) Flush the Introspector's internal cached information for a given class.
private GenericBeanInfo	getBeanInfo()
static BeanInfo	getBeanInfo(Class beanClass) Introspect on a Java bean and learn about all its properties, exposed methods, and events.
static BeanInfo	getBeanInfo(Class beanClass, Class stopClass) Introspect on a Java bean and learn all about its properties, exposed methods, below a given "stop" point.
static BeanInfo	getBeanInfo(Class beanClass, int flags) Introspect on a Java bean and learn about all its properties, exposed methods, and events, subnject to some comtrol flags.
static String[]	getBeanInfoSearchPath() Gets the list of package names that will be used for finding BeanInfo classes.
private static java.lang.reflect.Method[]	getPublicDeclaredMethods(Class clz)
private BeanDescriptor	getTargetBeanDescriptor()
private int	getTargetDefaultEventIndex()
private int	getTargetDefaultPropertyIndex()
private EventSetDescriptor[]	getTargetEventInfo()
private MethodDescriptor[]	getTargetMethodInfo()
private PropertyDescriptor[]	getTargetPropertyInfo()
(package private) static Object	instantiate(Class sibling, String className) Try to create an instance of a named class.
private static java.lang.reflect.Method	internalFindMethod(Class start, String methodName, int argCount) Internal support for finding a target methodName on a given class.
private boolean	isEventHandler(java.lang.reflect.Method m)
(package private) static boolean	isSubclass(Class a, Class b) Return true if class a is either equivalent to class b, or if class a is a subclass of class b, i.e.
private String	makeQualifiedMethodName(MethodDescriptor md)
static void	setBeanInfoSearchPath(String[] path) Change the list of package names that will be used for finding BeanInfo classes.
private boolean	throwsException(java.lang.reflect.Method method, Class exception) Return true iff the given method throws the given exception.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

USE_ALL_BEANINFO

public static final int USE_ALL_BEANINFO

IGNORE_IMMEDIATE_BEANINFO

public static final int IGNORE_IMMEDIATE_BEANINFO

IGNORE_ALL_BEANINFO

public static final int IGNORE_ALL_BEANINFO

informant

private BeanInfo informant

propertyChangeSource

private boolean propertyChangeSource

beanClass

private Class beanClass

superBeanInfo

private BeanInfo superBeanInfo

additionalBeanInfo

private BeanInfo[] additionalBeanInfo

beanInfoCache

private static Hashtable beanInfoCache

eventListenerType

private static Class eventListenerType

defaultEventName

private String defaultEventName

defaultPropertyName

private String defaultPropertyName

defaultEventIndex

private int defaultEventIndex

defaultPropertyIndex

private int defaultPropertyIndex

methods

private Hashtable methods

declaredMethodCache

private static Hashtable declaredMethodCache

properties

private Hashtable properties

events

private Hashtable events

searchPath

private static String[] searchPath

Constructor Detail

Introspector

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

Method Detail

getBeanInfo

public static BeanInfo getBeanInfo(Class beanClass)
                            throws IntrospectionException

Introspect on a Java bean and learn about all its properties, exposed methods, and events.

Parameters:

beanClass - The bean class to be analyzed.

Returns:

A BeanInfo object describing the target bean.

Throws:

IntrospectionException - if an exception occurs during introspection.

getBeanInfo

public static BeanInfo getBeanInfo(Class beanClass,
                                   int flags)
                            throws IntrospectionException

Introspect on a Java bean and learn about all its properties, exposed methods, and events, subnject to some comtrol flags.

Parameters:

beanClass - The bean class to be analyzed.

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.

Returns:

A BeanInfo object describing the target bean.

Throws:

IntrospectionException - if an exception occurs during introspection.

getBeanInfo

public static BeanInfo getBeanInfo(Class beanClass,
                                   Class stopClass)
                            throws IntrospectionException

Introspect on a Java bean and learn all about its properties, exposed methods, below a given "stop" point.

Parameters:

bean - The bean class to be analyzed.

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.

Throws:

IntrospectionException - if an exception occurs during introspection.

decapitalize

public static String decapitalize(String name)

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.

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

Parameters:

name - The string to be decapitalized.

Returns:

The decapitalized version of the string.

getBeanInfoSearchPath

public static String[] getBeanInfoSearchPath()

Gets the list of package names that will be used for finding BeanInfo classes.

Returns:

The array of package names that will be searched in order to find BeanInfo classes.

This is initially set to {"sun.beans.infos"}.

setBeanInfoSearchPath

public static void setBeanInfoSearchPath(String[] path)

Change the list of package names that will be used for finding BeanInfo classes.

First, if there is a security manager, its checkPropertiesAccess method is called. This could result in a SecurityException.

Parameters:

path - Array of package names.

Throws:

SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow setting of system properties.

See Also:

SecurityManager.checkPropertiesAccess()

flushCaches

public static void flushCaches()

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.

flushFromCaches

public static void flushFromCaches(Class clz)

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.

Parameters:

clz - Class object to be flushed.

getBeanInfo

private GenericBeanInfo getBeanInfo()
                             throws IntrospectionException

findInformant

private static BeanInfo findInformant(Class beanClass)

getTargetPropertyInfo

private PropertyDescriptor[] getTargetPropertyInfo()
                                            throws IntrospectionException

Returns:

An array of PropertyDescriptors describing the editable properties supported by the target bean.

addProperty

void addProperty(PropertyDescriptor pd)

getTargetEventInfo

private EventSetDescriptor[] getTargetEventInfo()
                                         throws IntrospectionException

Returns:

An array of EventSetDescriptors describing the kinds of events fired by the target bean.

addEvent

void addEvent(EventSetDescriptor esd)

getTargetMethodInfo

private MethodDescriptor[] getTargetMethodInfo()
                                        throws IntrospectionException

Returns:

An array of MethodDescriptors describing the private methods supported by the target bean.

addMethod

private void addMethod(MethodDescriptor md)

makeQualifiedMethodName

private String makeQualifiedMethodName(MethodDescriptor md)

getTargetDefaultEventIndex

private int getTargetDefaultEventIndex()

getTargetDefaultPropertyIndex

private int getTargetDefaultPropertyIndex()

getTargetBeanDescriptor

private BeanDescriptor getTargetBeanDescriptor()
                                        throws IntrospectionException

isEventHandler

private boolean isEventHandler(java.lang.reflect.Method m)
                        throws IntrospectionException

getPublicDeclaredMethods

private static java.lang.reflect.Method[] getPublicDeclaredMethods(Class clz)

internalFindMethod

private static java.lang.reflect.Method internalFindMethod(Class start,
                                                           String methodName,
                                                           int argCount)

Internal support for finding a target methodName on a given class.

findMethod

static java.lang.reflect.Method findMethod(Class cls,
                                           String methodName,
                                           int argCount)
                                    throws IntrospectionException

Find a target methodName on a given class.

isSubclass

static boolean isSubclass(Class a,
                          Class b)

Return true if class a is either equivalent to class b, or if class a is a subclass of class b, i.e. if a either "extends" or "implements" b. Note tht either or both "Class" objects may represent interfaces.

throwsException

private boolean throwsException(java.lang.reflect.Method method,
                                Class exception)

Return true iff the given method throws the given exception.

instantiate

static Object instantiate(Class sibling,
                          String className)
                   throws InstantiationException,
                          IllegalAccessException,
                          ClassNotFoundException

Try to create an instance of a named class. First try the classloader of "sibling", then try the system classloader.