Binding Beans and Data in a Desktop Application

This guide is an introduction to the support in NetBeans IDE 6.0 for beans binding and data binding in Java desktop applications.

Contents

• Introduction: Beans Binding in NetBeans IDE 6.0
• Binding Properties to Other Properties
• Binding Custom Beans
• Advanced Binding Properties
• Binding Data to Components
• Special Binding Properties

To follow this tutorial, you need the following software and resources.

Introduction: Beans Binding in NetBeans IDE 6.0

Until the release of the beans binding library, it was somewhat cumbersome to connect UI components to databases or to keep values of component properties in sync. For example, displaying data from a standard database in a JTable required the manual creation of utility classes to handle the connection between the database and the JTable. And keeping values of different bean properties in sync (such as the value of a JTextField with the rendering of a visual bean) required hand-coding of listeners and event handlers.

The beans binding library simplifies and standardizes all of this. You can merely write a few lines of code to establish which properties of which components need to be kept in sync, and the beans binding library handles the rest. In the NetBeans IDE, beans binding features are integrated in the GUI Builder, so you can quickly get the behavior of your application coded soon after you have established the visual design.

This guide is an overview of the main aspects of beans binding in the IDE. For a concrete example of many of these features, you can try the Building a Java Desktop Database Application tutorial.

Binding Properties to Other Properties

At its most basic, beans binding is a way to connect bean properties without using event listening and handling code.

To illustrate the concept of beans binding and how the IDE supports it, we will do a simple example where a user can adjust a slider to change a numerical value in a text field.

To set up the example:

1. In the IDE, choose, File > New Project.
2. Select the Java category and select the Java Application template. Click Next.
3. In the Name and Location page of the wizard, perform the following operations:
   • Type NumberSlider as the project name.
   • Leave the Use Dedicated Folder for Storing Libraries checkbox unselected. (If you are using NetBeans IDE 6.0, this option is not available.)
   • Leave the Set As Main Project checkbox selected.
   • Clear the Create Main Class checkbox.
   
4. Click Finish to exit the wizard and set up the project.
5. In the Projects window, right-click the NumberSlider project node and choose New > JFrame Form.

   (If JFrame Form is not available in the New menu, choose Other. Then in the New File wizard, select the Swing GUI Forms category and select the JFrame Form template.)

6. In the Name and Location page of the wizard, perform the following operations:
   • Type NumberSliderFrame for the class name.
   • Type numberslider for the package name.
   
7. Click Finish to exit the wizard and create the form.

   NumberSliderForm.java should open in design mode in the editing area.

8. From the Swing Controls section of the Palette, drag a slider component into the design area. (If the Palette window is not open, choose Window > Palette.)
9. From the Palette, drag a text field component to the design area.

   The resulting form might look something like the screenshot below. However, positioning is not important for purposes of this example.

   

Source and Target

Now that we have set up the example, we are ready to create the binding. However, first we need to determine which component will be the source of the binding and which will be the target. The binding source component is where a value for the property first originates.

When binding in the GUI Editor, you initiate a binding on the target and then you declare the source in the Bind dialog box.

In this case, since the JSlider comes with a default range of values, we will use it as the source.

Note: Bindings can be two-way (read/write), so that changes in the target are automatically reflected in the source. However, the direction of the initial binding is always from the source to the target. See the information on Update Mode in the Advanced Binding Configuration section.

To bind the slider to the text field:

1. Right-click the text field component and choose Bind > text to open the Bind dialog box.
2. From the Binding Source combo box, select jSlider1.
3. From the Binding Expression combo box, select value int as shown in the image below.
4. Click OK.

You have just bound the value bean property of the slider to the text value of the text field.

In the design area, the text field should show the value 50. This value reflects the fact that the slider is in the middle position and the default range of values for the slider is from 0 to 100.

You can now run the application and see the binding in action.

To run the project:

1. Choose Run > Run Main Project.
2. In the Run Project dialog box, click OK to accept numberslider.NumberSliderForm as the main class.

The applications should start in a separate window. Adjust the slider in the running application and watch the value change in the text field.

Binding Custom Beans

If you have a bean that you have written yourself, you have to perform a few steps before the IDE's binding features are available for that bean. You can take either of the following approaches:

• Add the bean to the Palette so that you can add it to a form just as you would use add a standard Swing component.
• Add the bean class to your project and compile the bean.

To add a bean to the Palette window:

1. Make sure that the bean is compiled.
2. Choose Tools > Palette Manager.
3. If you want to create a new palette category for the bean, click New Category and enter the desired name before you add the bean.
4. Click Add from JAR, Add from Library, or Add from Project and complete the wizard to add the bean.

To add a bean from your project:

1. In the Project's window, right-click the node for the bean and choose Compile File.
2. Drag the bean to the form.

   You should then see the bean in the Inspector window. You can then invoke the Bind dialog for any of the bean's properties.

Advanced Binding Configuration

The example above shows a straightforward binding with some default behaviors. But sometimes you might want or need to configure your binding differently. If that is the case, you can use the Advanced tab of the Binding dialog box.

The Advanced tab of the dialog box contains the following fields:

• Name. Enables you to create a name for the binding, which gives you more flexibility for managing your bindings. The name is added to the constructor of the binding and can be referenced with the binding's getName() method.
• Update Mode. Specifies the way that the properties are kept synchronized. The possible values are:
  • Always sync (read/write). Whenever a change is made to either the source or the target, the other is updated.
  • Only read from source (read only). The target is only updated the first time the source value is set. Changes that are made to the source are updated in the target. Changes made to the target are not updated in the source.
  • Read from source once (read once). The target is only updated when the target and source are initially bound.
• Update Source When (available only to the text property of JTextField and JTextArea components). Enables you to select the frequency with which the properties are synchronized.
• Ignore Adjusting (available to the value property of JSlider; to the selectedElement property of JTable and JList; and to the selectedElements property of JTable and JList). If this checkbox is selected, any changes made to one property are not propagated to the other property until the user is finished making the change. For example, when the application's user drags a slider, the value of the property to which the slider's value property is bound is only updated once the user releases the mouse button.
• Converter. If your binding involves properties with different data types, you can specify code that converts values between the types. The beans binding library handles many commonly needed conversions, but you might need to provide your own converters for other combinations of property types. Such converters need to extend the org.jdesktop.beansbinding.Converter class.

  The Converter drop-down list is populated with any converters that have been added as beans to your form. You can also add the conversion code directly by clicking the ellipsis (...) button, and selecting Custom Code from the Select Converter Property Using drop-down list.

• Validator. Enables you to specify code to validate a change in the target property value before propagating that change back to the source property. For example, you can use a validator to make sure that an integer property value is within a specific range.

  Validators need to extend the org.jdesktop.beansbinding.Validator class.

  The Validator drop-down list is populated with any validators that have been added as beans to your form. You can also add the validation code directly by clicking the ellipsis (...) button, and selecting Custom Code from the Select Validator Property Using drop-down list.

• Null Source Value. Enables you to specify a different value to use if the source property has a null value when the binding is attempted. This field corresponds with the setSourceNullValue() method of the org.jdesktop.beansbinding.Binding class.
• Unreadable Source Value. Enables you to specify a different value to use if the binding expression cannot be resolved when the binding is attempted. This field corresponds with the setSourceUnreadableValue() method of the org.jdesktop.beansbinding.Binding class.

Note: To better understand the classes and methods mentioned above, you can access the beans binding Javadoc documentation directly from the IDE. Choose Help > Javadoc References > Beans Binding. In the browser window that opens, click the org.jdesktop.beansbinding link to access documentation for those classes.

Binding Data to Components

Once you have created a new Java form and added components to the form, you can generate code to bind those components to data. The IDE makes it easy to bind data to Swing JTable, JList, and JComboBox components.

Before binding a component to data from a database, you need to have done the following things:

• Connected to a database in the IDE.
• Added the component to a form in the GUI Builder.
• Created classes that represent the database tables to which you want to bind. Steps on creating the entity classes for binding data to a component are given below.

jComboBox1.setRenderer(new DefaultListCellRenderer() {
           @Override
           public Component getListCellRendererComponent(
                   JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) {
               super.getListCellRendererComponent(list, value, index, isSelected, cellHasFocus);
               if (value instanceof MyEntityClass) {
                   MyEntityClass mec = (MyEntityClass)value;
                   setText(mec.getPropertyFromMyEntityClass());
               }
               return this;
           }
         })

Special Binding Properties

Where necessary, the beans binding library provides special synthetic properties for some Swing components that are missing from the components themselves. These properties represent things, such as a table's selected row, that are useful to bind to other properties.

Below is a list of the synthetic properties added by the beans binding libraries:

See Also

For a more general introduction to using the IDE's GUI Builder, see Introduction to GUI Building.

To see how you can use the Java Desktop Application project template to build a database application with a Master/Detail view, see Building a Java Desktop Database Application.

For more information on Beans Binding, see the Beans Binding project page on java.net.

For general information on JavaBeans components, see the Beans trail of the Java Tutorial.

For general tips and tricks on using the GUI Builder in NetBeans IDE, see the GUI Editor FAQ and Patrick Keegan's web log.