This section describes the first steps to take in order to use the JBeans package. But before we get to that, there are a few definitions that you must know. These definitions are used through out this document.

Java bean

A Java class that contains standard Java bean accessor methods for properties. These accessor methods have the form getX, setX and isX where X is the property's name. The isX method is only used for boolean values and can be replaced with getX.

Java bean property (property)

A value that is changed and retrieved using standard accessor methods. These accessor methods have the form getX, setX and isX where X is the property's name. The isX method is only used for retrieving boolean values and can be substituted with getX.

Java bean property name

The name of a Java bean property and NOT the name of the method used to access that property. The Java bean standard specifies how these names are constructed from the method names. If a Java class X has a method named getFoo(), then the property name would be foo. If the class has a method named getFooBar() (notice the mixed case), the property name would be fooBar. If the class has a method named getFOO(), the property name would be FOO. This naming convention holds true for set and is methods in addition to the get methods.

Child Java bean

A Java bean that is changed and retrieved via a Java bean property of another Java bean. That is, if Java bean X has a property named foo that is accessed using the method getFoo and getFoo returns the type Y (ie public Y getFoo() {...}), where Y is another JavaBean, then Y is considered a child Java bean of X.

Local property

A local property is a property of a Java bean and NOT a property of a child Java bean. That is, if Java bean X has a property named foo, then foo is a local property of X (ie public String getFoo() {...}). Another way to look at it is, a local property is a property contained within a single Java class. So, if there exists a class X, then all the properties defined in X.java are local properties of X.

Nested property

A nested property is a property of a child Java bean and NOT a local property. That is, if Java bean X has a property name foo of type Y and Java bean Y has a property name bar of type String, the the property foo.bar is a nested property of X and a local property of Y. (ie getFoo().getBar()).

Leaf property

A leaf property is a property inside a nesting that is the last property of the nesting. That is, if Java bean X has a property name foo of type Y and Java bean Y has a property name bar of type String, the the property bar is a leaf property and the property foo is a non-leaf property of the nesting.

Indexed property

A indexed property is a property of a Java bean that uses indices to access values stored in an array, Collection or other data structure. (ie public String getFoo(int index) {...; return array[index];}).

Events/listeners

Events and event listeners are the terminology used by the Java community to describe the Observer pattern (GOF). This pattern consists of listeners which implement a common interface. The methods of the interface are called when events occur and usually have standard parameters that describe th event. These are very common throughout the Java APIs such as the AWT and Swing packages.

Auto-generation

Auto-generation is a concept created for the JBeans package. This means when a property of a Java bean is null and should be created automatically by the JBeans package. This occurs only with nested properties when a non-leaf property is null. Normally during the course of accessing a nested Java bean property, it is necessary to check for null values, otherwise NullPointerExceptions will be thrown. For example, if this code were executed: user.getAddress(0).getType().setTypeCode(42) and getAddress(0) returned null, a NullPointerException would be thrown. In order to prevent this, we could check the property for null and then create a new instance of the property and set it:

    if (user.getAddress(0) == null) {
        user.setAddress(0, new Address());
    }
    

When this type of code happens automatically by the JBeans package, it is called auto-generation. Auto-generation only occurs when setting property values using one of the setPropertyValue methods.

Auto-conversion

Auto-conversion is another concept created for the JBeans package. This means when a property of a Java bean takes a particular type, java.lang.Integer for example and you are trying to set that property using a java.lang.String. The String will obviously need conversion or an exception will be thrown telling you that you are using the wrong type for the property. We could add code that converted the property like this:

    try {
        Integer intValue = Integer.valueOf(myString);
        ...
    } catch (NumberFormatException nfe) {
        ...
    }
    

When this type of conversion happens automatically in the JBeans package, it is called auto- conversion. Auto-conversion only occurs when setting property values using one of the setPropertyValue methods.

Now that we have those out of the way, let's get to the code! First off, JBeans has four main classes that are used to access Java beans. These are org.jbeans.BeanProperty, org.jbeans.IndexedBeanProperty, org.jbeans.NestedBeanProperty and org.jbeans.JavaBean. These classes make use of many other classes for doing conversions and events, but those are more advanced topics not covered until later. In the next four sections we will cover these four classes and how to use them to access Java beans. Each section builds on the last section, so it is recommended that you read them in order.