borland Packages  Class Hierarchy  jbcl.dataset Package  Index 

MasterLinkDescriptor class

java.lang.Object
   +----borland.jbcl.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. 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.


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(borland.jbcl.dataset.DataSet, java.lang.String[], java.lang.String[])

  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:

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(borland.jbcl.dataset.DataSet, java.lang.String[], java.lang.String[], boolean)

  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:

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 whose details have not yet been fetched. For more information on this property, see fetchAsNeeded.

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

  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:

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.
masterLinkColumns
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-exectuted as the master is navigated.

MasterLinkDescriptor properties

cascadeDeletes

 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.

cascadeUpdates

 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.

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

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.

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.