borland Packages  Class Hierarchy  dx.sql.dataset Package 

QueryDataSet class

java.lang.Object
   +----com.borland.dx.dataset.ReadRow
           +----com.borland.dx.dataset.ReadWriteRow
                   +----com.borland.dx.dataset.DataSet
                           +----com.borland.dx.dataset.StorageDataSet
                                   +----com.borland.dx.sql.dataset.QueryDataSet

About the QueryDataSet class

Properties  Methods  Event Listeners

Implements AccessListener, ColumnDesigner, Designable, MasterNavigateListener, StatusListener, Serializable, EventListener

The QueryDataSet class is an extension of its superclass (StorageDataSet) and provides functionality to run a query statement (with or without parameters) against a table in a SQL database.

In any application that uses the QueryDataSet, the following components are also required:

The data contained in a QueryDataSet is the result of the most recent query. The "result set" from the execution of the query is stored in the QueryDataSet, which allows for much greater flexibility in navigation of the resulting data. You specify how the data is loaded into the QueryDataSet (asynchronously, as needed, etc.) by specifying its loadOption property (stored in the associated QueryDescriptor). The QueryDataSet inherits the maxRows property which allows you to set the maximum number of rows that can be initially stored in the QueryDataSet from a query execution.

Once the data is stored in the QueryDataSet, you manipulate it and connect it to UI controls in exactly the same way as you would other StorageDataSet components, without regard to which component is storing the data.

The QueryDataSet component uses the QueryProvider and QueryResolver to perform the data providing and resolving functions.

Updatable versus read-only queries

By default, JDataStore automatically attempts to make a QueryDataSet updatable so that changes made to the data it contains can be resolved back to its data source. It analyzes the query and looks for row identifiers: one or more columns that uniquely identify each row. This is required to save any changed data back to the correct row of the original data. If you have not included these columns in your query's SELECT statement, JDataStore automatically adds them but sets the visibilty of such columns as "default". This hides them from any data aware controls that this QueryDataSet is connected to. You may change the column's visibility to true if desired.

Suppressing metadata discovery

To prevent the addition of row ID columns and various metadata related properties on DataSet and Column components, set this component's metaDataUpdate property to MetaDataUpdate.NONE.

If the rowId analysis fails or metaDataUpdate is set to NONE, you can make a QueryDataSet updatable by setting one or more of these properties (as applicable):

Fine-tuning query performance

To improve QueryDataSet performance on data retrieval,

To improve performance when performing data inserts, deletes, and updates:

Master-detail relationships

In a master-detail relationship, if you set the fetchAsNeeded property to true, you must include a WHERE clause in the detail query that matches the detail link column values to the master link column values.

For more information on master-detail relationships, see MasterLinkDescriptor.

Alias support and column name conflicts

JDataStore supports column aliases that are specified in a SQL Select statement. The name specified as the alias is stored in the columnName property and is used to access the DataExpress API. The original data source name is stored in the serverColumnName property for use when resolving changes back to the data source.

When a query joins two or more tables, it may return several columns that have the same name (often the columns used to link the tables have the same name). JDataStore handles duplicate column names by appending a number ("EMP_NO", "EMP_No1", etc.). The modified column name is stored in the columnName property and is used to access the DataExpress API. The original server name is stored in the serverColumnName property for (later) use when resolving data changes back to the data source.

These properties are also used for column aliases that are specified in SQL statements.

JDataStore also supports table aliases. For example, in the following query:

select e.emp_no, e.last_name  empl_last,  p.last_name,  phone_last 
        from employee e, phone_list p 
        where e.emp_no = p.emp_no and 
        e.last_name <> p.last_name 
The employee table is assigned the alias "e" and its last_name column is given the alias "empl_last". In multi-table queries, aliases can be useful.

Oracle synonyms

If a query is run against a synonym on an Oracle server, it is dependent on the support of synonyms in the JDBC driver to determine whether the query is updatable.

SQL views

Queries run against SQL views are supported, however, they may not be resolvable depending on what actions the SQL view performed. For example, if the view simply filters out rows, the server may be able to handle resolving the edits. You should be aware that you risk making edits that cannot later be resolved back to the data source. More likely, you will need to write your own resolver logic to handle this situation.

Examples and additional information

For more information on resolving changes to a QueryDataSet, see the QueryResolver component.


QueryDataSet properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in com.borland.dx.dataset.DataSet

Properties implemented in com.borland.dx.dataset.ReadRow

Properties implemented in com.borland.dx.dataset.ReadWriteRow

Properties implemented in com.borland.dx.dataset.StorageDataSet

Properties implemented in java.lang.Object

QueryDataSet methods

Methods implemented in this class

Methods implemented in com.borland.dx.dataset.DataSet

Methods implemented in com.borland.dx.dataset.ReadRow

Methods implemented in com.borland.dx.dataset.ReadWriteRow

Methods implemented in com.borland.dx.dataset.StorageDataSet

Methods implemented in java.lang.Object

QueryDataSet event listeners


QueryDataSet properties

accumulateResults

 public final boolean isAccumulateResults()
 public final void setAccumulateResults(boolean accumulate)
Determines whether the provided data is accumulated over consecutive calls to the executeQuery() method (true) or not (false). If this property is disabled, subsequent executeQuery() calls overwrite the existing DataSet.

database

 public final Database getDatabase()
Read-only property that stores the Database object that holds the connection to the SQL server.

originalQueryString

 public final String getOriginalQueryString()
Read-only property that returns the original query string. The query string may be automatically updated by JDataStore to include columns that form a unique rowID. Use this read accessor to obtain the original, unaltered query string.

parameterRow

 public ReadWriteRow getParameterRow()
Read-only property that returns the ReadWriteRow object that contains the parameters for the query.

Note: If the query contains parameters, you need to call DataSet.close() before providing for another QueryDataSet.

provider

 public void setProvider(Provider provider)
Stores the QueryProvider associated with this QueryDataSet component. When setting this property, only a QueryProvider is acceptable. A DataSetException of NEED_QUERY_PROVIDER is generated if this property is not set.

query

 public final QueryDescriptor getQuery()
 public final void setQuery(QueryDescriptor queryDescriptor)
Specifies the QueryDescriptor object that stores query properties which make the QueryDataSet usable.

QueryDataSet methods

closeStatement()

  public void closeStatement()
If Database.isUseStatementCaching() returns true, JDBC statements can be cached. By default these statements will be closed during garbage collection. If resources are scarce, the statement can be forced closed by calling this method.

executeQuery()

  public final void executeQuery()
Calls refresh().

You can call the executeQuery() method without an open DataSet. However, if the DataSet is open, executeQuery() will close the DataSet, execute the query, then re-open the DataSet.

getQueryString(com.borland.dx.dataset.StorageDataSet)

  public final String getQueryString(StorageDataSet sds)
Returns the query string executed against the data source. This query string may have been automatically altered by JDataStore; use getOriginalQueryString() to obtain the original, unaltered query string.

refetchRow(com.borland.dx.dataset.ReadWriteRow)

  public void refetchRow(ReadWriteRow row)
Fetches the original row from the data source based on the key field of the row you pass in. For example, if the key field of the row is "foobar", this method fetches the row in the DataSet with that key field.

Overrides: com.borland.dx.dataset.DataSet.refetchRow(ReadWriteRow)

refresh()

  public void refresh()
Given that the database and query properties have been set, executes the query and populates the DataSet.

Overrides: com.borland.dx.dataset.StorageDataSet.refresh()

refreshSupported()

  public boolean refreshSupported()
Returns true.

Overrides: com.borland.dx.dataset.StorageDataSet.refreshSupported()

saveChanges(com.borland.dx.dataset.DataSet)

  public void saveChanges(DataSet dataSet)
Calls Database.saveChanges() with the DataSet object specified in its parameter.

Overrides: com.borland.dx.dataset.StorageDataSet.saveChanges(com.borland.dx.dataset.DataSet)

saveChangesSupported()

  public boolean saveChangesSupported()
Returns true. Used internally by data-aware controls to determine if a saveChanges() type operation is supported.

Overrides: com.borland.dx.dataset.StorageDataSet.saveChangesSupported()


QueryDataSet event listeners

This class is a source for the following event sets.

access

 public final void addAccessListener(AccessListener listener)
 public final void removeAccessListener(AccessListener listener)

calcAggFields

 public synchronized void addCalcAggFieldsListener(CalcAggFieldsListener listener)
 public synchronized void removeCalcAggFieldsListener(CalcAggFieldsListener listener)

calcFields

 public synchronized void addCalcFieldsListener(CalcFieldsListener listener)
 public synchronized void removeCalcFieldsListener(CalcFieldsListener listener)

columnChange

 public void addColumnChangeListener(ColumnChangeListener listener)
 public synchronized void removeColumnChangeListener(ColumnChangeListener listener)

dataChange

 public final void addDataChangeListener(DataChangeListener listener)
 public final void removeDataChangeListener(DataChangeListener listener)

edit

 public void addEditListener(EditListener listener)
 public synchronized void removeEditListener(EditListener listener)

load

 public final synchronized void addLoadListener(LoadListener listener)
 public final synchronized void removeLoadListener(LoadListener listener)

masterNavigate

 public final void addMasterNavigateListener(MasterNavigateListener listener)
 public final void removeMasterNavigateListener(MasterNavigateListener listener)

navigation

 public final void addNavigationListener(NavigationListener listener)
 public final void removeNavigationListener(NavigationListener listener)

open

 public final void addOpenListener(OpenListener listener)
 public final void removeOpenListener(OpenListener listener)

rowFilter

 public final void addRowFilterListener(RowFilterListener listener)
 public final void removeRowFilterListener(RowFilterListener listener)

status

 public final void addStatusListener(StatusListener listener)
 public final void removeStatusListener(StatusListener listener)