Class com.ibm.db.SelectStatement
java.lang.Object
|
+----com.ibm.db.Statement
|
+----com.ibm.db.SelectStatement
- public class SelectStatement
- implements DatabaseConnectionAfterListener
- extends Statement
SelectStatement represents an SQL Select statement.
- See Also:
- Statement
Constructor Index
- SelectStatement()
- Constructs a new SelectStatement.
- SelectStatement(boolean)
- Constructs a new SelectStatement.
Method Index
- areDistinctTypesEnabled()
- Returns true if use of user-defined distinct types is enabled for this statement.
- cancelExecution()
- Cancels execution of the SQL statement which is associated with
this SelectStatement.
- close()
- Applies any changes in the current row of the associated Select Result to the
database, and then closes the result set and the statement.
- committed(DataEvent)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
commmitted
fires.
- connected(DataEvent)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
connected
fires.
- disconnected(DataEvent)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
disconnected
fires and closes the statement.
- execute()
- Executes the SQL SELECT statement and positions to the first row in the result set.
- getMaximumPacketsInCache()
- Returns the maximum number of packets the cache can contain at one time.
- getMaximumRows()
- Returns the maximum size of the result set.
- getPacketSize()
- Returns the number of rows that are in one packet.
- getResult()
- Returns the SelectResult that is associated with this SelectStatement.
- isFillCacheOnExecute()
- Returns true if as many rows as allowed are fetched into the cache when
execute
is invoked.
- isForceSearchedUpdate()
- Returns true if searched update/delete will always be done when
updateRow()/deleteRow()
is invoked.
- isLockRows()
- Returns true if a database lock is automatically held on a row while
it is the current row in the associated Select Result.
- isOpen()
- Returns true if the statement is open in the database and can be accessed,
otherwise returns false.
- refresh()
- Refreshes the result set from the database by re-executing the SQL SELECT statement.
- rolledBack(DataEvent)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
rolledBack
fires.
- setConnection(DatabaseConnection)
- Associates a DatabaseConnection with the Statement.
- setDistinctTypesEnabled(boolean)
- If true, use of user-defined distinct types is enabled for this statement.
- setFillCacheOnExecute(boolean)
- If true, as many rows as allowed are fetched into the cache when
execute
is invoked.
- setForceSearchedUpdate(boolean)
- If true, a searched update will be done when
updateRow()
is invoked and a searched delete will be done when deleteRow()
is invoked.
- setLockRows(boolean)
- If true, a database lock is automatically held on a row while
it is the current row in the associated Select Result.
- setMaximumPacketsInCache(int)
- Sets the maximum number of packets the cache can contain at one time.
- setMaximumRows(int)
- Sets the maximum size of the result set.
- setMetaData(StatementMetaData)
- Associates a StatementMetaData with the Statement.
- setPacketSize(int)
- Sets the number of rows that are in one packet.
Constructors
SelectStatement
public SelectStatement()
- Constructs a new SelectStatement.
SelectStatement
public SelectStatement(boolean forVAJava)
- Constructs a new SelectStatement. If
forVAJava
is true,
messages that refer to a row number, a column number, or the current row will
be reported in VisualAge for Java Select bean terms (zero-based),
instead of one-based.
This constructor only be used by classes in com.ibm.ivj.db.uibeans package.
- Parameters:
- forVAJava - if true report row, column and currentRow in VisualAge
terms.
Methods
areDistinctTypesEnabled
public boolean areDistinctTypesEnabled()
- Returns true if use of user-defined distinct types is enabled for this statement.
Returns false if use of user-defined distinct types is not enabled for this statement.
See the
setDistinctTypesEnabled
method for a fuller
discussion of what it means for use of user-defined distinct types to be enabled.
- Returns:
- true if use of user-defined distinct types is enabled, otherwise false.
- See Also:
- setDistinctTypesEnabled
cancelExecution
public void cancelExecution() throws DataException
- Cancels execution of the SQL statement which is associated with
this SelectStatement. In order to use this method, it must be invoked
from a thread different from the one in which the SQL statement is running.
The SQL statement is either the one that executes the SELECT, or
the one associated with a subsequent request to insert, update, or delete
a row in the result set.
- Throws: DataException
- noConnection
- if no associated DatabaseConnection
- Throws: DataException
- notExecuting
- if the statement is not currently being executed
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- cancelExecution in class Statement
close
public void close() throws DataException
- Applies any changes in the current row of the associated Select Result to the
database, and then closes the result set and the statement.
JDBC resources associated with the statement and its result set are
released. After the statement is closed, no more rows can be fetched into
the result set, but you can still use the SelectResult to update the database,
and you can re-execute the statement.
Even if you do not explicitly call close()
,
JDBC resources are automatically freed when your SelectStatement is garbage collected,
However, changes to the current row are not automatically applied in that case.
The events aboutToClose
and closed
are
triggered by this method.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- sqlException
- if an SQLException occurred
committed
public void committed(DataEvent event)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
commmitted
fires. Takes no action.
- Parameters:
- event - a DataEvent
connected
public void connected(DataEvent event)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
connected
fires. Takes no action
- Parameters:
- event - a DataEvent
disconnected
public void disconnected(DataEvent event)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
disconnected
fires and closes the statement.
- Parameters:
- event - a DataEvent
execute
public synchronized void execute() throws DataException
- Executes the SQL SELECT statement and positions to the first row in the result set.
If needed, a connection is made to the database prior to executing the
SQL statement, using the associated DatabaseConnection. The SQL statement is
obtained from the StatementMetaData associated with this SelectStatement.
The result set can be accessed through the SelectResult associated with
this SelectStatement.
The events aboutToExecute
and executed
are
triggered by this method.
The event cacheRowsChanged
of the associated SelectResult is triggered
by this method.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
- Throws: DataException
- noConnection
- if no associated DatabaseConnection
- Throws: DataException
- noGui
- if no GUI available and logon prompt requested
- Throws: DataException
- badUidPwd
- if incorrect Userid or password specified
- Throws: DataException
- noSQL
- if the SQL statement is null
- Throws: DataException
- notSelect
- if SQL statement is not a SELECT statement
- Throws: DataException
- noTransactions
- if database does not support transactions and autoCommit set to false
- Throws: DataException
- sqlException
- if an SQLException occurred
- Overrides:
- execute in class Statement
- See Also:
- DatabaseConnection
- StatementMetaData
- SelectResult
getMaximumPacketsInCache
public int getMaximumPacketsInCache()
- Returns the maximum number of packets the cache can contain at one time. If there is
no limit to the number of packets, the value is 0.
The number of rows the cache can contain at one time is the number of packets it can
contain times the number of rows in a packet.
- Returns:
- the maximum number of packets in the cache
- See Also:
- setMaximumPacketsInCache
- getPacketSize
getMaximumRows
public int getMaximumRows()
- Returns the maximum size of the result set. If there is no limit to the size
of the result set, the value is 0.
This limit governs not how many rows the cache can contain at one time, but
how many rows can be fetched in total over time.
- Returns:
- the maximum size of the result set.
- See Also:
- setMaximumRows
getPacketSize
public int getPacketSize()
- Returns the number of rows that are in one packet. Whenever you execute a method that
can require rows to be fetched, such as
execute
or nextRow
,
if any rows must be fetched, a whole packet of rows is fetched.
A packet is also the unit in which rows are displaced from the cache when it is full
and more rows must be fetched.
If the value for the packet size is less than 1, the default packet size of 1
is used.
- Returns:
- the number of rows in a packet.
- See Also:
- setPacketSize
- getMaximumPacketsInCache
getResult
public SelectResult getResult()
- Returns the SelectResult that is associated with this SelectStatement.
You can access the result set from executing the SQL statement through the SelectResult.
- Returns:
- the associated SelectResult
isFillCacheOnExecute
public boolean isFillCacheOnExecute()
- Returns true if as many rows as allowed are fetched into the cache when
execute
is invoked.
Returns false if rows are fetched into the cache only as needed to satisfy
a request to set the current row position.
The number of rows you are allowed to fetch into the cache is the smallest of:
the total number of rows, the number of rows in a packet times the maximum
number of packets allowed in the cache, and the maximum number of rows you are
allowed to fetch over time.
If rows are fetched only as needed, one packet of rows is fetched on execute
.
- Returns:
- true if as many rows as allowed will be fetched on
execute
; else false.
- See Also:
- setFillCacheOnExecute
- getPacketSize
- getMaximumPacketsInCache
- getMaximumRows
- isFillResultCacheOnExecute
isForceSearchedUpdate
public boolean isForceSearchedUpdate()
- Returns true if searched update/delete will always be done when
updateRow()/deleteRow()
is invoked.
- Returns:
- true if searched update/delete will always be done,
else false.
- See Also:
- setForceSearchedUpdate
isLockRows
public boolean isLockRows()
- Returns true if a database lock is automatically held on a row while
it is the current row in the associated Select Result. Returns false
if a database lock is only held on a row while it is being updated in the
database.
See the lockRow
method of SelectResult for a fuller
discussion of what it means for a row to be locked.
- Returns:
- true if a database lock is automatically held on a row while
it is the current row; else false.
- See Also:
- setLockRows
- lockRow
isOpen
public boolean isOpen()
- Returns true if the statement is open in the database and can be accessed,
otherwise returns false.
If the statement is not open, results cannot be fetched from the the database, but
you can still use the associated SelectResult to do updates.
When
isOpen
returns false, it may be because the statement
has not been executed, the close
method has been invoked, you have
disconnected from the database, or the SelectStatement has been serialized and
then de-serialized.
- Returns:
- true if the statement is open in the database, otherwise false.
refresh
public synchronized void refresh() throws DataException
- Refreshes the result set from the database by re-executing the SQL SELECT statement.
The statement must currently be open.
Any changes you have made to statement parameters will take effect when the
statement is re-executed. If you have changed the SQL SELECT statement itself in the
StatementMetaData, that change will not take effect. (To make the latter change take
effect, use the
execute
method.
The event cacheRowsChanged
of the associated SelectResult is triggered
by this method.
The events aboutToExecute
and executed
are
triggered by this method.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
- Throws: DataException
- notOpen
- if the statement is not open
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- execute
rolledBack
public void rolledBack(DataEvent event)
- Invoked when the com.ibm.db.DatabaseConnectionAfter event
rolledBack
fires. Takes no action.
- Parameters:
- event - a DataEvent
setConnection
public void setConnection(DatabaseConnection connection)
- Associates a DatabaseConnection with the Statement.
- Parameters:
- connection - the associated DatabaseConnection
- Overrides:
- setConnection in class Statement
- See Also:
- getConnection
setDistinctTypesEnabled
public void setDistinctTypesEnabled(boolean aValue)
- If true, use of user-defined distinct types is enabled for this statement.
If false, use of user-defined distinct types is not enabled for this statement.
If you never execute this method for a Statement, the value defaults to false.
When use of user-defined distinct types is not enabled for a statement, and the
result set contains columns with user-defined distinct types, you cannot use
a result set produced from the statement to update, delete, or lock a row. You can, however,
retrieve data of user-defined types, and you can use the result set to insert rows in the
database.
When use of user-defined distinct types is enabled for a statement, you can retrieve data of
user defined types, as well as use the result set to insert, update, delete, or lock rows.
Implementation of this feature makes use of the CAST specification in SQL. The database
you are using must support casting if you turn this enablement on. It does no harm to
turn enablement on even if your statement uses no user-defined distinct types, but
the SQL we generate to update, delete, or lock a row will be more complex, making use of the
CAST specification for all columns.
- Parameters:
- aValue - true if use of user-defined distinct types should be enabled;
false if it should not be enabled.
- See Also:
- areDistinctTypesEnabled
setFillCacheOnExecute
public void setFillCacheOnExecute(boolean fillCacheOnExecute)
- If true, as many rows as allowed are fetched into the cache when
execute
is invoked.
Otherwise, rows are fetched into the cache as needed to satisfy
a request to set the current row position.
The number of rows you are allowed to fetch into the cache is the smallest of:
the total number of rows, the number of rows in a packet times the maximum
number of packets allowed in the cache, and the maximum number of rows you are
allowed to fetch over time.
If rows are fetched only as needed, one packet of rows is fetched on execute
.
If you never execute this method for a SelectStatement, the value defaults to true.
- Parameters:
- fillCacheOnExecute - true, fetch as many rows as allowed on
execute
;
false fetch rows only as needed
- See Also:
- isFillCacheOnExecute
- setPacketSize
- setMaximumPacketsInCache
- setMaximumRows
setForceSearchedUpdate
public void setForceSearchedUpdate(boolean forceSearchedUpdate)
- If true, a searched update will be done when
updateRow()
is invoked and a searched delete will be done when deleteRow()
is invoked.
By default, searched updates and deletes are only done for
Oracle, Microsoft SQL Server, Sybase SQL Server, and databases which do not
support positioned updates and deletes (as reported in the JDBC DatabaseMetaData).
For other databases, positioned updates and deletes are attempted. If these are
being attempted but failing, you can use this method to force searched updates
and deletes, which should be universally supported. See the updateRow
and deleteRow
methods of SelectResult for the implications of doing
positioned versus searched updates and deletes.
If you do not execute this method for a SelectStatement, the value defaults to
false.
- Parameters:
- forceSearchedUpdate - true, always use a searched update/delete;
false use a positioned update/delete if database supports it
- See Also:
- isForceSearchedUpdate
- updateRow
- deleteRow
setLockRows
public void setLockRows(boolean lockRows)
- If true, a database lock is automatically held on a row while
it is the current row in the associated Select Result. If false,
a database lock is only held on a row while it is being updated in the
database.
If you never execute this method for a SelectStatement, the value defaults to false.
See the lockRow
method of SelectResult for a fuller
discussion of what it means for a row to be locked.
- Parameters:
- lockRows - true, hold database lock while a row is the current row;
false hold database lock only while a row is being updated.
- See Also:
- isLockRows
- lockRow
setMaximumPacketsInCache
public void setMaximumPacketsInCache(int maximumPacketsInCache)
- Sets the maximum number of packets the cache can contain at one time. Set the value to 0
if there is no limit on the number of packets in the cache.
The number of rows the cache can contain at one time is the number of packets it can
contain times the number of rows in a packet.
If you never execute this method for a SelectStatement, the value defaults to 0.
- Parameters:
- maximumPacketsInCache - the maximum number of packets in cache
- See Also:
- getMaximumPacketsInCache
- setPacketSize
setMaximumRows
public void setMaximumRows(int maximumRows)
- Sets the maximum size of the result set. Set the value to 0 if there is
no limit on the number of rows that can be contained in the result set.
This limit governs not how many rows the cache can contain at one time, but
how many rows can be fetched in total over time.
If you never execute this method for a SelectStatement, the value defaults to 0.
- Parameters:
- maximumRows - the maximum number of rows in the result set
- See Also:
- getMaximumRows
setMetaData
public synchronized void setMetaData(StatementMetaData metaData)
- Associates a StatementMetaData with the Statement.
- Parameters:
- metaData - the associated StatementMetaData
- Overrides:
- setMetaData in class Statement
- See Also:
- getMetaData
setPacketSize
public void setPacketSize(int packetSize)
- Sets the number of rows that are in one packet. Whenever you execute a method that
can require rows to be fetched, such as
execute
or nextRow
,
if any rows must be fetched, a whole packet of rows is fetched.
A packet is also the unit in which rows are displaced from the cache when it is full
and more rows must be fetched.
If you never execute this method for a SelectStatement, the value defaults to 1.
Setting the value to less than 1 has the same effect as allowing it to default to 1.
- Parameters:
- packetSize - the number of rows in a packet
- See Also:
- getPacketSize
- setMaximumPacketsInCache
