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.
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.
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.
Click to remove the selected entry from the Master Link Column list box.
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.
Click to remove the selected entry from the Detail Link Column list box.
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.
Click to add a column selected in the Available Master Columns list box to the Master Link Columns list box.
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.
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.
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.
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.
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.
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.