Knowledge Center

BeanHelpers

Overview
Goals
Architecture overview
     com.beanexplorer.beans
     com.beanexplorer.editors
Java Introspection
Definition of additional meta information
     Constants declaration
     Type safety
     Properties order
     Semantic control of property values
     Other meta data
Property Editor extension
     Composite editor
Modification of behavior of the properties at runtime
Hierarchy of the properties
     Property types and their customization
     Controlling array items
     Merging
Summary table

Overview

BeanHelpers is an extension of JavaBeans^TM technology that is used to implement JavaBeans with an advanced functionality. These beans are still backward compatible with JavaBeans technology but when used with one of the Property Inspectors provided by BeanExplorer^TM the extensions are recognized and used to enhance user interface.

Goals

Backward compatibility with JavaBeans technology.

Definition of additional meta information about the bean and its properties.

Possibility to specify an order of properties explicitly.

Implementation of advanced editors for the properties of standard types.

Modification of behavior of the properties at runtime by the bean or the application.

Possibility to add and remove properties at runtime.

Architecture Overview

BeanHelpers consist of two java packages: com.beanexplorer.beans and com.beanexplorer.editors.

Package com.beanexplorer.beans

This package defines common BeanExplorer constants (BeanInfoConstants and IndexedPropertyConstants) and provides extensions of the standard java.beans classes:

• BeanInfoEx extends standard BeanInfo class to specify an explicit ordering of the properties and supply additional meta information about the bean.
• PropertyDescriptorEx extends standard PropertyDescriptor class to supply additional meta information about the property.
• IndexedPropertyDescriptorEx extends of standard IndexedPropertyDescriptor class to supply additional meta information about the indexed property.
• ChoicePropertyDescriptorEx - the utility class to simplify creation of the properties with predefined list of values.

There are also several helper classes for creation of dynamic beans which properties can be added or removed by application at runtime:

• DynamicProperty - describes individual property that can be dynamically added to the bean.
• DynamicPropertySet - an interface that defines a container for DynamicProperties which can be added or removed from the container at runtime.
• DynamicPropertySetSupport - default implementation of DynamicPropertySet interface.
• JDBCRecordAdapter -  abstract class to map JDBC result sets to dynamic DynamicPropertySet. When subclassing developer should define getResultSet() function which then will be used to fetch records from the database as well as a database metadata.

In additions the following classes can be used:

• DefaultValue an interface to provide default values for properties with null values.

Package com.beanexplorer.editors

This package provides extensions of java.beans.PropertyEditor and contains following classes:

• PropertyEditorEx - extends standard java.beans.PropertyEditor interface to provide editor with access to the bean which property is being edited. Property Inspector(s) may also supply to the editor implementing this interface additional arguments isSelected and hasFocus for finer integration  into JTable components.
• CustomEditorSupport - a support class to simplify creation of the property editors implementing PropertyEditorEx interface.
   
• TagEditorSupport - utility class  to present property value defined using an enumeration.
• StringTagEditorSupport - another utility class  to present property value defined an enumeration where values are Strings.

Java Introspection

Introspection is a runtime process used by builder environment or Property Inspector to figure out which properties and methods a JavaBean supports. This information or meta information presented as instance of class implementing BeanInfo interface.

By default a low level reflection mechanism is used to study the methods supported by a target bean and then apply simple design patterns to deduce from those methods what properties, events, and public methods are supported. However, bean implementer may provide explicit meta information for his bean supplying BeanInfo class describing the bean. This BeanInfo class will be used to programmatically discover behavior of the bean.

JavaBeans technology expect introspection information to be immutable and not to vary in normal use. Only if a bean is updated with a new improved set of class files, then the information may change.

JavaBeans API provides special java.beans.Introspector class allowing application builders and other tools to analyze beans. Introspector understands the various design patterns and standard interfaces and provides a uniform way of introspecting on different beans. The Introspector class walks over the class/superclass chain of the target class. At each level it checks if there is a matching BeanInfo class which provides explicit information about the bean, and if so uses that explicit information. Otherwise it uses the low level reflection APIs to study the target class and uses design patterns to analyze its behaviour and then proceeds to continue the introspection with its baseclass.

For example, if an implementer supplies class Foo and possibly FooBeanInfo class, then builder tool can use Introspector in following way to get BeanInfo describing Foo bean:

BeanInfo beanInfo = Introspector.getBeanInfo(Foo.class);

Here we need to highlight some important details, how the Introspector works. Ingenuously you can suppose, that if implementer supplies FooBeanInfo class, then beanInfo returned by Introspector will be instance of FooBeanInfo. No, it will be instance GenericBeanInfo. Indeed Introspector will instantiate FooBeanInfo and use it as "informant" for creating GenericBeanInfo, copying and validating all data from "informant".

Definition of additional meta information

At a first glance the introspection algorithm described above does not allows a developer to extend standard BeanInfo interface with methods to provide additional meta information. Indeed, if a developer provides additional methods in FooBeanInfo class, they will not be available at beanInfo returned by Introspector, since it will be an instance of GenericBeanInfo. Moreover, if FooBeanInfo will use classes that are extensions of BeanDescriptor or PropertyDescriptor with additional methods there, these methods will not be available, because GenericBeanInfo will contain instances of BeanDescriptor or PropertyDescriptor, rather than their extension.

Fortunately, we can put key-value pairs into the internal hashtable provided by FeartureDescriptor - a common ancestor for BeanDescriptor and PropertyDescriptor and this information will be copied from "informant". FeartureDescriptor declares three public methods to get access to the supplied values. 

Constants declaration

BeanInfoConstants interface declares all keys to get access for additional meta information provided by BeanHelpers technology. This constants are summarized in the table in the end of document.

Type safety

BeanHelpers technology provides type safe methods to associate correct type of meta information value with the specified key. This methods are declared in following classes:

• BeanInfoEx extends standard BeanInfo class to specify an explicit ordering of the properties and supply additional meta information about the bean.
• PropertyDescriptorEx extends standard PropertyDescriptor class to supply additional meta information about the property.
• IndexedPropertyDescriptorEx extends of standard IndexedPropertyDescriptor class to supply additional meta information about the indexed property.

Order of the properties

JavaBeans technology does not provide mechanism to order the properties of a bean. Trying to solve this problem builder tools allows to developer sort properties by its name or value class. BeanHelpers technology allows bean implementer to specifies explicitly the order for the properties. 

From the BeanHelpers' view point the order is still some additional meta information. This information is stored in BeanDescriptor internal hashtable as array of PropertyDescriptors with BeanInfoConstants.ORDER key.

Property Inspector or builder tool should use a following algorithm to get PropertyDescriptors describing properties provided by the bean:

    BeanInfo beanInfo = Introspetor.getBeanInfo(Foo.class);

    // try to get ordered PropertyDescriptors array
    // provided by BeanHelpers technology
    BeanDescriptor beanDescriptor = beanInfo.getBeanDescriptor();
    PropertyDescriptor[] properties = (PropertyDescriptor[])

beanDescriptor.getValue(BeanConstants.ORDER);

    // if properties order is not defined,
    // then standard approach is used
    if(properties == null)
        properties = beanInfo.getPropertyDescriptors();

BeanInfoEx provides a special add method allowing a bean implementer to specify the order while creating a BeanEinfo. The properties will be arranged by Property Inspector in the same order in which they were added. For example if Foo bean class has properties named a, b, c, then bean implementer can specify the order in the following way:

public class FooBeanInfo extends BeanInfoEx
{
    public FooBeanInfo()
    {
        super(Foo.class);

        add(new PropertyDescriptor("a", beanClass));
        add(new PropertyDescriptor("b", beanClass));
        add(new PropertyDescriptor("c", beanClass));
    }
}

When add method is invoked, BeanInfoEx instance puts the specified PropertyDescriptor into its internal vector. Later when BeanInfoEx used as "informant" it returns BeanDescriptor with ordered array of PropertyDescriptors from the vector.

BeanInfoEx provides several utility add methods with extra arguments (see the table above). For example, add(PropertyDescriptor pd, Class propertyEditor) method allows the developer to set up property editor class for the given property descriptor. The code of the method you can see below.

public void add(PropertyDescriptor pd, Class propertyEditor)
{
    pd.setPropertyEditor(propertyEditor);
    add(pd);
}

Semantic control of property values

Other meta data

Property Editor extension

BeanHelpers technology introduce PropertyEditorEx class that extends standard java.beans.PropertyEditor interface to provide editor with access to the bean which property is being edited. Property sets up the such editors using PropertyEditorEx.setBean method. Later property editor can get access to the bean using PropertyEditorEx.getBean method.

Property Inspector may also pass to a editor implementing this interface additional arguments isSelected and hasFocus to provide finer integration  into JTable components, using methods getCustomRenderer and getCustomEditor methods.

There is a support class CustomEditorSupport to simplify creation of the property editors implementing PropertyEditorEx interface.

Another extension (part of PropertyDescriptoEx) allows the developer to specify preferred size of the property when it is being displayed in some visual UI like PropertyInspector or DialogPropertyInspector, as well as specify format string for the property value. The tables below provides summary of such methods.

Composite editor

Composite Editor is a container editor allowing the developer to group several property editors into one panel. Composite Editor can be specified both as bean editor and property editor. Lesson 6 gives you a detailed example how composite editor can be used.

Modification of behavior of the properties at runtime

Possibility to control properties behavior by the bean or changing behavior of the properties at run time is one of the central in BeanHelpers technology.

According to JavaBeans technology BeanInfo is associated with class, not with particular instance of the class. Because class definition is immutable all class instances share the same BeanInfo instance and consequently have the same outlook in Property Inspector. Such approach is good enough for application builder tools. But in practice it is often necessary to have values of property attributes depending on some conditions. Here are some examples:

• property's display name should be controlled by the bean;
• property "a" should be read only if property "b" has some value;
• property "a" should be hidden if property "b" has some value.

To solve this task BeanHelpers introduce the concept of dynamic property attribute. We say that property attribute is dynamic when its value is controlled by some method of the bean, specified in PropertyDescriptor. PropertyInspector invokes the specified method of the bean to get  value of the property attribute. This allows a bean to control behavior of the property.

The table below summarizes methods of PropertyDescriptorEx that can be used to specify property attributes that values can be calculated dynamically by a bean. Lesson 4 gives an example how you can use dynamic property attribute in your application.

Hierarchy of the properties

Bean properties can form a hierarchy, represented in Property Inspector as a tree. In the example below BarChart bean has array property columns. Array items presented by composite properties that consists of 4 simple properties: label, value, color and visible. Thus in this example we have three level hierarchy:

• first level - properties of BarChart;
• second level - array items of columns property;
• third level - properties of array items.

BeanHelpers technology provides two extensions to address complications arising for such hierarchies. First extension provides fine control on array item properties. Second extensions concerns merging metadata from BeanDescriptor and PropertyDescriptor when some bean (child)  is used as property of other bean (parent).

Property types and their customization

Controlling array items

BeanHelpers extends JavaBeans technology to provide fine control on array items. The table below summarizes methods of PropertyDescriptorEx for dealing with array items.

By default display names of array elements are shown as [0], [1], [2] etc. Using setChildDisplayName method a bean can provide a method for calculating display names for the elements of the indexed property.

Other methods allow a bean to control insertion or deletion of array items*.

* This feature is not yet supported by standard Property Editors.

Merging

Any bean (child) can be used as a value of the property of another bean (parent). In such case we consider metadata from child BeanDescriptor as default, while parent PropertyDescriptor can redefine some child property attributes.

BeanExplorer merges information from PropertyDescriptor and BeanDescriptor when a property is created. Property attributes defined in BeanDescriptor are replaced by corresponding attributes from PropertyDescriptor if such attributes exist.

Summary Table