MasterLink property editor

This is a feature of JBuilder Professional and Enterprise.

To display this property editor, choose the masterLink property in the Inspector when a detail DataSet is selected in the structure pane.

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

Master Dataset

Displays the names of all instantiated DataSet objects to which this DataSet can be linked. Select the master data set from the list to activate the rest of the dialog.

Master Link Columns

Displays the selected Columns in the master DataSet being 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 to remove the selected entry from the Master Link Column list box.

Detail Link Columns

Displays the Columns in the detail DataSet being 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 to remove the selected entry from the Detail Link Column list box.

Available Master Columns

Displays the 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 to add a column selected in the Available Master Columns list box to the Master Link Columns list box.

Available Detail Columns

Displays the 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 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

Uncheck this option to enable immediate fetching, where a single query is used to fetch the entire detail set in one batch. After the initial execution of the query and fetching of the results, the two DataSets are linked based on the cached data, using settings stored in the MasterLinkDescriptor.

Check this option to enable delayed fetching, a less consistent view of the data. Each time a master row is visited for the first time, its detail data is fetched by re-executing the detail query. The detail query must contain a WHERE clause with links to the master DataSet using named parameters. The detail DataSet's loadRow() method is invoked each time a master row is first encountered. This method extracts the link columns data values from the master (as specified in the MasterLinkDescriptor) and binds them to the query. Then the query executes and the results of that query added to any already cached rows in the detail DataSet. There must be a one-to-one match of the master DataSet column names to the named parameters in the WHERE clause of the detail QueryDataSet.

For more information on master-detail relationships within parameterized queries, see the Parameterized queries in master-detail relationships topic in Database Application Developer's Guide.

For more information on the fetchAsNeeded property, see the Fetching details topic in 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

Check this option to allow updates to linking columns in the master DataSet to be applied to rows in detail DataSets. If checked, updates are cascaded to details. If unchecked, updates to linking columns are not allowed if the master has details. Doing so could leave details orphaned.

Checking this option should be done with care, especially in cases where you have multiple master-detail relationships chained, for example where a detail DataSet is a master to another detail (and so on). Typically in that case, you want the updates to be reflected through the chain of related DataSets. For this to be possible, you must set the cascadeUpdates and cascadeDeletes properties at each level. Otherwise, the cascading stops at the DataSet whose cascade property is false, or unchecked. Partial updates or deletions (orphan records) can also occur in cases where a DataSet somewhere in the master-detail chain is not updateable. Program logic may also cause this property to effect only partial updates. For instance, an event handler for the editListener's deleting event might allow deletion of some detail rows and block deletion of others. In the case of cascaded updates, you may end up with orphan details if some rows in a detail set can be updated and others can't.

Allow Cascading Deletes

Check this option to enable matching detail (DataSet) rows to be deleted when the corresponding row in the master DataSet is deleted. If checked (or true), deletes are also applied to matching details. If unchecked (or false), master rows that have details cannot be deleted.

This property should be used with care, especially in cases where you have multiple master-detail relationships chained, for example, where a detail DataSet is a master to another detail (and so on). Typically in that case, you want the deletes to be reflected through the chain of related DataSets. For this to be possible, you must set the cascadeUpdates and cascadeDeletes properties at each level. Otherwise, the cascading stops at the DataSet whose cascade property is false, or unchecked. Partial updates or deletions (orphan records) can also occur in cases where a DataSet somewhere in the master-detail chain is not updateable. Program logic may also cause this property to effect only partial updates. For instance, an event handler for the editListener's deleting event might allow deletion of some detail rows and block deletion of others.

Test Link

Click to verify that 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.