Class com.ibm.ivj.db.uibeans.Select
java.lang.Object
|
+----com.ibm.ivj.db.uibeans.Statement
|
+----com.ibm.ivj.db.uibeans.Select
- public class Select
- implements Serializable, DatabaseConnectionAfterListener, DatabaseConnectionBeforeListener, StatementAfterListener, StatementBeforeListener, PropertyChangeListener, StatementResultAfterListener, StatementResultBeforeListener, StatementResultValueChangeListener, TableModel
- extends Statement
Select allows you to access and change data in a relational database using
JDBC.
Constructor Index
- Select()
- Constructs a new Select and initializes properties to the default values.
Method Index
- aboutToAddNewRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToAddNewRow
fires, and fires the corresponding DataBefore event
aboutToAddNewRow
.
- aboutToDeleteRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToDelete
fires, and fires the corresponding DataBefore event
aboutToDelete
.
- aboutToSetColumnValue(PropertyChangeEvent)
- Invoked when the underlying com.ibm.db.StatementResultValueChange event
aboutToSetColumnValues
fires.
- aboutToUpdateRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToUpdateRow
fires, and fires the corresponding DataBefore event
aboutToUpdateRow
.
- addedNewRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
addedNewRow
fires, and fires the corresponding DataAfter event
addedNewRow
.
- addTableModelListener(TableModelListener)
- Adds a listener to the TableModel event set.
- areDistinctTypesEnabled()
- Returns true if use of user-defined distinct types is enabled for this Select.
- cacheRowsChanged(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
cacheRowsChanged
fires, and fires the corresponding DataAfter event
cacheRowsChanged
.
- cancelAction()
- Cancels execution of the SQL statement which is associated with
this Select.
- close()
- Applies any changes in the current row to the
database, and then closes the result set and the statement.
- columnNames()
- Returns the names of the columns of the result set.
- columnValueSet(PropertyChangeEvent)
- Invoked when the underlying com.ibm.db.StatementResultValueChange event
columnValueSet
fires, and fires the corresponding PropertyChange
event propertyChange
and TableModel event TableChanged
.
- commit()
- Commits changes to the database.
- committed(DataEvent)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
committed
fires, and fires the corresponding DataAfter event
committed
.
- connect()
- Attempts to establish a connection to the database using the connection properties
specified in the connection alias.
- connected(DataEvent)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
connected
fires and fires the corresponding DataAfter event
connected
.
- deletedRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
deletedRow
fires, and fires the corresponding DataAfter event
deletedRow
.
- deleteRow()
- Deletes the current row from the result set and from the database.
- disconnect()
- Closes the JDBC connection for further use by this Select object.
- disconnected(DataEvent)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
disconnected
fires, and fires the corresponding DataAfter event
disconnected
.
- execute()
- Executes the SQL SELECT statement and positions to the first row in the result set.
- firstRow()
- Applies any changes in the current row to the database, and then positions to the
first row in the result set.
- getColumnClass(int)
- Returns the java class that is used for the values of the column.
- getColumnClass(String)
- Returns the java class that is used for the values of the column.
- getColumnCount()
- Returns the number of columns in the result set.
- getColumnIndex(String)
- Returns the index of the column based on its name.
- getColumnName(int)
- Returns the name of the specified column.
- getColumnValue(int)
- Returns the value of the column at the specified index in the current row.
- getColumnValue(String)
- Returns the value of the column with the specified name in the current row.
- getColumnValueToString(int)
- Returns the value of the column at the specified index in the current row as a
String.
- getColumnValueToString(String)
- Returns the value of the column with the specified name in the current row as a
String.
- getCurrentRow()
- Returns the index of the current row in the result set.
- getCurrentRowInCache()
- Returns the index in the cache of the current row in the result set.
- getInstanceBeanInfo()
- Returns the BeanInfo that contains information about the instance properties of
this Select.
- getMaximumPacketsInCache()
- Returns the maximum number of packets the cache can contain at one time.
- getMaximumRows()
- Returns the maximum size of the result set.
- getNumPacketsInCache()
- Returns the number of packets currently in the cache.
- getNumRows()
- Returns the number of rows in the result set.
- getNumRowsInCache()
- Returns the number of rows currently in the cache.
- getPacketSize()
- Returns the number of rows that are in one packet.
- getParameter(int)
- Returns the value of the parameter at the specified index.
- getParameter(String)
- Returns the value of the parameter with the specified name.
- getParameterToString(int)
- Returns the value of the parameter at the specified index as a String.
- getParameterToString(String)
- Returns the value of the parameter with the specified name as a String.
- getQuery()
- Returns a new Query object that contains references to the connection alias and
the SQL specification for this Select.
- getResult()
- Returns the underlying com.ibm.db.SelectResult.
- getRowCount()
- Returns the number of rows currently in the cache.
- getSelectStatement()
- Returns the underlying com.ibm.db.SelectStatement.
- getStatementMetaData()
- Returns the underlying com.ibm.db.StatementMetaData.
- getTimeout()
- Returns the number of seconds the JDBC driver will wait for this statement
to execute.
- getValueAt(int, int)
- Returns the value of the specified cell in the cache.
- isCellEditable(int, int)
- Returns true if
isReadOnly
returns false.
- isEnd()
- Returns true if the currentRow is the last row in the result set and no
more rows can be fetched.
- isExecuted()
- Returns true if
execute
has been invoked.
- 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.
- isMaxRowsReached()
- Returns true if the number of rows in the result set is equal to the
maximum size of the result set.
- isOpen()
- Returns true if the statement is open in the database and can be accessed,
otherwise returns false.
- isReadOnly()
- Returns true if updates are disallowed even when the database would permit them.
- lastRow()
- Applies any changes in the current row to the database, and then positions to the
last row in the result set.
- lockRow()
- Locks the current row in the database.
- newRow(boolean)
- Applies any changes in the current row to the database, inserts a new empty row
into the result set, and positions to the new row.
- nextPacket()
- Fetches the next packet from the database into the result set.
- nextRow()
- Applies any changes in the current row to the database, and then positions to the
next row in the result set.
- previousRow()
- Applies any changes in the current row to the database, and then positions to
the previous row in the result set.
- propertyChange(PropertyChangeEvent)
- Method to handle events for the PropertyChangeListener interface.
- refresh()
- Refreshes the result set from the database by re-executing the SQL SELECT statement.
- removeTableModelListener(TableModelListener)
- Removes a listener to the TableModel event set.
- restoreRow()
- Restores a row's column values to those last known to be in the database.
- rollback()
- Rollback changes in the database.
- rolledBack(DataEvent)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
rolledBack
fires, and fires the corresponding DataAfter event
rolledBack
.
- setColumnValue(int, Object)
- Sets (in the result set) the value of the column at the specified index in the
current row.
- setColumnValue(String, Object)
- Sets (in the result set) the value of the column with the specified name in the
current row.
- setColumnValueFromString(int, String)
- Sets (in the result set) the value of the column at the specified index in the
current row.
- setColumnValueFromString(String, String)
- Sets (in the result set) the value of the column with the specified name in the
current row.
- setCurrentRow(int)
- Applies any changes in the current row to the database, and then positions to
the specified row in the result set.
- setCurrentRowInCache(int)
- Makes the specified row in the cache the currentRow in the result set.
- setDatabaseConnection(DatabaseConnection)
- Associates a DatabaseConnection with the Select.
- 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.
- 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.
- setPacketSize(int)
- Sets the number of rows that are in one packet.
- setParameter(int, Object)
- Sets the parameter at the specified index to the specified value.
- setParameter(String, Object)
- Sets the parameter with the specified name to the specified value.
- setParameterFromString(int, String)
- Sets the parameter at the specified index to the specified value.
- setParameterFromString(String, String)
- Sets the parameter with the specified name to the specified value.
- setQuery(Query)
- Sets the connection alias and the SQL specification for this Select to the
values contained in the specified Query.
- setReadOnly(boolean)
- If true, updates are disallowed even when the database would permit them.
- setStatementMetaData(StatementMetaData)
- Associates a StatementMetaData with the Select.
- setTimeout(int)
- Sets the number of seconds the JDBC driver will wait for this statement
to execute.
- setValueAt(Object, int, int)
- Sets the specified cell in the cache to the specified value.
- unlockRow()
- Unlocks the current row.
- updatedRow(DataEvent)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
updatedRow
fires, and fires the corresponding DataAfter event
updatedRow
.
- updateRow()
- Updates the database with the values of the current row in the result set.
Constructors
Select
public Select()
- Constructs a new Select and initializes properties to the default values.
Methods
aboutToAddNewRow
public void aboutToAddNewRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToAddNewRow
fires, and fires the corresponding DataBefore event
aboutToAddNewRow
.
- Parameters:
- event - DataEvent
aboutToDeleteRow
public void aboutToDeleteRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToDelete
fires, and fires the corresponding DataBefore event
aboutToDelete
.
- Parameters:
- event - DataEvent
aboutToSetColumnValue
public void aboutToSetColumnValue(PropertyChangeEvent event)
- Invoked when the underlying com.ibm.db.StatementResultValueChange event
aboutToSetColumnValues
fires. No action is taken.
- Parameters:
- event - a java.beans.PropertyChangeEvent
aboutToUpdateRow
public void aboutToUpdateRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultBefore event
aboutToUpdateRow
fires, and fires the corresponding DataBefore event
aboutToUpdateRow
.
- Parameters:
- event - DataEvent
addedNewRow
public void addedNewRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
addedNewRow
fires, and fires the corresponding DataAfter event
addedNewRow
.
- Parameters:
- event - DataEvent
addTableModelListener
public void addTableModelListener(TableModelListener listener)
- Adds a listener to the TableModel event set.
- Parameters:
- listener - tableModleListener
- See Also:
- removeTableModelListener
areDistinctTypesEnabled
public boolean areDistinctTypesEnabled()
- Returns true if use of user-defined distinct types is enabled for this Select.
Returns false if use of user-defined distinct types is not enabled for this Select.
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
cacheRowsChanged
public void cacheRowsChanged(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
cacheRowsChanged
fires, and fires the corresponding DataAfter event
cacheRowsChanged
.
- Parameters:
- event - DataEvent
cancelAction
public void cancelAction() throws DataException
- Cancels execution of the SQL statement which is associated with
this Select. 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:
- cancelAction in class Statement
close
public void close() throws DataException
- Applies any changes in the current row 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 Select 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 Select 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
columnNames
public Enumeration columnNames() throws DataException
- Returns the names of the columns of the result set.
- Returns:
- enumeration containing column names
- Throws: DataException
- noStatement
- if there is no StatementMetaData associated with this Select
columnValueSet
public void columnValueSet(PropertyChangeEvent event)
- Invoked when the underlying com.ibm.db.StatementResultValueChange event
columnValueSet
fires, and fires the corresponding PropertyChange
event propertyChange
and TableModel event TableChanged
.
- Parameters:
- event - a java.beans.PropertyChangeEvent
commit
public void commit() throws DataException
- Commits changes to the database. All outstanding changes made to the database
using the connection associated with the connection alias are committed to the
database and any database locks currently held by the connection are released.
This method should only be used when auto commit has been turned off.
The events aboutToCommit
and committed
are triggered by
this method.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- sqlException
- if an SQL exception occurs
- See Also:
- setAutoCommit
- rollback
committed
public void committed(DataEvent event)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
committed
fires, and fires the corresponding DataAfter event
committed
.
- Parameters:
- event - DataEvent
- Overrides:
- committed in class Statement
connect
public void connect() throws DataException
- Attempts to establish a connection to the database using the connection properties
specified in the connection alias.
If a connection already exists for the specified connectionAlias, no new
connection is made and the existing connection is shared. If the value of
connectionAlias is null, a new connection is always established.
If the connectionPoolType property is POOL_TYPE_WEBSPHERE, the connection
is obtained from the WebSphere connection pools. If no connection pool
currently exists, a new connection pool with default settings is created based on
the specified URL. Then the connection is obtained from the new pool.
If the connectionPoolType property is POOL_TYPE_NONE, a new connection is obtained
directly from the JDBC DriverManager.
The events aboutToConnect
and connected
are triggered by
this method.
- Throws: DataException
- alreadyConnected
- if connection is already established
- Throws: DataException
- noGui
- if no GUI available and logon prompt requested
- Throws: DataException
- badUidPwd
- if incorrect Userid or password specified
- Throws: DataException
- noTransactions
- if database does not support transactions and autoCommit set to false
- Throws: DataException
- sqlException
- if an SQLException occurred
- Throws: DataException
- websphereConnectionError
- if an error occurred obtaining the connection from WebSphere
- See Also:
- disconnect
connected
public void connected(DataEvent event)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
connected
fires and fires the corresponding DataAfter event
connected
.
- Parameters:
- event - DataEvent
- Overrides:
- connected in class Statement
deletedRow
public void deletedRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
deletedRow
fires, and fires the corresponding DataAfter event
deletedRow
.
- Parameters:
- event - DataEvent
deleteRow
public void deleteRow() throws DataException
- Deletes the current row from the result set and from the database. (If the current row
is a new one that has not yet been inserted into the database, it is just removed from
the result set.)
When you delete any row except the last in the result set, you are positioned to the
next row, and the index returned by the
getCurrentRow
method does not change.
When you delete the last row, you are positioned to the previous row,
and the index returned by the getCurrentRow
method decreases by 1.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
We generate and execute the SQL necessary to delete the current row from the database.
To insure that your delete affects the intended row in the database, make sure that
the query used to produce the result set includes columns that uniquely identify
a row. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table from which the row is to be deleted.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
If no row can be found in the database exactly matching the current row, an exception
is thrown. Failure to find a matching row may occur if the row was changed in the
database by means other than this Select after being fetched.
If more than one row is found in the database, no exception is thrown. The number of
rows deleted depends on whether we perform a positioned or searched delete.
Whenever possible, we perform a positioned delete, which deletes the first matching
row. Otherwise, we perform a searched delete, which deletes all matching rows and
logs a message. You can avoid having multiple matching rows by including enough columns
in the result set to uniquely identify a row.
For more information on when we perform positioned or searched deletes, see the
setForceSearchedUpdate()
method.
The events aboutToDeleteRow
, deletedRow
, and
propertyChange
(for the currentRow and the currentRowInCache properties)
are triggered by this method.
The event cacheRowsChanged
may also be triggered.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be deleted because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- isLockRows
- setForceSearchedUpdate
disconnect
public void disconnect() throws DataException
- Closes the JDBC connection for further use by this Select object. A disconnect
may or may not be performed on the JDBC connection itself depending on whether the
JDBC connection was obtained from a WebSphere connection pool, whether it is externally
managed, and if neither of the former applies, whether it is being shared by another
object using the same connection alias.
If the connection is externally managed or is being shared by another
object, the association between the JDBC connection and this object
is removed, but the JDBC connection itself is not closed.
If the connection was obtained from a Webshpere connection pool and is not
externally managed, the JDBC connection is simply released back to the connection pool.
If the connection is not externally managed, is not from a Webshpere connection pool,
and is not being shared with another Select object, the JDBC connection is
closed, releasing the JDBC resources associated with the connection.
The events aboutToDisconnect
and disconnected
are triggered by
this method.
- Throws: DataException
- noActiveConnection
- if no active Connection
- Throws: DataException
- notRegistered
- if connection alias not registered as in use
- Throws: DataException
- sqlException
- if an SQLException occurred
- Throws: DataException
- websphereConnectionError
- if an error occurred releasing the connection to WebSphere
- See Also:
- connect
disconnected
public void disconnected(DataEvent event)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
disconnected
fires, and fires the corresponding DataAfter event
disconnected
.
- Parameters:
- event - DataEvent
- Overrides:
- disconnected in class Statement
execute
public 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.
The events aboutToExecute
and executed
are
triggered by this method.
The event cacheRowsChanged
is triggered
by this method.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache.
- Throws: DataException
- noGui
- if no GUI available and logon prompt requested
- Throws: DataException
- badUidPwd
- if incorrect Userid or password specified
- Throws: DataException
- noSQL
- if 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
firstRow
public void firstRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
first row in the result set.
If the first row in the result set has been displaced from the cache, you are
positioned to the first row still in the cache, and an exception is thrown to
indicate that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
getColumnClass
public Class getColumnClass(int columnIndex)
- Returns the java class that is used for the values of the column. If the columns have been
defined by
addColumn
, this method returns the java class used in the definition.
If the columns have not been defined by addColumn
, the java class is not available
until after the SQL statement has been executed. The index of the first column is 0.
- Parameters:
- columnNumber - the index of the column
- Returns:
- the java class for the column
- Throws: IndexOutOfBoundsException
- if the column index is not defined
getColumnClass
public Class getColumnClass(String columnName)
- Returns the java class that is used for the values of the column. If the columns have been
defined by
addColumn
, this method returns the java class used in the definition.
If the columns have not been defined by addColumn
, the java class is not available
until after the SQL statement has been executed.
- Parameters:
- columnName - the name of the column
- Returns:
- the java class for the column
- Throws: IndexOutOfBoundsException
- if the column name is not defined
getColumnCount
public int getColumnCount()
- Returns the number of columns in the result set. If the columns have been
defined by
addColumn
, this method returns the number of columns that have
currently been defined. If the columns have not been defined by addColumn
, the number
of columns is not available until after the SQL statement has been executed.
- Returns:
- the number of columns
getColumnIndex
public int getColumnIndex(String columnName)
- Returns the index of the column based on its name. If the columns have been
defined by
addColumn
, this method returns an index representing the order
that the columns were defined. If the columns have not been defined by addColumn
,
the column index is not available until after the SQL statement has been executed. The first
defined column has an index of 0.
- Parameters:
- columnName - the name of the column
- Returns:
- the column index
getColumnName
public String getColumnName(int columnIndex)
- Returns the name of the specified column. If the columns have not been defined by
addColumn
, the name is not available until after the SQL statement has been executed.
The index of the first column is 0.
- Parameters:
- columnNumber - the index of the column
- Returns:
- the column name
- Throws: IndexOutOfBoundsException
- if the column index is not defined
getColumnValue
public Object getColumnValue(int columnNumber)
- Returns the value of the column at the specified index in the current row.
The index of the first column is 0.
If the statement has not been executed, a null value is returned.
If a DataException is raised attempting to get the column value because
the result set is empty, the error is logged and a null value is returned.
- Parameters:
- columnNumber - index of the column
- Returns:
- value of the column
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- See Also:
- setColumnValue
getColumnValue
public Object getColumnValue(String columnName)
- Returns the value of the column with the specified name in the current row.
If the statement has not been executed, a null value is returned.
If a DataException is raised attempting to get the column value because
the result set is empty, the error is logged and a null value is returned.
- Parameters:
- columnName - name of the column
- Returns:
- value of the column
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- See Also:
- setColumnValue
getColumnValueToString
public String getColumnValueToString(int columnNumber)
- Returns the value of the column at the specified index in the current row as a
String. The value of the column is converted to a String before it is returned.
If the column value is null, a null is returned.
The index of the first column is 0.
If the statement has not been executed, a null value is returned.
If a DataException is raised attempting to get the column value because
the result set is empty, the error is logged and a null value is returned.
- Parameters:
- columnNumber - index of the column
- Returns:
- value of the column as a String.
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- See Also:
- setColumnValueFromString
getColumnValueToString
public String getColumnValueToString(String columnName)
- Returns the value of the column with the specified name in the current row as a
String. The value of the column is converted to a String before it is returned.
If the column value is null, a null is returned.
If the statement has not been executed, a null value is returned.
If a DataException is raised attempting to get the column value because
the result set is empty, the error is logged and a null value is returned.
- Parameters:
- columnName - name of the column
- Returns:
- value of the column as a String.
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- See Also:
- setColumnValueFromString
getCurrentRow
public int getCurrentRow()
- Returns the index of the current row in the result set.
The index of the first row is 0.
If there are no result sets, a value of -1 is returned.
Many methods on Select operate on the current row.
- Returns:
- index of the current row
- See Also:
- setCurrentRow
getCurrentRowInCache
public int getCurrentRowInCache()
- Returns the index in the cache of the current row in the result set.
The index of the first row in the cache is 0. If there are no result sets, a value
of -1 is returned.
The values of currentRowInCache and currentRow will be the same unless you have
set maximumPacketsInCache to a value other than 0 and a packet has been displaced
from the cache.
For example, if a packet of 10 rows has been displaced from the cache and the
currentRow is 10, the currentRowInCache would be 0.
- Returns:
- index of the current row
getInstanceBeanInfo
public BeanInfo getInstanceBeanInfo()
- Returns the BeanInfo that contains information about the instance properties of
this Select. This method is called by the VisualAge for Java IDE to display
the parameters and columns from the associated SQL statement on the connection dialog.
- Returns:
- beanInfo of instance properties
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
getNumPacketsInCache
public int getNumPacketsInCache()
- Returns the number of packets currently in the cache.
- Returns:
- the number of packets in the cache
getNumRows
public int getNumRows()
- Returns the number of rows in the result set. This number changes as rows are
fetched from the database, deleted, or added via the
newRow
method.
- Returns:
- number of rows in the result set
- See Also:
- getRowCount
- getNumRowsInCache
getNumRowsInCache
public int getNumRowsInCache()
- Returns the number of rows currently in the cache.
To obtain the number of rows in the entire result set, not just rows in the cache,
use
getNumRows
.
Another method that returns the number of rows currently in the cache is
getRowCount
. That method is required to implement the TableModel interface.
- Returns:
- the number of rows in cache
- See Also:
- getRowCount
- getNumRows
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
getParameter
public Object getParameter(int parameterNumber) throws DataException
- Returns the value of the parameter at the specified index.
If the parameter value is null, a null is returned.
The index of the first parameter is 1.
- Parameters:
- parameterNumber - index of the parameter
- Returns:
- the parameter value
- Throws: IndexOutOfBoundsException
- if the parameter index is not
defined
- Throws: DataException
- sqlException
- if an SQL Exception is raised (only thrown by ProcedureCall)
- Overrides:
- getParameter in class Statement
- See Also:
- getParameterToString
- setParameter
getParameter
public Object getParameter(String parameterName) throws DataException
- Returns the value of the parameter with the specified name.
If the parameter value is null, a null is returned.
- Parameters:
- parameterName - name of the parameter
- Returns:
- the parameter value
- Throws: IndexOutOfBoundsException
- if the parameter name is not
defined
- Throws: DataException
- sqlException
- if an SQL Exception is raised (only thrown by ProcedureCall)
- Overrides:
- getParameter in class Statement
- See Also:
- getParameterToString
- setParameter
getParameterToString
public String getParameterToString(int parameterNumber) throws DataException
- Returns the value of the parameter at the specified index as a String. The value
of the parameter is converted to a String before the value is returned. If the
parameter value is null, a null is returned.
The index of the first parameter is 1.
- Parameters:
- parameterNumber - index of the parameter
- Returns:
- value of the parameter as a String
- Throws: IndexOutOfBoundsException
- if the parameter index is not
defined
- Throws: DataException
- sqlException
- if an SQL Exception is raised (only thrown by ProcedureCall)
- Overrides:
- getParameterToString in class Statement
- See Also:
- getParameter
- setParameterFromString
getParameterToString
public String getParameterToString(String parameterName) throws DataException
- Returns the value of the parameter with the specified name as a String. The value
of the parameter is converted to a String before the value is returned. If the
parameter value is null, a null is returned.
- Parameters:
- parameterName - name of the parameter
- Returns:
- value of the parameter as a String
- Throws: IndexOutOfBoundsException
- if the parameter name is not
defined
- Throws: DataException
- sqlException
- if an SQL Exception is raised (only thrown by ProcedureCall)
- Overrides:
- getParameterToString in class Statement
- See Also:
- getParameter
- setParameterFromString
getQuery
public Query getQuery()
- Returns a new Query object that contains references to the connection alias and
the SQL specification for this Select.
- Returns:
- a new Query
- See Also:
- setQuery
getResult
public SelectResult getResult()
- Returns the underlying com.ibm.db.SelectResult.
- Returns:
- the associated SelectResult
getRowCount
public int getRowCount()
- Returns the number of rows currently in the cache.
This method is part of the TableModel interface. To obtain the number of rows
in the entire result set, not just rows in the cache, use getNumRows
.
Another method that returns the number of rows currently in the cache is
getNumRowInCache
.
- Returns:
- the number of rows in the cache
- See Also:
- getNumRows
- getNumRowsInCache
getSelectStatement
public SelectStatement getSelectStatement()
- Returns the underlying com.ibm.db.SelectStatement.
- Returns:
- the associated SelectStatement.
getStatementMetaData
public StatementMetaData getStatementMetaData()
- Returns the underlying com.ibm.db.StatementMetaData.
- Returns:
- the associated StatementMetaData
- Overrides:
- getStatementMetaData in class Statement
- See Also:
- setStatementMetaData
getTimeout
public int getTimeout()
- Returns the number of seconds the JDBC driver will wait for this statement
to execute. If the limit is exceeded, a DataException is thrown by the
execute method.
- Returns:
- the timeout limit in seconds; zero means unlimited
- Overrides:
- getTimeout in class Statement
- See Also:
- setTimeout
getValueAt
public Object getValueAt(int rowIndex,
int columnIndex)
- Returns the value of the specified cell in the cache. The index of both the
first row and the first column is 0.
If a DataException is raised attempting to get the cell value because the
result set is empty, a null value is returned.
If this method is called before the SQL statement has been executed, a null
is
returned.
- Returns:
- the value of the specified cell
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Throws: IndexOutOfBoundsException
- noSuchRow
- if the row index is not defined
isCellEditable
public boolean isCellEditable(int rowIndex,
int columnIndex)
- Returns true if
isReadOnly
returns false. If the
SQL statement returns a result set that cannot be updated, you should explicitly
set the ReadOnly property to true, so that the correct value is returned
for this method.
- Returns:
- true if
isReadOnly
returns false.
- See Also:
- setReadOnly
isEnd
public boolean isEnd()
- Returns true if the currentRow is the last row in the result set and no
more rows can be fetched. No more rows can be fetched if any of the following
conditions is true: all rows have been fetched from the database, the maxRows
limit has been reached, or the result set has been closed.
- Returns:
- true if the currentRow is the last row in the result set and no
more rows can be fetched
- See Also:
- isOpen
- isMaxRowsReached
isExecuted
public boolean isExecuted()
- Returns true if
execute
has been invoked.
- Returns:
- true if
execute
has been invoked.
otherwise false.
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
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. Returns false
if a database lock is only held on a row while it is being updated in the
database.
See lockRow
for a fuller
discussion of what it means for a row to be locked.
- Returns:
- The lockRows property value.
- See Also:
- setLockRows
- lockRow
isMaxRowsReached
public boolean isMaxRowsReached()
- Returns true if the number of rows in the result set is equal to the
maximum size of the result set.
- Returns:
- true if the number of rows in the result set is equal to the
maximum size of the result set, otherwise false.
- See Also:
- setMaximumRows
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 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.
isReadOnly
public boolean isReadOnly()
- Returns true if updates are disallowed even when the database would permit them.
Returns false if updates are allowed as long as the database will permit them.
- Returns:
- true if updates are disallowed, otherwise false.
- See Also:
- setReadOnly
lastRow
public void lastRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
last row in the result set. If more rows can be fetched from the database they
are fetched before positioning to the last row. For a discussion of when more
rows can be fetched, see the
isEnd
method.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property of the associated SelectStatement is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
lockRow
public void lockRow() throws DataException
- Locks the current row in the database.
No updates can be made to this row using another connection until the lock is released.
The lock is automatically released when you move to another row. You can release
the lock without moving to another row by invoking the
unlockRow
method.
To implement this method, we generate and execute an SQL query that opens a database
cursor locking the row.
If no row can be found in the database exactly matching the current row, an exception
is thrown. Failure to find a matching row may occur if the row was changed in the
database by means other than this Select after being fetched.
If more than one row is found in the database, no exception is thrown.
All matching rows are locked.
To insure that only the intended row is locked, make sure that
the query used to produce the result set includes columns that uniquely identify
a row. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table in which the row is to be locked.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- rowNotFound
- if the current row cannot be locked because it cannot be found in the database
- Throws: DataException
- rowNotInDatabase
- if the current row cannot be locked in the database because it has not
yet been written to the database
- Throws: DataException
- lockNotSupported
- if the current row cannot be locked because the database does not have
function required to do so
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- unlockRow
- setLockRows
newRow
public void newRow(boolean beforeCurrent) throws DataException
- Applies any changes in the current row to the database, inserts a new empty row
into the result set, and positions to the new row.
Use the
setColumnValue
method to set values for its columns.
The new row is not inserted into the database until you set values and move to
another row or invoke the updateRow
method.
If you move to another row without setting any values in the new row, the new row
remains in the result set, but has not yet been inserted into the database. You can
return to it later, set values, and insert it into the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
The events aboutToAddNewRow
, addedNewRow
, and
cacheRowsChanged
are triggered by this method.
- Parameters:
- beforeCurrent - true, insert the new row before the current row;
false insert the new row after the current row.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- maxSize
- if the maximum number of rows in the result set has been reached
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
nextPacket
public void nextPacket() throws DataException
- Fetches the next packet from the database into the result set. If this causes
the current row to be displaced from the cache any changes in the current row
are first applied to the database, and then you are positioned to the first row
in the cache.
The event cacheRowsChanged
is triggered by this method.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- notOpen
- if the result set is not open
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
nextRow
public void nextRow() throws DataException
- Applies any changes in the current row to the database, and then positions to the
next row in the result set.
If the next row has not already been fetched from the database, it is fetched, along
with any other rows in the next packet. If no more rows can be fetched, your
position does not change, and no exception is thrown.
Thus, if you are at the end of the result set, repeatedly invoking this method has
no effect. For a discussion of when no more rows can be fetched, see the
isEnd
method.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
The event cacheRowsChanged
may be triggered by this method.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
previousRow
public void previousRow() throws DataException
- Applies any changes in the current row to the database, and then positions to
the previous row in the result set.
If you are already on the first row, your position does not change, and no exception
is thrown. Thus, if you are at the beginning of the result set, repeatedly invoking
this method has no effect.
If the previous row has been displaced from the cache, your position does not change,
and an exception is thrown to indicate that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
propertyChange
public void propertyChange(PropertyChangeEvent arg1)
- Method to handle events for the PropertyChangeListener interface.
- Parameters:
- arg1 - java.beans.PropertyChangeEvent
refresh
public 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
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
removeTableModelListener
public void removeTableModelListener(TableModelListener listener)
- Removes a listener to the TableModel event set.
- Parameters:
- listener - tableModleListener
- See Also:
- addTableModelListener
restoreRow
public void restoreRow() throws DataException
- Restores a row's column values to those last known to be in the database.
Use this method when an attempt to lock a row, insert or update a row in the database,
or delete a row from the database has failed. This can occur implicitly when
you try to move to another row. When one of these failures has occurred,
you cannot move to another row until you either correct the problem or
use this method.
If the current row was added via the newRow
method, and you
have not yet inserted it into the database, its column values are reset
to nulls. Otherwise, the current row's column values are reset
to the values originally fetched from the database or the values to
which it was last successfully updated.
If you believe the failure that occurred is correctable by changing one
or more of column values, as for example if the failure was due to
a duplicate key value in the database, you can just change the values
and try the operation again instead of using this method.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- readOnly
- if the result set is read only
rollback
public void rollback() throws DataException
- Rollback changes in the database. All changes made since the previous
commit/rollback are rolled back and any database locks currently held
by the connection are released. This method should only be used when auto
commit has been turned off.
The events aboutToRollback
and rolledBack
are triggered by
this method.
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- sqlException
- if an SQL exception occurs
- See Also:
- commit
- setAutoCommit
rolledBack
public void rolledBack(DataEvent event)
- Invoked when the underlying com.ibm.db.DatabaseConnectionAfter event
rolledBack
fires, and fires the corresponding DataAfter event
rolledBack
.
- Parameters:
- event - DataEvent
- Overrides:
- rolledBack in class Statement
setColumnValue
public void setColumnValue(int columnNumber,
Object aValue) throws DataException
- Sets (in the result set) the value of the column at the specified index in the
current row. To set a column value to null, pass null as the value.
The index of the first column is 0.
The column value is not updated in the database until you move to another row,
call the updateRow
method, or close the result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnNumber - index of the column
- aValue - value for the column
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- See Also:
- setColumnValueFromString
- getColumnValue
setColumnValue
public void setColumnValue(String columnName,
Object aValue) throws DataException
- Sets (in the result set) the value of the column with the specified name in the
current row. To set a column value to null, pass null as the value.
The column value is not updated in the database until you move to another row,
call the updateRow
method, or close the result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnName - name of the column
- aValue - value for the column
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- See Also:
- setColumnValueFromString
- getColumnValue
setColumnValueFromString
public void setColumnValueFromString(int columnNumber,
String stringValue) throws DataException
- Sets (in the result set) the value of the column at the specified index in the
current row. The index of the first column is 0. If the Select has not been executed
and the specified stringValue is null or has zero length, the method returns without setting
the column value.
The stringValue parameter is converted to the datatype associated
with the column before the value is set.
To set a column value to null, pass null as the value.
If the datatype is not String, you can also set a column value to null
by passing a zero-length String as the value.
The column value is not updated in the database until you move to another row,
call the updateRow
method, or close the result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnNumber - index of the column
- stringValue - value for the column
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column index is not defined
- Throws: DataException
- cannotConvert
- if cannot convert to object type of column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- See Also:
- setColumnValue
- getColumnValueToString
setColumnValueFromString
public void setColumnValueFromString(String columnName,
String stringValue) throws DataException
- Sets (in the result set) the value of the column with the specified name in the
current row. The index of the first column is 0. If the Select has not been executed
and the specified stringValue is null or has zero length, the method returns without setting
the column value.
The stringValue parameter is converted to the datatype associated
with the column before the value is set.
To set a column value to null, pass null as the value.
If the datatype is not String, you can also set a column value to null
by passing a zero-length String as the value.
The column value is not updated in the database until you move to another row,
call the updateRow
method, or close the result set.
The events aboutToSetColumnValue
and columnValueSet
are
triggered by this method.
- Parameters:
- columnName - name of the column
- stringValue - value for the column
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- noResults
- if the result set is empty
- Throws: IndexOutOfBoundsException
- noSuchColumn
- if the column name is not defined
- Throws: DataException
- cannotConvert
- if cannot convert to object type of column
- Throws: DataException
- truncated
- if data truncation occurred on retrieval.
- See Also:
- setColumnValue
- getColumnValueToString
setCurrentRow
public void setCurrentRow(int rowNumber) throws DataException
- Applies any changes in the current row to the database, and then positions to
the specified row in the result set. The index of the first row is 0.
If the specified row has not yet been fetched, packets are fetched until the
specified row is in the cache or no more rows can be fetched.
If no more rows can be fetched, and the specified row was not reached, you are
positioned to the last row, and an exception is thrown to indicate
that the request could not be satisfied. For a discussion of when no more
rows can be fetched, see the isEnd
method.
If the specified row has been displaced from the cache, you are positioned to
the first row in the cache, and an exception is thrown to indicate
that the request could not be satisfied.
If the current row should be locked ( isLockRows
returns true),
the new current row is locked in the database.
The event propertyChange
is triggered by this method for the
bound properties currentRow and currentRowInCache as well as for the
generated bound properties for each result column.
The event cacheRowsChanged
may be triggered by this method.
- Parameters:
- rowNumber - index in the result set of the row
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated because it cannot be found in the database
- Throws: DataException
- rowNotFound
- if the lockRows property is true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- indexTooLarge
- if the requested row is after the end of the result set
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- getCurrentRow
setCurrentRowInCache
public void setCurrentRowInCache(int row) throws DataException
- Makes the specified row in the cache the currentRow in the result set.
The index of the first row is 0.
The values of currentRowInCache and currentRow will be the same unless you have
set maximumPacketsInCache to a value other than 0 and a packet has been displaced
from the cache.
For example, if a packet of 10 rows has been displaced from the cache and the
currentRow is 10, the currentRowInCache would be 0.
- Parameters:
- row - the index of the row in the cache
- Throws: DataException
- notExecuted
- if statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- rowChanged
- if the current row cannot be updated in the database because it has been
modified by another user since it was fetched
- Throws: DataException
- rowNotFound
- if the lockRows property true and
the new current row cannot be locked
- Throws: DataException
- beforeCacheStart
- if the requested row is before the start of the cache
- Throws: DataException
- indexTooLarge
- if the requested row is after the end of the result set
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- setCurrentRow
setDatabaseConnection
public void setDatabaseConnection(DatabaseConnection connection)
- Associates a DatabaseConnection with the Select.
- Parameters:
- connection - the associated DatabaseConnection
- Overrides:
- setDatabaseConnection in class Statement
- See Also:
- getDatabaseConnection
setDistinctTypesEnabled
public void setDistinctTypesEnabled(boolean enabled)
- 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 Select, the value defaults to false.
When use of user-defined distinct types is not enabled for a statement, 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:
- enabled - 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 fillCache)
- 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 Select, 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 for the implications of doing
positioned versus searched updates and deletes.
If you do not execute this method for a Select, 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. 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 Select, the value defaults to false.
See the lockRow
method 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 Select, 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 Select, the value defaults to 0.
- Parameters:
- maximumRows - the maximum number of rows in the result set
- See Also:
- getMaximumRows
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 Select, 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
setParameter
public void setParameter(int parameterNumber,
Object aValue) throws DataException
- Sets the parameter at the specified index to the specified value.
To set a parameter value to null, pass null as the value.
The index of the first parameter is 1.
- Parameters:
- parameterNumber - index of the parameter
- aValue - parameter value
- Throws: IndexOutOfBoundsException
- if the parameter index is not
defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the parameter
- Overrides:
- setParameter in class Statement
- See Also:
- setParameterFromString
- getParameter
setParameter
public void setParameter(String parameterName,
Object aValue) throws DataException
- Sets the parameter with the specified name to the specified value.
To set a parameter value to null, pass null as the value.
- Parameters:
- parameterName - name of the parameter
- aValue - parameter value
- Throws: IndexOutOfBoundsException
- if the parameter name is not
defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the parameter
- Overrides:
- setParameter in class Statement
- See Also:
- setParameterFromString
- getParameter
setParameterFromString
public void setParameterFromString(int parameterNumber,
String stringValue) throws DataException
- Sets the parameter at the specified index to the specified value.
The index of the first parameter is 1.
The stringValue is converted to the datatype associated with the parameter before the
parameter is updated.
To set a parameter value to null, pass null as the value.
If the datatype is not String, you can also set a parameter value to null
by passing a zero-length String as the value.
- Parameters:
- parameterNumber - index of the parameter
- stringValue - parameter value as a String
- Throws: IndexOutOfBoundsException
- if the parameter index is not
defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the parameter
- Overrides:
- setParameterFromString in class Statement
- See Also:
- setParameter
- getParameterToString
setParameterFromString
public void setParameterFromString(String parameterName,
String stringValue) throws DataException
- Sets the parameter with the specified name to the specified value.
The stringValue is converted to the datatype associated with the parameter before the
parameter is updated.
To set a parameter value to null, pass null as the value.
If the datatype is not String, you can also set a parameter value to null
by passing a zero-length String as the value.
- Parameters:
- parameterName - name of the parameter
- stringValue - parameter value as a String
- Throws: IndexOutOfBoundsException
- if the parameter name is not
defined
- Throws: DataException
- wrongObjectType
- if the value does not match the object type of the parameter
- Overrides:
- setParameterFromString in class Statement
- See Also:
- setParameter
- getParameterToString
setQuery
public void setQuery(Query query)
- Sets the connection alias and the SQL specification for this Select to the
values contained in the specified Query. The Query itself is not saved.
- Parameters:
- query - the Query
- See Also:
- getQuery
setReadOnly
public void setReadOnly(boolean readOnly)
- If true, updates are disallowed even when the database would permit them.
If false, updates are allowed as long as the database will permit them.
The default value is false.
- Parameters:
- readOnly - true if updates are disallowed;
false if updates are allowed.
- See Also:
- isReadOnly
setStatementMetaData
public void setStatementMetaData(StatementMetaData metaData)
- Associates a StatementMetaData with the Select.
- Parameters:
- metaData - the associated StatementMetaData
- Overrides:
- setStatementMetaData in class Statement
- See Also:
- getStatementMetaData
setTimeout
public void setTimeout(int seconds)
- Sets the number of seconds the JDBC driver will wait for this statement
to execute. If the limit is exceeded, a DataException is thrown by the
execute method.
- Parameters:
- seconds - the new timeout limit in seconds; zero means unlimited
- Overrides:
- setTimeout in class Statement
- See Also:
- getTimeout
setValueAt
public void setValueAt(Object aValue,
int rowIndex,
int columnIndex)
- Sets the specified cell in the cache to the specified value. The index of both the
first row and the first column is 0.
If a String value is supplied, the value will be automatically converted to the
correct datatype for the cell.
If the specified row was not already the current row, first applies any changes in the
current row to the database, and then makes the specified row the current row.
The cell value is not updated in the
database until you move to another row or invoke updateRow
.
- Throws: DataRuntimeException
- if a DataException is raised. A runtime exception is thrown since the
setValueAt() method cannot throw an exception and be considered part of the
implementation of the TableModel Interface.
unlockRow
public void unlockRow() throws DataException
- Unlocks the current row. The database lock on the current row is released.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- Throws: DataException
- sqlException
- if an SQLException occurred
- See Also:
- lockRow
updatedRow
public void updatedRow(DataEvent event)
- Invoked when the underlying com.ibm.db.StatementResultAfter event
updatedRow
fires, and fires the corresponding DataAfter event
updatedRow
.
- Parameters:
- event - DataEvent
updateRow
public void updateRow() throws DataException
- Updates the database with the values of the current row in the result set. If the
current row is a new row, it is inserted into the database. If it is an existing
row, it is updated in the database.
We generate and execute the SQL necessary to update the current row in the database.
To insure that your update affects the intended row in the database, make sure that
the query used to produce the result set includes columns that uniquely identify
a row. Also make sure to use the addTable()
method of the associated
StatementMetaData object to identify the table in which the row is to be updated.
Otherwise we will attempt to parse your query for this information, with no guarantee
of success.
If no row can be found in the database exactly matching the current row, an exception
is thrown. Failure to find a matching row may occur if the row was changed in the
database by means other than this Select after being fetched.
If more than one row is found in the database, no exception is thrown. The number of
rows updated depends on whether we perform a positioned or searched update.
Whenever possible, we perform a positioned update, which updates the first matching
row. Otherwise, we perform a searched update, which updates all matching rows and
logs a message. You can avoid having multiple matching rows by including enough columns
in the result set to uniquely identify a row.
For more information on when we perform positioned or searched updates, see the
setForceSearchedUpdate
method.
The events aboutToUpdateRow
and updatedRow
are
triggered by this method.
- Throws: DataException
- notExecuted
- if the statement has not been executed
- Throws: DataException
- noResults
- if the result set is empty
- Throws: DataException
- noActiveConnection
- if no active connection exists
- Throws: DataException
- readOnly
- if the result set is read only
- 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
