8

DataSource's Data Bound Components

Introduction  The Types of Data Bound Components

The Navigator and its Functions  Data Binding the Other Components

---

8.1 Introduction

JClass DataSource and JClass HiGrid work as a team to provide a flexible data binding solution for those applications that need to present hierarchically organized data in an integrated package. JClass DataSource by itself is able provide your application with a number of SWING-like components grouped on a form and bound to a hierarchical source of data. It contains a versatile set of components that can be bound to any source of data that JClass DataSource can access, and it provides the navigation tool for choosing any of the records in the data set to which it is bound. The same data binding mechanism is available for use in JClass Chart, JClass Field, and JClass LiveTable as long as all products have matching version numbers.

---

8.2 The Types of Data Bound Components

JClass DataSource contains SWING-type components. If you are using the JClass DesktopViews product suite, you are able to bind JClass Chart, JClass Field, and JClass LiveTable objects in addition to the set of components included in JClass DataSource.

The "standard" components and their associated data bound component names are given in the table.

Swing		Types
JCheckBox	DSdbJCheckBox	String, Numeric
	DSdbJImage	java.awt.Image
JLabel	DSdbJLabel	String, Numeric
JList	DSdbJList	String, Numeric
	DSdbJNavigator	void
JTextArea	DSdbJTextArea	String, Numeric
JTextField	DSdbJTextField	String, Numeric

Editable components are: DSdbJTextField, DSdbJTextArea, DSdbJCheckBox. The non-editable components are DSdbJLabel, DSdbJList, DSdbJImage, and DSdbNavigator.

The Navigator is derived from either SWING Panel classes, and it is included in the table because it functions much the same way as the other components.

JClass DataSource's API makes it possible for you to bind SWING, or even components of your own making, to a data source. The next sections illustrate how this is done.

Binding a Component to a Meta Data-Level

Each component Bean has a setDataBinding property to simplify the task of specifying the data connection. This method is called automatically by the component's property editor in an IDE environment. The next section discusses the programmatic method.

Binding the Component Programmatically

Programmatically, data binding is accomplished by calling the setDataBinding constructor in one of two ways. The "standard" method is to provide handles to the DataModel and the MetaDataModel themselves. A second way of representing the MetaDataModel is by a "path" of MetaDataModel descriptions separated by "|" (for example, Orders|Customers).

Binding the navigator component to a data source requires only references to a DataModel and a MetaDataModel. For example:

DSdbNavigator nav = new DSdbNavigator();
nav.setDataBinding(dataModel, metaDataModel);

To bind a component that displays a single database field, such as a text field, requires a column name as a third parameter in the call to the setDataBinding method:

DSdbTextField dbCustomerID = new DSdbTextField();
dbCustomerID.setDataBinding( dataModel, metaDataModel, "CustomerID");

Binding the Component through an IDE

There are more choices when you effect data binding using an IDE. The recommended way is to use JClass DataSource's JCData or JCTreeData and JDBC to specify the connection to the data source. Alternatively, you provide the instance of the DataModel and path, just as in the case of programmatic data binding. Finally, you can provide a single String containing the name of the DataModel, separated by a colon, from the path to the chosen MetaDataModel. For example:

setDataBinding("DataModel0:Orders|OrderDetails").

Using the JClass DataSource Data Bound Components

The data bound components have been made especially easy to use in an IDE by providing a customizer that communicates with any JCData or JCTreeData that has already been created and connected to a source of data. Use this customizer to select the DataModel and MetaDataLevel. Once these have been selected, a list of column names is presented. Once a name has been selected, the data bound component is ready for use.

If you decide to use the programmatic API, the data bound component's constructor takes three parameters whether it binds to the entire column, in the case of DSdbList, or to a single cell for all the rest. Taking DSdbTextField as an example, its constructor is:

public DSdbTextField(DataModel dataModel,
  MetaDataModel metaDataModel,
  String column_name)

There is also a parameterless constructor that requires data binding to be set using setDataBinding, which takes the same three parameters. Use this form of the constructor when you need to instantiate the component first and set the data binding later.

---

8.3 The Navigator and its Functions

8.3.1 Introduction

DSdbNavigator is a visual component that fires events to JClass DataSource, requesting a move to another row in the table to which it is bound. In addition to buttons for movement to the first, last, next, and previous rows, it is able to request the insertion of a new row or the deletion of the row to which it is currently pointing.

It is bound to a data source by giving its constructor references to the DataModel and a particular MetaDataModel in the hierarchy. Thus, it can be bound to any level in the master-detail structure.

Swing Support

Since data bound components have been defined in JClass DataSource for SWING, a navigator exists for this environment. The Swing navigator is based on JComponent and is called DSdbJNavigator.

The navigators are in the same packages as the other JClass DataSource data bound components. The Swing navigator is called com.klg.jclass.datasource.swing.DSdbJNavigator.

8.3.2 The Navigator Binds to any MetaData Level

The navigator binds to any MetaData level, just like the other DataSource data bound components. It uses com.klg.jclass.datasource.TreeData to bind to a particular node in the hierarchical data source. The property is called DataBinding, just like all the other data bound components in JClass Chart, JClass Field, JClass LiveTable, and JClass DataSource.

A DSdbNavigator constructor is parameterless; therefore, the newly instantiated component is not initially bound to a data source. Binding occurs in various ways, depending on whether the IDE or programmatic approach is taken.

Binding the Navigator Programmatically

Programmatically, data binding is accomplished by calling the setDataBinding constructor in one of two ways. The "standard" method is to provide handles to the DataModel and the MetaDataModel themselves. A second way of representing the MetaDataModel is by a "path" of MetaDataModel descriptions separated by "|" (for example, Orders|Customers).

Binding the Navigator through an IDE

There are more choices when you effect data binding using an IDE. The recommended way is to use JClass DataSource's JCData or JCTreeData and JDBC to specify the connection to the data source. Alternatively, you provide the instance of the DataModel and path, just as in the case of programmatic data binding. Finally, you can provide a single String containing the name of the DataModel, separated by a colon (:), from the path to the chosen MetaDataModel. An example is setDataBinding("DataModel0:Orders|OrderDetails").

8.3.3 DSdbNavigator's Functions

The JClass DSdbNavigator component displays the current row of the data table to which it is bound. Four of its buttons, First, Previous, Next, and Last, signal the data source to adjust its current row pointer. The Insert button requests the insertion of a new row and the Delete button requests the deletion of the current row from the data source. The Command button pops up a sub-menu of additional choices. The layout of the navigator's buttons is shown below:

Figure 77 :  The DSdbNavigator component.

The central Status field displays the description for the meta data level, the current record number, and the total number of records in the data table to which it is bound. The navigator's buttons are described below, beginning at the right and preceding in order to the left:

Command	Description
First	Moves to the first row in the current DataTable.
Previous	Moves to the previous row in the current DataTable. If already at the start, no move occurs.
Delete	Deletes the current record.
Command	Pops up a menu of commands that can be executed. The menu is similar to the one in JClass HiGrid that pops up by right-clicking on one of the grid's rows.
Status	Displays the name given to the meta data level to which it is bound, the Data Table record number, and total number of records in that Data Table.
Next	Moves to the next row in the current DataTable. If already at the end, no move occurs
Last	Moves to the last row in the current DataTable
Insert	Adds a new record in the current table at the end of the table.

The Swing version of the navigator uses tool tips to show what each of the buttons does. The tool tip's text is derived from the text in the table above.

The Command menu pops up a sub-menu that allows operations on a table similar to those allowed by HiGrid. A list of Command menu commands is shown after the figure that illustrates it:

Figure 78 :  DSdbNavigator, showing the Command menu.

Command	Description
Insert Record	Adds a new record in the current table. Same as the add button in the navigator.
Delete Record	Removes the current record in the current table.
Cancel Record	Cancels the current edit.
Cancel All	Cancels all edits made.
Requery Record and Details	Requeries the table from the database.
Requery All	Updates the current row in the database.
Save Record	Saves changes made to the current record.
Save All	Updates all changes made.
Go To	Pops up a dialog that allows specification of a new row number.

8.3.4 Exploring DSdbNavigator's Bean Properties

Binding a navigator to a data source in an IDE is accomplished through the use of its data binding editor. The editor is aware of the data sources that you have pre-configured, so it's important to add a JCData or a JCTreeData to your form before you use the navigator's data binding editor.

Here are the steps to bind a navigator to a data source:

1. Place a JCData or a JCTreeData on your form.
2. Use the Data Bean's customizer to specify the connection to the database.
3. Place a DSdbNavigator (or a DSdbJNavigator) on your form. Its display area (called the status area) indicates that it is not bound to a data source.

   
   
   

4. Click Select a Data Source to launch its data binding editor.
5. A diagram of the meta data structure appears. If necessary, expand the diagram to show all the nodes. Click on a node to select it. Press Done to bind the navigator to the chosen level.
6. Check that the navigator confirms that it is bound to a data source by reporting the meta data level to which it is bound in its display area.

   
   
   

When a DSdbNavigator is placed in the BeanBox or an IDE, you'll see the properties listed in Figure 79.

Figure 79 :  The properties of DSdbNavigator.

Each region has the following properties:

Property	Description
Visible	Determines whether the region is shown.
Foreground	Foreground color.
Background	Background color.

Note that all of the buttons must have the same color, but the color of the status area can be set independently of the button color. Set the background and foreground colors for the buttons using setButtonBackground and setButtonForeground. The color is applied to all the buttons as a group. Set the colors for the status area using setStatusBackground and setStatusForeground.

Each button has its own get and set methods for reading and controlling its visibility. For example, use setCommandVisible(false) to hide the Command button.

The property names for controlling visibility are based on the region names as shown below:

Button or Status Area	Visible Get/Set Method
First	FirstVisible
Previous	PreviousVisible
Delete	DeleteVisible
Status	StatusVisible
Command	CommandVisible
Next	NextVisible
Last	LastVisible
Insert	InsertVisible

The following figure shows the data binding editor window which appears as a result of clicking on Select a Data Source... in the properties list.

It shows an example of an expanded view of the data model that was created to accompany the steps in the data binding procedure given above. The navigator was bound to the Order Details level by clicking on its name, then clicking Done.

Figure 80 :  DSdbNavigator's data binding editor.

---

8.4 Data Binding the Other Components

A component that binds to a single database field requires a column name in addition to the data model and meta data level. In an IDE, the binding is done following the same steps as is the case for DSdbNavigator. The next figure shows a cutout of a DSdbTextField, its exposed properties, and its ColumnDataBindingEditor.

The text field is bound to a column called Territory Name, which is part of the meta data level called Territories. All the database field names (that is, the column names) appear in the editor. The name appears highlighted after it has been chosen with a mouse click.

Figure 81 :  A DSdbTextField, its Properties, and its ColumnDataBindingEditor.