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