borland Packages Class Hierarchy jbcl.dataset Package Index
java.lang.Object +----borland.jbcl.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. JBuilder creates indexes for the linking relationship as needed, quickly and efficiently.
To work with this class programatically, you set its properties when instantiating the MasterLinkDescriptor. There are no write accessors for this class. The properties of the MasterLinkDescriptor object are:
These properties can be accessed through the JBuilder user interface when inspecting the masterLink property of a DataSetView, QueryDataSet, ProcedureDataSet, or TableDataSet. These properties are required on the detail DataSet only when setting up a master-detail relationship. The masterLink property editor displays when you double-click the masterLink property of the detail DataSet in the JBuilder Component Inspector, then click the ellipses button. Set the properties that define the master-detail relationship using this dialog. This dialog also includes a Test button that tests the masterLink property settings. Status messages appear in the gray area beneath the Test button.
When specifying the query statement for the detail DataSet, you must specify the linking columns in a where clause if fetchAsNeeded is true.
Note: When performing a link that is a self-join (where a DataSet is linked to itself), JBuilder displays the linked data. However, edits to the data, particularly the data contained in the detail DataSet may not work as expected.
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 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 updatable. 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.
For more information on how to create a master-detail relationship and an example, see Establishing a master-detail relationship in the Database Application Developer's Guide.
public MasterLinkDescriptor(borland.jbcl.dataset.DataSet masterDataSet, java.lang.String[] masterLinkColumns, java.lang.String[] detailLinkColumns)Constructs a MasterLinkDescriptor with properties as specified in its parameters.
Parameters:
public MasterLinkDescriptor(borland.jbcl.dataset.DataSet masterDataSet, java.lang.String[] masterLinkColumns, java.lang.String[] detailLinkColumns, boolean fetchAsNeeded)Constructs a MasterLinkDescriptor with properties as specified in its parameters.
Parameters:
public MasterLinkDescriptor(borland.jbcl.dataset.DataSet masterDataSet, java.lang.String[] masterLinkColumns, java.lang.String[] detailLinkColumns, boolean fetchAsNeeded, boolean cascadeUpdates, boolean cascadeDeletes)Constructor for MasterLinkDescriptor
Parameters:
public boolean isCascadeDeletes()Stores 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, deletes are not cascaded. This property defaults to false meaning that deletes are not cascaded.
public boolean isCascadeUpdates()Stores 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 are not cascaded. 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.)
If this property is false, there should not be a WHERE clause in the query string of the detail DataSet. If the WHERE clause is included, a DataSetException of QUERY_FAILED is generated.
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.