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