BeanInfo classes and introspection

If you are creating new components or beans for use within the visual editor (for example, adding components to the palette), you can control their behavior by supplying a BeanInfo class.

A BeanInfo class implements java.beans.BeanInfo and is used by the visual editor to determine the behavior of the properties view for the bean, and whether a customizer is available. The visual editor includes BeanInfo classes for common AWT and Swing controls.

Since the BeanInfo class contains information required only at design time, it is usually kept in a different project from the bean class itself and not included when the bean is deployed. The visual editor for Java uses a number of rules that allow you to associate BeanInfo classes with the Java beans they describe. You need to understand these rules if you are using Java beans having BeanInfo classes that you want the visual editor to detect. For instance, if you are using a third party set of Java bean classes, or if you have developed Java beans and BeanInfo classes that you are using.

To learn more about BeanInfo classes you can download the JavaBeans specification from java.sun.com/products/javabeans/docs/.

 

Background

The class java.beans.Introspector is used to locate a BeanInfo class for a Java bean. The time that this occurs is referred to as introspection, and is done by the visual editor the first time a bean is used. For example, when a button is first dropped from the palette, introspection occurs that tries to locate the correct BeanInfo class. After introspecting the bean, the results are cached to help performance. However, when the visual editor detects that the BeanInfo class may have changed and the cache is stale, introspection will re-occur.

Introspection of a bean is done by calling the getBeanInfo(Class) static method with the bean class as the argument. For example:

java.beans.Introspector.getBeanInfo(MyJavaBean.class)

The introspector uses the following logic to locate a BeanInfo class for the argument class MyJavaBean. This involves a number of sequential steps, and after any successful step the introspector stops looking. If any step fails, then the next step is used to try a different way to locate the bean info.

• If the Java bean itself implements java.beans.BeanInfo, then it is used. This scenario rarely occurs, however, because it means that the run-time class MyJavaBean contains design time information that will be unnecessarily included at deployment.

• A class with the same name as the argument, but the string BeanInfo appended to it is searched for. For example, MyJavaBeanBeanInfo. It is first searched for in the same package as the class, and if one is not found, it is located within a defined search path. Rather than use the class path of the Java virtual machine to search for the BeanInfo class, the introspector has its own list of packages to search within. This is known as the BeanInfo search path. The introspector does not use the class path again in order to keep run-time and design time information separate.

• If no BeanInfo class is found for the immediate class being introspected, then the introspector attempts to locate the BeanInfo class for the superclass.

• If no BeanInfo class is found for the immediate class being introspected, then a default one is created. The default will take the results of the introspection of the immediate superclass and merge in the results of the default properties of the immediate class. The rules for creating the default properties are to match get and set methods with compatible names and arguments. For example, the method public void setName(String aName) and public String getName() are paired into a property called name. The BeanInfo created is not stored as a class in any package. It is a transient instance that is used as a temporary description of the bean's design time details, so that the visual editor can extract a list of properties and other information.

If a BeanInfo class is found for the class, then the introspector does not return it explicitly. Instead, it uses its details to create a temporary result class that implements java.beans.BeanInfo.

 

BeanInfo search path

The best way to understand the BeanInfo path is to consider the Java virtual machine that is created to perform introspection. This virtual machine is given a class path that is made up of following entries:

• The items in the Java build path for the project itself

• The items in the BeanInfo classes on the BeanInfo path for the project itself

• All exported items in the BeanInfo classes for any projects in the Java build path

Having created the virtual machine, the java.beans.Introspector has its list of packages to search for BeanInfo classes set with the method public void setSearchPath(String[]).

The arguments to this method are:

• The items in the packages list on the BeanInfo path for the project itself

• All exported items in the packages lists for any projects in the Java build path

 

BeanInfo and inherent attributes

If the bean you are writing is inheriting attributes from a super class, the default BeanInfo will not expose the inherent attributes. You have to explicitly expose them with the getAdditionalBeanInfo() method.

For example:

public BeanInfo[] getAdditionalBeanInfo() { 
try {                 
         // The following will return all inherited features.                 
         return new BeanInfo[] { 
Introspector.getBeanInfo(MyPanel.class.getSuperclass())};  
} catch (IntrospectionException e) {            
return new BeanInfo[0];            
} 

If an inherent attribute is not exposed, the visual editor will not render it, even if it is set in the source code.

BeanInfo classes for JRE classes
The Java beans for classes included in the JRE are supplied as part of the visual editor for Java. These define the behavior of classes such as javax.swing.JButton or javax.swing.JFrame inside the workbench.

Tips for writing BeanInfo classes for the visual editor
This section describes some rules you can employ if you are writing a BeanInfo class for a Java bean intended for use in the visual editor for Java.

Controlling BeanInfo information for plug-in developers
You can exercise control over how the BeanInfo classes are associated with a class path variable by adding an entry in a plug-in manifest file.

 

Parent topic

Extending the visual editor for Java

 

Related tasks

Controlling BeanInfo information for plug-in developers
Specifying the location of BeanInfo classes