borland Packages  Class Hierarchy  dx.dataset Package 

MasterLinkDescriptor class

java.lang.Object
   +----com.borland.dx.dataset.MasterLinkDescriptor

About the MasterLinkDescriptor class

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.

Mechanisms for fetching detail data

There are two methods of using a StorageDataSet to provide the detail rows in a master-detail relationship:

Programmatically calling the MasterLinkDescriptor

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:

These properties are required on the detail DataSet only when setting up a master-detail relationship.

fetchAsNeeded for detail DataSets

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.

How editing operations affect multiple rows of a data set

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

Self-joins (where a DataSet is linked to itself) are not supported in JDataStore.

Cascading updates and deletes

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.

Displaying all detail data when a master-detail relationship is in effect

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

Empty master DataSet

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.


MasterLinkDescriptor constructors

MasterLinkDescriptor properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in java.lang.Object

MasterLinkDescriptor methods

Methods implemented in java.lang.Object


MasterLinkDescriptor constructors

MasterLinkDescriptor(com.borland.dx.dataset.DataSet, java.lang.String[], java.lang.String[])

  public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns)
Constructs a MasterLinkDescriptor with properties as specified in its parameters.

Parameters:

masterDataSet
The DataSet which is the master of the master-detail relationship.
masterLinkColumns
An array of String column names from the masterDataSet to use when linking.
detailLinkColumns
An array of String column names from the detail DataSet to use when linking.

MasterLinkDescriptor(com.borland.dx.dataset.DataSet, java.lang.String[], java.lang.String[], boolean)

  public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns, boolean fetchAsNeeded)
Constructs a MasterLinkDescriptor with properties as specified in its parameters.

Parameters:

masterDataSet
The DataSet which is the master of the master-detail relationship.
masterLinkColumns
An array of String column names from the masterDataSet to use when linking.
detailLinkColumns
An array of String column names from the detail DataSet to use when linking.
fetchAsNeeded
A boolean value which determines whether detail data is fetched all at once or fetched when a master is navigated to a row whose details have not yet been fetched. For more information on this property, see fetchAsNeeded.

MasterLinkDescriptor(com.borland.dx.dataset.DataSet, java.lang.String[], java.lang.String[], boolean, boolean, boolean)

  public MasterLinkDescriptor(DataSet masterDataSet, String[]masterLinkColumns, String[]detailLinkColumns, boolean fetchAsNeeded, boolean cascadeUpdates, boolean cascadeDeletes)
Constructs a MasterLinkDescriptor with properties as specified in its parameters.

Parameters:

masterDataSet
The DataSet which is the master of the master/detail relationship.
masterLinkColumns
An array of column names to use from master the master DataSet.
detailLinkColumns
An array of column names to use from the detail DataSet.
fetchAsNeeded
If true, causes details to be fetched as the master DataSet navigates. If the QueryDataSet or ProcedureDataSet components are being used, the detail query will be re-executed as the master is navigated.
cascadeUpdates
If true, updates to linking columns in the master DataSet are also cascaded to applicable rows in the detail DataSet. If false, updates to linking columns are not allowed if the master has details: they would be orphaned by this operation.
cascadeDeletes
If true, matching detail rows are deleted when the corresponding master DataSet row is deleted. If false, master rows that have details cannot be deleted.

MasterLinkDescriptor properties

cascadeDeletes

 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.

cascadeUpdates

 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.

detailLinkColumns

 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.

fetchAsNeeded

 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.

masterDataSet

 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.

masterLinkColumns

 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.