* 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). *
* For more information about introspection and design patterns, please
* consult the
* JavaBeans™ specification.
*/
public class Introspector {
// Flags that can be used to control getBeanInfo:
/**
* Flag to indicate to use of all beaninfo.
*/
public final static int USE_ALL_BEANINFO = 1;
/**
* Flag to indicate to ignore immediate beaninfo.
*/
public final static int IGNORE_IMMEDIATE_BEANINFO = 2;
/**
* Flag to indicate to ignore all beaninfo.
*/
public final static int IGNORE_ALL_BEANINFO = 3;
// Static Caches to speed up introspection.
private static final WeakCache
* 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();
}
ThreadGroupContext context = ThreadGroupContext.getContext();
BeanInfo beanInfo;
synchronized (declaredMethodCache) {
beanInfo = context.getBeanInfo(beanClass);
}
if (beanInfo == null) {
beanInfo = new Introspector(beanClass, null, USE_ALL_BEANINFO).getBeanInfo();
synchronized (declaredMethodCache) {
context.putBeanInfo(beanClass, beanInfo);
}
}
return beanInfo;
}
/**
* Introspect on a Java bean and learn about all its properties, exposed
* methods, and events, subject to some control flags.
*
* 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.
*
* 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.
* @return the BeanInfo for the bean
* @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}.
*
* 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.
*
* 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() {
return ThreadGroupContext.getContext().getBeanInfoFinder().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.
*
* First, if there is a security manager, its
* Used in the contructors of the EventSetDescriptor,
* PropertyDescriptor and the IndexedPropertyDescriptor.
*
* @param cls The Class object on which to retrieve the method.
* @param methodName Name of the method.
* @param argCount Number of arguments for the desired method.
* @param args Array of argument types for the method.
* @return the method or null if not found
*/
static Method findMethod(Class cls, String methodName, int argCount,
Class args[]) {
if (methodName == null) {
return null;
}
return internalFindMethod(cls, methodName, argCount, args);
}
/**
* 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.
*/
static boolean isSubclass(Class a, Class b) {
// We rely on the fact that for any given java class or
// primtitive type there is a unqiue Class object, so
// we can use object equivalence in the comparisons.
if (a == b) {
return true;
}
if (a == null || b == null) {
return false;
}
for (Class x = a; x != null; x = x.getSuperclass()) {
if (x == b) {
return true;
}
if (b.isInterface()) {
Class[] interfaces = x.getInterfaces();
for (int i = 0; i < interfaces.length; i++) {
if (isSubclass(interfaces[i], b)) {
return true;
}
}
}
}
return false;
}
/**
* Return true iff the given method throws the given exception.
*/
private boolean throwsException(Method method, Class exception) {
Class exs[] = method.getExceptionTypes();
for (int i = 0; i < exs.length; i++) {
if (exs[i] == exception) {
return true;
}
}
return false;
}
/**
* Try to create an instance of a named class.
* First try the classloader of "sibling", then try the system
* classloader then the class loader of the current Thread.
*/
static Object instantiate(Class sibling, String className)
throws InstantiationException, IllegalAccessException,
ClassNotFoundException {
// First check with sibling's classloader (if any).
ClassLoader cl = sibling.getClassLoader();
Class cls = ClassFinder.findClass(className, cl);
return cls.newInstance();
}
} // end class Introspector
//===========================================================================
/**
* Package private implementation support class for Introspector's
* internal use.
*
* Mostly this is used as a placeholder for the descriptors.
*/
class GenericBeanInfo extends SimpleBeanInfo {
private BeanDescriptor beanDescriptor;
private EventSetDescriptor[] events;
private int defaultEvent;
private PropertyDescriptor[] properties;
private int defaultProperty;
private MethodDescriptor[] methods;
private Reference
*
* Any methods/properties/events in the {@code stopClass}
* or in its parent classes will be ignored in the analysis.
* checkPropertiesAccess
* method is called. This could result in a SecurityException.
*
* @param path Array of package names.
* @exception SecurityException if a security manager exists and its
* checkPropertiesAccess 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();
}
ThreadGroupContext.getContext().getBeanInfoFinder().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() {
synchronized (declaredMethodCache) {
ThreadGroupContext.getContext().clearBeanInfoCache();
declaredMethodCache.clear();
}
}
/**
* 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();
}
synchronized (declaredMethodCache) {
ThreadGroupContext.getContext().removeBeanInfo(clz);
declaredMethodCache.put(clz, null);
}
}
//======================================================================
// 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) {
return ThreadGroupContext.getContext().getBeanInfoFinder().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) {
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)) {
// Optimization. Don't bother with invalid propertyNames.
continue;
}
try {
if (argCount == 0) {
if (name.startsWith(GET_PREFIX)) {
// Simple getter
pd = new PropertyDescriptor(this.beanClass, name.substring(3), method, null);
} else if (resultType == boolean.class && name.startsWith(IS_PREFIX)) {
// Boolean getter
pd = new PropertyDescriptor(this.beanClass, name.substring(2), method, null);
}
} else if (argCount == 1) {
if (int.class.equals(argTypes[0]) && name.startsWith(GET_PREFIX)) {
pd = new IndexedPropertyDescriptor(this.beanClass, name.substring(3), null, null, method, null);
} else if (void.class.equals(resultType) && name.startsWith(SET_PREFIX)) {
// Simple setter
pd = new PropertyDescriptor(this.beanClass, name.substring(3), null, method);
if (throwsException(method, PropertyVetoException.class)) {
pd.setConstrained(true);
}
}
} else if (argCount == 2) {
if (void.class.equals(resultType) && int.class.equals(argTypes[0]) && name.startsWith(SET_PREFIX)) {
pd = new IndexedPropertyDescriptor(this.beanClass, name.substring(3), null, null, null, method);
if (throwsException(method, PropertyVetoException.class)) {
pd.setConstrained(true);
}
}
}
} catch (IntrospectionException ex) {
// This happens if a PropertyDescriptor or IndexedPropertyDescriptor
// constructor fins that the method violates details of the deisgn
// pattern, e.g. by having an empty name, or a getter returning
// void , or whatever.
pd = null;
}
if (pd != null) {
// If this class or one of its base classes is a PropertyChange
// source, then we assume that any properties we discover are "bound".
if (propertyChangeSource) {
pd.setBound(true);
}
addPropertyDescriptor(pd);
}
}
}
processPropertyDescriptors();
// Allocate and populate the result array.
PropertyDescriptor result[] =
properties.values().toArray(new PropertyDescriptor[properties.size()]);
// Set the default index.
if (defaultPropertyName != null) {
for (int i = 0; i < result.length; i++) {
if (defaultPropertyName.equals(result[i].getName())) {
defaultPropertyIndex = i;
}
}
}
return result;
}
private HashMap