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.
Indexes for the linking relationship are created as needed, quickly and efficiently.
There are two methods of using a StorageDataSet
to provide the detail rows in a master-detail relationship:
DataSets
are linked based on the cached data, using settings stored in the MasterLinkDescriptor
.
delayed fetching: is a less consistent view of the data. Each time a master row is visited for the first time, its detail data is fetched by re-executing the detail query. The detail query must contain a WHERE clause with links to the master DataSet
using named parameters. The detail DataSet
's loadRow()
method is invoked each time a master row is first encountered. This method extracts the link columns data values from the master (as specified in the MasterLinkDescriptor
) and binds them to the query. Then the query executes and the results of that query added to any already cached rows in the detail DataSet
. There must be a one-to-one match of the master DataSet
columns names to the named parameters in the WHERE clause of the detail QueryDataSet
.
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
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:
fetchAsNeeded
detailLinkColumns
masterDataSet
masterLinkColumns
cascadeDeletes
cascadeUpdates
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 Inspector, then click the ellipses button. Set the properties that define the master-detail relationship
using this dialog. This dialog also includes a Test Link button that tests the masterLink
property
settings. Status messages appear in the gray area to the right of the Test Link button.
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.
saveChanges()
method (and the Save button on a JdbNavToolBar
) saves changes to all details sets for all masters,
whether fetchAsNeeded
is true or false.
The refresh()
method (and the Refresh button on a JdbNavToolBar
) performs differently according to fetchAsNeeded
. If fetchAsNeeded
is false, it refreshes all detail sets; if true, it refreshes the details for the current master row only. This is consistent with the fact that detail sets are fetched at different times when fetchAsNeeded
is true, or are never fetched if their masters are never visited, so they are also refreshed independently.
The empty()
method deletes all details for all master rows, whether fetchAsNeeded
is true or false.
The emptyAllRows()
method deletes all details for the current master row only, whether fetchAsNeeded
is true or false. This is because
emptyAllRows()
affects visible rows only, and only one detail set is visible at a time.
Self-joins (where a DataSet
is linked to itself) are not supported.
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)
.
DataSet
In establishing a master-detail relationship using fetchAsNeeded
, the master DataSet
columns are used 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.
delayedDetailFetch
is enabled. The jbInit()
method in the DataModule1.java
file shows the following source code:
custOrderDataSet.setMasterLink(new com.borland.dx.dataset.MasterLinkDescriptor(customerDataSet, new String[]{"ID"}, new String[] {"CUSTOMERID"}, true)); custOrderDataSet.setReadOnly(true); custOrderDataSet.setQuery(new com.borland.dx.sql.dataset.QueryDescriptor(database1, "SELECT ID, CUSTOMERID, ORDERDATE, STATUS, SHIPDATE FROM ORDERS WHERE CUSTOMERID = :ID", null, true, Load.ALL));See the source code for the project directly at the above location of your JBuilder installation.
For additional 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(DataSet masterDataSet, String[] masterLinkColumns, String[] detailLinkColumns)Constructs a
MasterLinkDescriptor
with properties as specified in its parameters.
masterDataSet
DataSet
which is the master of the master-detail relationship.
masterLinkColumns
String
column names from the masterDataSet
to use when linking.
detailLinkColumns
String
column names from the detail DataSet
to use when linking.
public MasterLinkDescriptor(DataSet masterDataSet, String[] masterLinkColumns, String[] detailLinkColumns, boolean fetchAsNeeded)Constructs a
MasterLinkDescriptor
with properties as specified in its parameters.
masterDataSet
DataSet
which is the master of the master-detail relationship.
masterLinkColumns
String
column names from the masterDataSet
to use when linking.
detailLinkColumns
String
column names from the detail DataSet
to use when linking.
fetchAsNeeded
fetchAsNeeded
.
public MasterLinkDescriptor(DataSet masterDataSet, String[] masterLinkColumns, String[] detailLinkColumns, boolean fetchAsNeeded, boolean cascadeUpdates, boolean cascadeDeletes)Constructs a
MasterLinkDescriptor
with properties as specified in its parameters.
masterDataSet
DataSet
which is the master of the master/detail relationship.
masterLinkColumns
DataSet
.
detailLinkColumns
DataSet
.
fetchAsNeeded
DataSet
navigates. If the QueryDataSet
or ProcedureDataSet
components are being used, the detail query will be re-executed as the master is navigated.
cascadeUpdates
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
DataSet
row is deleted. If false, master rows that have details cannot be deleted.
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.