JavaBean Attributes

Introduction

Sun's BeanInfo descriptors were designed with builder-specific extension in mind. Developers of bean builders could allow bean authors to add extra metadata to describe the beans, and the builder tool could take advantage of the extra metadata for enhanced functionality.

A good example of this is VisualAge for Java's use of "preferred" as an attribute. VisualAge users wanted some way to specify that a property, method, or event appear on the "short list" of features that appear during connection creation (without requiring a popup dialog with a list of all features). IBM added support for a "preferred" attribute, and if bean authors set "preferred" to Boolean.TRUE, VisualAge added the feature to the "short list".

(Note that eventually Sun added the isPreferred() method to FeatureDescriptor for this same function.)

Unfortunately, these extensions are not well documented, and difficult to find. I've collected the following definitions from various sources (the Sun Java source code, Sun's bean builder source, and various web searches) to help create a common place to define commonly-used BeanInfo attributes.

If you know of any commonly-used beaninfo attribute that is not listed here, or if you see an error in one of these descriptions, please email me at scott@javadude.com.

Commonly-Used BeanInfo Attributes

Sun has a BeanInfo generator that generates the BeanInfo for Swing etc using a javadoc @beaninfo tag. It sets up several kinds of attributes. I've found the following list of commonly-used attributes. We should reuse where possible. (I gathered this list doing some web searches, looking at source code for sun's bean builder, etc...)

The format of the following table is

attributeName
(Who defined it)

ApplicableDescriptors

 Description, possible values, examples

Note that in the following table I use FeatureDescriptors for ApplicableDescriptors to refer to attributes that apply to any feature descriptor. This includes BeanDescriptor, PropertyDescriptor, MethodDescriptor, and EventSetDescriptor.

enumerationValues
(Sun)

PropertyDescriptors

Defines an Object[] that specifies a list of valid values. This function could be provided by implementing a custom PropertyEditor (see my Property Editor Tutorial), but that's really overkill.

The Object[] contains sets of three values:

  • name - A displayable name for the value
  • value - the actual property value to use, (an Object of the property's type)
  • java initialization string - a string that can be used when generating code

For example:

Figure 1: Enumeration values

Object[] enumerationValues = new Object[] {

    "vertical",   new Integer(JSlider.VERTICAL),   "JSlider.VERTICAL",

    "horizontal", new Integer(JSlider.HORIZONTAL), "JSlider.HORIZONTAL"

};

propertyDescriptor.setValue("enumerationValues", enumerationValues);
propertyorder
(?)

BeanDescriptors

 Defines the order in which properties should be displayed by builder tools.

I've heard reference to this attribute but haven't found how it's formatted. It sounded like it has been used as a list of indices into the property descriptor array, but I'm not sure.

I've also heard some folks mention that it might be more useful as a Comparator object; again, no examples seen.
isContainer
(Sun)

BeanDescriptors

 Helps a GUI builder determine if it should treat a bean as a container; should it allow other beans to be dropped in it?

This was added primarily for Swing. All Swing components inherit from java.awt.Container (that's a long story -- in short, AWT's design was flawed because Container was a class instead of an interface...).

For Swing components, bean builder tools couldn't decide if they should allow other components to be dropped into a JButton. They needed some indication on the intended use of a Swing component.

Boolean.TRUE
GUI builder should allow use as a container
Boolean.FALSE
otherwise
containerDelegate
(Sun)

BeanDescriptors

 Sometimes the actual container that objects can be added to isn't directly the bean being displayed on a builder. JFrame, for example, does not allow you to add components directly to it. Instead, you need to add those components to its contentPane.

To support this, Sun added a containerDelegate attribute to BeanDescriptors. Its value is the name of a method that takes no arguments and returns a Container.

For example (similar to JFrame's BeanInfo, defining its BeanDescriptor)

Figure 2: Container delegate

beanDescriptor.setValue("containerDelegate", "getContentPane");
preferred
(IBM, now others and in FeatureDescriptor)

FeatureDescriptors

 I'm pretty sure I started this one ;)

VisualAge for Java users asked for a way to specify that a property should be included on the "short list" of properties that comes up in a popup menu when making connections (instead of having to bring up a dialog). I suggested to IBM that they use a property descriptor attribute, so they started looking for an attribute named "preferred" and set up support in VAJ to set it.

This is now available directly in FeatureDescriptor as the isPreferred() method. For compatability, bean builder tools should check isPreferred() and the "preferred" attribute of a feature.

Boolean.TRUE
The feature is considered one that will be used/changed often in a builder. If there is a simplified way to work with features, this feature should be accessible there.
Boolean.FALSE
otherwise
lateSetting
(Borland)

PropertyDescriptors

 This attribute provides a hint to a bean builder that the property should be set "late". Borland defines this as "after the add calls".

Personally I think this is bad design -- a proper bean shouldn't care in which order its properties are set...

Boolean.TRUE
The bean builder should set up code to set the property as late as possible, preferably after any child components have been added to the bean instance in question.
Boolean.FALSE
otherwise
details
(InstallShield)

FeatureDescriptors

 Specifies help text for a bean property.

This appears to be intended to be end user help text, not bean builder help text (like the name and description in a FeatureDescriptor).
 
category
(NetBeans)

FeatureDescriptors

 Specifies a single "categories" to which the described feature belongs. This allows builder tools to organize features at build time or run time.

(Thanks to Richard Bair for pointing this out)
categories
(InstallShield)

FeatureDescriptors

 Specifies a list of "categories" to which the described feature belongs. This allows builder tools to organize features at build time or run time.

The format used by InstallShield is

Figure 3: InstallShield categories

"'/Some Category' '/Another Category' '/Some Category/Sub Category'"
persistenceDelegate
(Sun)

BeanDescriptor

Specifies an instance of a class that extends PersistenceDelegate that can be used to persist an instance of this bean. A bean builder should use the specified delegate instead of Java's serialization mechanism for saving the state of the bean if using persistence as the means to generate an application.

Note that the value is an instance of a class, not the name of a class or a Class object.
proxyComponent
(Sun)

BeanDescriptor

 Returns the name of a visual component class that should be used to visually represent a non-visual component.

For example, suppose you define a Person bean that's not an AWT/Swing component. You could define a PersonRepresentation that extends (for example) and define that that object should be used to display the Person in a GUI builder.

The bean builder will create a unique instance of the proxy for each bean instance, Any manipulation done on the proxy is also performed on the bean.

Note: I'm still a tad unclear on the actual mapping of operations like "add" when adding a child to the visual component. I'm still examining the Sun bean builder code to get a better idea of this.
 
transient
(Sun)

PropertyDescriptor

 Indicates that a property's value shouldn't be persisted/added to generated code.

I'm not sure about this one -- why consider it a property??? debugging in builder???

Sun's bean builder code has a comment about this being used to workaround an introspector bug. hmmm...
 
visualUpdate
(Sun)

PropertyDescriptors
MethodDescriptors

 I didn't see this in Sun's bean builder, but it's in the Swing javadoc @beaninfo descriptions.

This appears to be an indication that calling the method will require updating the visuals of the GUI.

I'm not sure at this point if this means the called method will perform the update, or if a builder should perform/generate the update code... I'm thinking the former, but I'm not sure.