MasterLink property editor

In JBuilder, you can join, or link, two data sets that have at least one common field with a MasterLinkDescriptor. A master-detail relationship is usually a one-to-many type relationship among data sets. The properties are stored in the MasterLinkDescriptor object. This custom property editor is used to specify properties of the MasterLinkDescriptor for linking a detail DataSet to a master DataSet based on at least one common column of data. This dialog also provides an option for testing the master-detail link.

The master DataSet and the detail DataSet do not have to be of the same DataSet type, for example the master DataSet could be a QueryDataSet and the detail DataSet could be a TableDataSet. You can link one master data set to several detail data sets, linking on the same field or on different fields. You can also create a master-detail relationship that cascades to a one-to-many-to-many type relationship or you can link a data set to itself. Many-to-one or one-to-one relationships can be handled within a master-detail context, but these kinds of relationships would be better handled through the use of lookup fields, in order to view all of the data as part of one data set.

The columns that establish the link between the detail DataSet and the master DataSet must be of the same data type.

See Establishing a master-detail relationship for a tutorial using sample InterBase files to create a master-detail relationship.

Dialog box options

Master Dataset

This drop-down list displays the names of all instantiated DataSet objects to which this DataSet can be linked.

Master Link Columns

This list box displays the selected Columns in the master DataSet used to establish the master-detail relationship. There are no index requirements on the selected master Columns. Columns are added to this list box by selecting a column name from the Available Master Columns list box and clicking the Add to Master Links button.

Remove Column

Click this button to remove a selected entry from the Master Link Column list box.

Detail Link Columns

This list box displays the Columns in the detail DataSet used to establish the master-detail relationship. There are no index requirements on the selected detail Columns. Columns are added to this list box by selecting a column name from the Available Detail Columns list box and clicking the Add to Detail Links button.

Remove Column

Click this button to remove a selected entry from the Detail Link Column list box.

Available Master Columns

This list box contains the list of Columns in the master DataSet that can be used to establish the master-detail link. Select a column that you want to use to establish the master-detail relationship, and then click the Add to Master Links button to add the column to the Master Link Columns list box.

Add To Master Links

Click this button to add a column selected in the Available Master Columns list box to the Master Link Columns list box.

Available Detail Columns

This list box displays the list of Columns in the detail DataSet that can be used to establish the master-detail link. Select a column that you want to use to establish the master-detail relationship, and then click the Add to Detail Links button to add the column to the Detail Link Columns list box.

Add To Detail Links

Click this button to add a column selected in the Available Detail Columns list box to the Master Detail Columns list box. If the corresponding column in the Master Link Columns box is of a different data type or if there is no corresponding column in the Master Link Columns box, the selected column is not added to the Detail Link Columns list.

Delay fetch of detail records until needed

Check this box to fetch detail records for a master record when that master record is visited. Leave this box unchecked to fetched all of the detail records at once. Detail records are filtered from the detail dataset and viewed in a corresponding visual control as the master is visited.

Fetching all detail records at once

When the fetchAsNeeded property is false (or Delay fetch of detail records until needed is unchecked in the MasterLinkDescriptor dialog box), all of the detail data is fetched at once. Use this setting when your detail data set is fairly small. You are viewing a snapshot of your data when you use this setting, which will give you the most consistent view of your data.

Fetching detail records when the master record is visited

When the fetchAsNeeded parameter is true (or Delay fetch of detail records until needed is checked in the MasterLinkDescriptor dialog box), the detail records are fetched on demand and stored in the detail data set. This type of master-detail relationship is really a parameterized query where the values in the master fields determine which detail records will display. You are most likely to use this option if your remote database table is very large, in order to improve performance (not all of the data set will reside in memory - it will be loaded as needed). You would also use this option if you are not interested in most of the detail data. The data that you view will be fresher and more current, but not be as consistent a snapshot of your data as when the fetchAsNeeded parameter is false. You will fetch one set of detail records at one point in time, it will be cached in memory, then you will fetch another set of detail records and it will be cached in memory. In the meantime, the first set of detail records may have changed in the remote database table, but you will not see the change until you resolve or cancel all changes and re-fetch the details.

When the fetchAsNeeded property is true, there should be a WHERE clause that defines the relationship of the detail columns in the current QueryDataSet to a parameter that represents the value of a column in the master data set. If the parameterized query has named parameter markers, the name must match a name in the master data set. If "?" JDBC parameter markers are used, the detail link columns are bound to the parameter markers from left to right as defined in the masterLink property. The binding of the parameter values is implicit when the master navigates to a row for the first time. The query will be re-executed to fetch each new detail group. If there is no WHERE clause, JBuilder throws DataSetException.NO_WHERE_CLAUSE. When fetching is handled this way, if no explicit transactions are active, the detail groups will be fetched in separate transactions. For more information on master-detail relationships within parameterized queries, see Parameterized queries in master-detail relationships. For more information on the fetchAsNeeded property, see Fetching details.

Fetching details in a TableDataSet

When the detail data set is a TableDataSet, the fetchAsNeeded parameter is ignored and all data is fetched at once.

Test link

Click this button to ensure the link between the detail DataSet and the master DataSet is valid with the properties specified in this dialog box. If the link is valid, the message in the area immediately below this button indicates "Success". If the link is not valid, the message in the area immediately below this button indicates "Failed". If errors are encountered, an error dialog containing detailed error information displays.