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
Advanced Binding Properties
Binding Data to Components
Special Binding Properties

Software and Files Needed for the Tutorial

For this tutorial you need to have the following software installed on your computer:

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:

    Image showing the Name & Location page of the New Java Application wizard 
                with the project information filled in.

  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:

    Image showing the Name & Location page of the New JFrame wizard 
                with the file information filled in.

  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.

    Image showing the form with both the slider and text field added to the form.

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.

    Image showing values to select in the Binding Source combo box.

  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.

Image showing the running application with the slider moved and the 
    text value changed.

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:

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:

Creating Entity Classes

To create entity classes to represent the database that is to be bound to the JTable:

  1. In the Projects window, right-click your project and choose New > Other, select the Persistence category, and select the Entity Classes from Database template.
  2. In the Database Tables page of the wizard, select the database connection.
  3. Once the Available Tables column is populated, select the tables that you want to use in your application and click Add to move them to the Selected Tables column. Click Next.

    Image showing the Database Tables page of the New Entity Classes From Database wizard 
            with the CUSTOMER and DISCOUNT_CODE tables selected.

  4. In the Entity Classes page of the wizard, make sure the Generate Named Query Annotations for Persistent Fields dialog box is selected.
  5. Make any customizations that you want to make to the names of the generated classes and their location.

    Image showing the Entity Classes page of the New Entity Classes From Database wizard.

  6. Click Create Persistence Unit.
  7. In the Create Persistence Unit dialog box, make sure of the following things:
    • That the selected Persistence Library is TopLink.
    • That the selected Table Generation Strategy is "None".
    • Image showing the Create Persistence Unit dialog box.

  8. Click Finish.

    You should see nodes for the entity classes in the Projects window.

Binding Components to the Beans That Represent the Data

To bind the data to a JTable component:

  1. Right-click the component in the GUI Builder and choose Bind > elements.
  2. Click Import Data to Form. From the Import Data to Form dialog box, select the database table to which you want to bind your components. Click OK.
  3. From the Binding Source combo box, select the item that represents the result list of the entity class. For example, if the entity class is called, Customer.java, the list object would be generated as customerList.
  4. Leave the Binding Expression value as null.
  5. If there are any database columns that you want to appear in the JTable, select those columns in the Selected list and move them to the Available list.
  6. Select the Advanced tab to further configure the binding. For example, you can specify a validator or converter, or you can specify behavior if the binding source is null or unreadable.
  7. Click OK.

To bind the data to a JList component:

  1. Right-click the component in the GUI Builder and choose Bind > elements.
  2. Click Import Data to Form. From the Import Data to Form dialog box, select the database table to which you want to bind your components. Click OK.
  3. From the Binding Source combo box, select the item that represents the result list of the entity class. For example, if the entity class is called, Customer.java, the list object would be generated as customerList.
  4. Leave the Binding Expression value as null.
  5. In the Display Expression drop-down list, select the property that represents the database column that contains the values that you want to display in the list.
  6. Select the Advanced tab to further configure the binding.
  7. Click OK.

Note: You can also use the New Java Desktop Application wizard to quickly create a whole working application that has CRUD (create, read, update, and delete) features. However, it is better to generate all the entity classes in advance to ensure that all relations among the entities are correctly covered by the generated classes.

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:

Component Property Description
AbstractButton selected The selected state of a button.
JComboBox selectedItem The selected item of a JComboBox.
JSlider value The value of a JSlider; notifies of all changes.
value_IGNORE_ADJUSTING Same as "value" but does not notify of change while the slider is adjusting its value.
JList selectedElement The selected element of a JList; notifies of all changes. If there is a JListBinding with the JList as the target, the selected element is reported as an element from the binding's source list. Otherwise, the selected element is reported as an object from the list's model. If nothing is selected, the property evaluates to null.
selectedElements A list containing the selected elements of a JList; notifies of all changes. If there is a JListBinding with the JList as the target, the selected elements are reported as elements from the binding's source list. Otherwise, the selected elements are reported as objects from the list's model. If nothing is selected, the property evaluates to an empty list.
selectedElement_IGNORE_ADJUSTING Same as "selectedElement" but does not notify of change while the list selection is being updated.
selectedElements_IGNORE_ADJUSTING Same as "selectedElements" but does not notify of change while the list selection is being updated.
JTable selectedElement The selected element of a JTable; notifies of all changes. If there is a JTableBinding with the JTable as the target, the selected element is reported as an element from the binding's source list. Otherwise, the selected element is reported as a map where the keys are composed of the string "column" plus the column index and the values are the model values for that column. Example: {column0=column0value, column1=column1value, ...} If nothing is selected, the property evaluates to null.
selectedElements A list containing the selected elements of a JTable; notifies of all changes. If there is a JTableBinding with the JTable as the target, the selected elements are reported as elements from the binding's source list. Otherwise, each selected element is reported as a map where the keys are composed of the string "column" plus the column index and the values are the model values for that column. Example: {column0=column0value, column1=column1value, ...} If nothing is selected, the property evaluates to an empty list.
selectedElement_IGNORE_ADJUSTING Same as "selectedElement" but does notify of change while the table selection is being updated.
selectedElements_IGNORE_ADJUSTING Same as "selectedElements" but does not notify of change while the table selection is being updated.
JTextComponent (including its sub-classes JTextField, JTextArea, and JEditorPane) text The text property of a JTextComponent; notifies of all changes (including typing).
text_ON_FOCUS_LOST The text property of a JTextComponent; notifies of change only when focus is lost on the component.
text_ON_ACTION_OR_FOCUS_LOST The text property of a JTextComponent; notifies of change only when the component notifies of actionPerformed or when focus is lost on the component.
Send Us Your Feedback

See Also

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

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.