borland Packages Class Hierarchy dx.dataset Package
java.lang.Object +----com.borland.dx.dataset.MasterLinkDescriptor
Constructors Properties Methods
Implements Serializable
The MasterLinkDescriptor object stores properties that set a master-detail relationship between two DataSet objects such as QueryDataSet, ProcedureDataSet, TableDataSet or DataSetView. You can link different DataSet objects together, for example, a QueryDataSet and a TableDataSet as long as there is common data to base the link relationship on. JDataStore creates indexes for the linking relationship as needed, quickly and efficiently.
There are two methods of using a StorageDataSet to provide the detail rows in a master-detail relationship:
When specifying the query statement for the detail DataSet, you should specify the linking columns in a where clause if fetchAsNeeded is true. If the fetchAsNeeded setting is not compatible with the detail query, you will get a DataSetException and anomalous results.
For example, to bind parameters in the correct order where
The correct query statement for the detail query is:
SELECT * FROM DETAIL WHERE DetailColumn2 = :MasterColumn1
To work with the MasterLinkDescriptor class programmatically, you set its properties when instantiating the MasterLinkDescriptor object. There are no write accessors for this class. The properties of the MasterLinkDescriptor object are:
When specifying the query statement for the detail DataSet, you should specify the linking columns in a where clause if fetchAsNeeded is true. If the fetchAsNeeded setting is not compatible with the detail query, you will get a DataSetException and anomalous results.
This section discusses how editing operations that affect multiple rows of a data set work on detail data sets. Only refresh() varies according to how the fetchAsNeeded property is set.
Self-joins (where a DataSet is linked to itself) are not supported in JDataStore.
To cascade updates and deletes, set the cascadeUpdates and cascadeDeletes properties as appropriate. These properties should be used with care, especially in cases where you have multiple master-detail relationships chained where a detail DataSet is a master to another detail (and so on). Typically in those circumstances, 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.
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.
In a master-detail relationship, visible detail rows include only those which match the current master. To see all detail rows, instantiate a DataSetView component using the detail DataSet as the data source. Navigation through the data in the DataSetView is also independent of that of the detail DataSet. To turn the master-detail relationship off, you can also call DataSet.setMasterLink(null).
In establishing a master-detail relationship using fetchAsNeeded, JDataStore uses the master DataSet columns in order to run the query that obtains the data for the detail DataSet. If there are no rows in the master DataSet, the detail query cannot be run.
An application can ensure that the detail query is always executable by setting up persistent columns for the master and detail data sets which include all respective linking columns.
This is especially important for a QueryDataSet that has a MasterLinkDescriptor with the fetchAsNeeded property set to true. In this case, DataExpress cannot determine what columns are present in the detail because its query cannot be run without parameter values from the current row of the master. Setting persistent columns for the detail linking columns will allow the detail data set to be opened.
public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns)Constructs a MasterLinkDescriptor with properties as specified in its parameters.
public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns, boolean fetchAsNeeded)Constructs a MasterLinkDescriptor with properties as specified in its parameters.
public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns, boolean fetchAsNeeded, boolean cascadeUpdates, boolean cascadeDeletes)Constructs a MasterLinkDescriptor with properties as specified in its parameters.
public boolean isCascadeDeletes()Read-only property that returns whether matching detail (DataSet) rows should be deleted when the corresponding row in the master DataSet is deleted. If true, deletes are also applied to matching details; if false, master rows that have details cannot be deleted. This property defaults to false meaning that deletes are not cascaded.
public boolean isCascadeUpdates()Read-only property that returns whether updates to linking columns in the master DataSet are also applied to rows in detail DataSets. If true, updates are cascaded to details; if false, updates to linking columns are not allowed if the master has details: the details would be orphaned by this operation. This property defaults to false meaning that updates are not cascaded.
public String[]getDetailLinkColumns()Read-only property that returns a String array containing the names of the column or columns of the detail DataSet that are used to link to the MasterDataSet. An index on the link columns of the detail DataSet is not required. The names of the link columns between the master and detail data sets do not need to match as long as the number and data types of linking columns do match.
Set this property when creating the MasterLinkDescriptor object by calling a MasterLinkDescriptor constructor that takes this property as a parameter.
public boolean isFetchAsNeeded()Read-only property that determines whether the detail rows are all fetched at one time, or when a master is navigated to whose details have not yet been fetched.
Set this property when creating the MasterLinkDescriptor object by calling a MasterLinkDescriptor constructor that takes this property as a parameter.
Set this property to true when you want to fetch the detail data when needed. This is useful when you don't need to access the data for most details, when the detail data set is very large, or when you want to see the most current information for that detail set. The disadvantage is that the data may not be consistent since detail fetching is done in separate transactions.
When true, the detail rows for the corresponding master are fetched and stored in the detail DataSet. As additional details are fetched for other master rows, the corresponding detail data is added to the same detail DataSet but filtered so that you only see the details for the current master. If the detail data has already been fetched for a particular master and you want to get a refresh from the data source, you must post any changes in the detail data set first; otherwise, updates will be lost.
If this property is true, there should be a WHERE clause in the query string of the detail DataSet. If the WHERE clause is omitted, a DataSetException of NO_WHERE_CLAUSE is generated.
Set this property to false to retrieve all detail data at one time so that the detail data is a consistent snapshot at the time of the fetch. This is useful when working off-line (when not directly connected to the data source), or when data consistency across all details is an issue. For example, in a situation where an update affects multiple rows of data, you may want to fetch all details at one time instead of as-needed to ensure that the updated data is consistent across all affected rows. (This assumes some level of transaction processing when changes are saved back to the data source.)
This property is used for QueryDataSet and ProcedureDataSet components. It has no effect for TableDataSet components since all detail rows are fetched at one time.
public DataSet getMasterDataSet()Read-only property that returns the instantiated DataSet object that is the master in the relationship. The current position in the MasterDataSet determines what data is visible in the detail data set. As you navigate through the data in the MasterDataSet, the corresponding data (based on matches in the linking columns) is displayed for the detail DataSet.
Set this property when creating the MasterLinkDescriptor object by calling a MasterLinkDescriptor constructor that takes this property as a parameter.
public String[]getMasterLinkColumns()Read-only property that returns a String array of columns of the master DataSet that are used to link to a DetailDataSet. An index on the link columns of the master DataSet is not required. The names of the link columns between the master and detail data sets do not need to match as long as the data types of the linking columns do match.
Set this property when creating the MasterLinkDescriptor object by calling a MasterLinkDescriptor constructor that takes this property as a parameter.