borland Packages Class Hierarchy dx.sql.dataset Package
java.lang.Object +----com.borland.dx.sql.dataset.QueryDescriptor +----com.borland.dx.sql.dataset.ProcedureDescriptor
Constructors Properties Methods
Implements Serializable
The QueryDescriptor
stores properties that set a query statement to run against a SQL database.
To access SQL table data using a QueryDataSet
,
the Database
component and QueryDescriptor
object are also required. The properties of the QueryDescriptor
object are:
Database
object which is associated to a particular userName
and
connectionURL
(required)
QueryDataSet
is opened.
ResourceBundle
QueryDataSet
To work with this component programmatically, you set its properties when instantiating
the QueryDescriptor
object, or individually by its write accessor methods. For
properties that do not have a corresponding setter method, use a constructor that takes that
property as a parameter.
Through the user-interface, the information stored in the QueryDescriptor
can be
accessed by inspecting the query
property of a QueryDataSet
object. This
displays the Query property editor. The Query property editor also provides the additional
functionality of
A Browse Tables button which assists in table discovery. Clicking this button displays
a dialog listing available tables in the database (as specified by the Database
property).
When you select a table from this dialog, its columns are listed as well. Buttons allow you to
easily paste the table or column name into the query string to create the query statement to
run against the server database.
A SQL Builder button that offers UI assistance with the query statement creation.
A Test Query button which allows you to explicitly test the query properties from within the Query property editor. A "Success" or "Fail" message displays in the gray area beneath this button as applicable.
Query statements in the Query property editor display with any line breaks you've entered. When JBuilder generates source code for your query, it preserves the newlines so that the query looks the same when you redisplay it later in query editor. In source, the newlines are stored as "\n", which are removed when the query is passed to database for execution as some servers do not support this.
Data can be loaded all in one fetch, as needed, asynchronously or one at a time (as specified by the loadOption
property).
When working with asynchronous queries, opening the QueryDataSet
then immediately
calling methods such as rowCount()
typically returns a row count lower than expected.
To avoid this, either set the query to synchronous, listen for the LoadingEvent
,
perform other actions while the QueryDataSet
completes loading, or listen for
updates to the row count.
As an asynchronous query fetches rows of data, they are appended to the end of the DataSet
.
When working with a sorted view of the DataSet
, the new rows appear in the specified sort order.
Also, be careful to not make assumptions about the current row position since rows are inserted into the sorted view as they are fetched, thereby changing row positions automatically.
When executing queries, you have several options from which to choose, depending on your query statement. If your statement returns a ResultSet
, use a QueryDataSet
component with a QueryDescriptor
. For example, the statement
select * from customer
If you also require the addition of parameter passing (all named or all unnamed), assign these values to an object derived from ReadWriteRow
(for example, a ParameterRow
) in conjunction with the QueryDataSet
.
Do not use a QueryDataSet
if your SQL statement doesn't yield a ResultSet
. Instead, use one of the following:
Database.executeStatement(...)
method.
To execute a SQL statement with parameters, use the QueryProvider.executeStatement(...)
method.
To execute a statement that has output parameters, use the ProcedureProvider.callProcedure(...)
method.
Through the Query property editor, the SQL statement entered may be optionally resourced into a separate file. This provides a logical separation between the code which uses the SQL statement and the contents of that statement. This allows a developer to change the SQL statement inside the resourced file without needing to recompile the code which uses the SQL. Once a SQL statement has been resourced, any future changes to it in the JBuilder design tools will modify the resource file, not the source file referring to that SQL string. This property appears only in the Query property editor (as the Resource SQL String checkbox) and has no programmatic counterpart since its selection state merely affects the structure of the code that is automatically generated by the UI designer tools. For more information on this option, see Place SQL text in resource bundle from the Query property editor F1 help topic.
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.
For examples on using a QueryDataSet
and its associated QueryDescriptor
,
see "Querying a database" in the Database Application Developer's Guide. If your query uses parameters, see
"Using parameterized queries to obtain
data from your database" in the Database Application Developer's Guide.
public QueryDescriptor(Database database, String query)Constructs a
QueryDescriptor
object with the following properties:
database
Database
object the QueryDataSet
is to run against.
query
database
.
public QueryDescriptor(Database database, String query, boolean executeOnOpen)Constructs a
QueryDescriptor
object with the following properties:
database
Database
object the QueryDataSet
is to run against.
query
database
.
executeOnOpen
QueryDataSet
is opened.
public QueryDescriptor(Database database, String query, ReadWriteRow parameters)Constructs a
QueryDescriptor
object with the following properties:
database
Database
object the QueryDataSet
is to run against.
query
database
.
parameters
ReadWriteRow
implementation that contains the values to use for the parameters of the query string.
public QueryDescriptor(Database database, String query, ReadWriteRow parameters, boolean executeOnOpen)Constructs a
QueryDescriptor
object with the following properties:
database
Database
object the QueryDataSet
is to run against.
query
database
.
parameters
ReadWriteRow
implementation that contains the values to use for the parameters of the query string.
executeOnOpen
QueryDataSet
is opened.
public QueryDescriptor(Database database, String query, ReadWriteRow parameters, boolean executeOnOpen, boolean asynchronousExecution)This constructor has been deprecated. Use a constructor that takes a
loadOption
parameter, or set the loadOption
property directly.
public QueryDescriptor(Database database, String query, ReadWriteRow parameters, boolean executeOnOpen, int loadOption)Constructs a
QueryDescriptor
object with the following properties:
database
Database
object the QueryDataSet
is to run against.
query
database
.
parameters
ReadWriteRow
implementation that contains the values to use for the parameters of the query string.
executeOnOpen
QueryDataSet
is opened.
loadOption
QueryDataSet
.
Constants for this parameter are defined as Load
variables.
public final boolean isAsynchronousExecution() public final void setAsynchronousExecution(boolean async)This property has been deprecated. Use a constructor that takes a
loadOption
parameter, or set the loadOption
property directly.
public Database getDatabase()
Read-only property that returns the instantiated Database that the query is associated with.
To set this property, use any QueryDescriptor
constructor that takes this property as a parameter.
public boolean isExecuteOnOpen() public void setExecuteOnOpen(boolean executeOnOpen)
If the QueryDataSet
is empty, this property specifies whether the query is executed
automatically when the QueryDataSet
is opened. ("Empty" refers to a DataSet
not having any visible or non-visible rows.) When true (the default value),
the query is executed automatically and allows for live data to display in UI controls (such
as the GridControl
) in the JBuilder UI Designer. To prevent the query from automatically
executing when the QueryDataSet
is opened, set this property to false.
This property does not apply to the ProcedureDescriptor
subclass of the QueryDescriptor
when used with a ProcedureResolver
component.
public final int getLoadOption() public final void setLoadOption(int loadOption)Returns the options specified for loading the
QueryDataSet
with data. Valid values for this property are defined in Load
variables.
public ReadWriteRow getParameterRow()Specifies the
ReadWriteRow
implementation that stores the parameters for the query
statement.
public String getQueryString()Read-only property that returns the query string to run against the
Database
.
To set this property, use any QueryDescriptor
constructor that takes this property as a parameter.
public String toString()Returns a
String
equivalent of the property values stored in the QueryDescriptor
.
This String
representation appears in the JBuilder Inspector as the value of the query
property.