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. 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 in the Database Application Developer's Guide for a tutorial using sample InterBase files to create a master-detail relationship.

To display this property editor, choose the masterLink property in the Inspector when a DataSet property is selected in the Component Tree.

Master Dataset

Displays the names of all instantiated DataSet objects to which this DataSet can be linked.

Master Link Columns

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

Removes the selected entry from the Master Link Column list box.

Detail Link Columns

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

Removes the selected entry from the Detail Link Column list box.

Available Master Columns

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

Adds a column selected in the Available Master Columns list box to the Master Link Columns list box.

Available Detail Columns

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

Adds 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

Specifies whether to fetch all detail records in one fetch, or fetch details for each 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.

When this option is unchecked for the detail DataSet, 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. This is stored as a false value in the fetchAsNeeded property of the MasterLinkDescriptor.

When this option is selected for the detail DataSet, 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. This is stored as a fetchAsNeeded(true).

Select this option if your remote database table is very large, as this improves 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 more current, but will 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 this option is selected (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 and this option is selected, 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 the Parameterized queries in master-detail relationships topic in the Database Application Developer's Guide.

For more information on the fetchAsNeeded property, see the Fetching details topic in the Database Application Developer's Guide.

This option does not apply to TableDataSets since all data is fetched at once for this component.

Allow cascading updates

Select this option to allow updates made to linking columns in the master DataSet to cascade to linked detail DataSets. In the case of multiple levels of links (for example, one DataSet is linked to a detail DataSet which is the master to another DataSet), this option must be set at each level for the cascade results to be as expected.

Allow cascading deletes

Select this option to allow deletes made to a master DataSet to cascade to linked detail DataSets. In the case of multiple levels of links (for example, one DataSet is linked to a detail DataSet which is the master to another DataSet), this option must be set at each level for the cascading delete results to be as expected.

Test Link

Ensures 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.