com.ibm.db.beans
Class DBProcedureCall

java.lang.Object
  |
  +--com.ibm.db.beans.DBStatement
        |
        +--com.ibm.db.beans.DBSelect
              |
              +--com.ibm.db.beans.DBProcedureCall
All Implemented Interfaces:
java.io.Serializable

public class DBProcedureCall
extends DBSelect

This class allows you to call a stored procedure and use any parameters or result sets it returns in a bean which exposes JDBC 2.0 RowSet functionality and adds its own useful functions for managing stored procedure results.

The JDBC RowSet "wraps" a connection, a statement, and a result set as a bean, and provides properties, methods, and events for using them. It does not currently define interfaces for getting output parameters or multiple result sets from stored procedures. That function is added by this bean.

The bean does not currently support getting stored procedure results which are update counts. Only stored procedure results which are result sets are supported.

This bean also has function (some of it inherited from DBSelect) to help with managing large result sets and to make it easy to use the bean in a graphical user interface. For example, it can fire PropertyChange events for dynamically generated bound "properties" corresponding to the parameters of the stored procedure. You can also connect this bean to the utility bean DBTableModel, which adapts it for use as the model of a javax.swing.JTable.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class com.ibm.db.beans.DBSelect
DEFER_NOTHING, DEFER_WRITE_TO_DATABASE, DEFER_WRITE_TO_DATABASE_AND_ROW_NUMBER_CHANGE, FETCH_FORWARD, FETCH_REVERSE
 
Fields inherited from class com.ibm.db.beans.DBStatement
LEVEL_CONNECTION, LEVEL_RESULTSET, LEVEL_STATEMENT, TRANSACTION_DEFAULT
 
Constructor Summary
DBProcedureCall()
          Default constructor for a DBProcedureCall bean.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a listener to the PropertyChange event set.
 void clearMetaData()
          Clears the descriptions of all result sets for this DBProcedureCall.
 com.ibm.db.beans.DBSelectMetaData createMetaData(int position)
          Creates a new DBSelectMetaData object to describe the specified result set.
 int findColumn(java.lang.String columnName)
          Maps the given column label to its column index.
 boolean firstResult()
          Applies any changes in the current row of the current result set to the database, and then positions to the first result set.
 com.ibm.db.beans.DBSelectMetaData getMetaData(int position)
          Gets the meta data describing the result set at the specified position.
 java.lang.Object getParameter(int position)
          Gets the value of the parameter at the specified position.
 int getResult()
          Gets the number of the result set to which you are currently positioned.
 int getResultCount()
          Gets the number of result sets.
 boolean hasResult()
          Returns true if the store procedure returns at least one result set; returns false otherwise.
 boolean isFetchAllResultsOnExecute()
          Returns true if all result sets produced by this procedure call will be obtained immediately during the execute method.
 boolean isLastResult()
          Returns true if the current result set is the last one fetched and either there are known to be no more result sets or the statement has been closed.
 boolean isOpen()
          Returns true if the underlying RowSet is open, otherwise returns false.
 boolean lastResult()
          Applies any changes in the current row of the current result set to the database, and then positions to the last result set.
 boolean nextResult()
          Applies any changes in the current row of the current result set to the database, and then positions to the next result set.
 boolean previousResult()
          Applies any changes in the current row of the current result set to the database, and then positions to the previous result set.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a listener to the PropertyChange event set.
 void setFetchAllResultsOnExecute(boolean fetchAll)
          If true, all result sets produced by this procedure call will be obtained immediately during the execute method.
 boolean setResult(int resultNumber)
          Applies any changes in the current row of the current result set to the database, and then positions to the specified result set.
 
Methods inherited from class com.ibm.db.beans.DBSelect
addDBAfterListener, addDBBeforeListener, applyUpdates, areDistinctTypesEnabled, cancelRowUpdates, cancelUpdates, close, close, deleteRow, execute, execute, fetchMoreRows, fetchMoreRows, first, getCacheLimit, getCacheRowCount, getCacheValueAt, getColumn, getColumn, getColumnAsString, getColumnAsString, getColumnCount, getColumnName, getFetchSize, getMaxFieldSize, getMaxRows, getMetaData, getRow, getRowCount, getRowInCache, getScrollType, getUpdateDeferral, hasMoreRows, hasMoreRows, isCompareLargeColumns, isFirst, isLast, isLockRows, isOpen, isReadOnly, isValidateLOBs, last, lockRow, newRow, next, onRow, previous, reExecute, refreshRow, removeDBAfterListener, removeDBBeforeListener, setCacheLimit, setCacheValueAt, setColumn, setColumn, setColumnFromString, setColumnFromString, setCompareLargeColumns, setDistinctTypesEnabled, setFetchSize, setLockRows, setMaxFieldSize, setMaxRows, setReadOnly, setRow, setRowInCache, setScrollType, setUpdateDeferral, setValidateLOBs, unlockRow, updateRow
 
Methods inherited from class com.ibm.db.beans.DBStatement
cancelAction, clearParameters, commit, findParameter, getAutoCommit, getCommand, getConnection, getConnectionSpec, getDataSourceName, getDriverName, getInitialContextFactory, getJspNullToken, getLogWriter, getParameter, getParameterAsString, getParameterAsString, getParameterCount, getParameterMetaData, getParameterName, getPassword, getProviderUrl, getQueryTimeout, getTrace, getTransactionIsolation, getUrl, getUsername, isExecuted, isOptimizeConvertToString, isOptimizeForJsp, isOptimizeForNoListeners, rollback, setAutoCommit, setCommand, setConnection, setConnectionSpec, setDataSourceName, setDriverName, setInitialContextFactory, setJspNullToken, setLogWriter, setOptimizeConvertToString, setOptimizeForJsp, setOptimizeForNoListeners, setParameter, setParameter, setParameterFromString, setParameterFromString, setPassword, setProviderUrl, setQueryTimeout, setTrace, setTransactionIsolation, setUrl, setUsername, shareConnectionWith
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DBProcedureCall

public DBProcedureCall()
Default constructor for a DBProcedureCall bean. This constructor also creates associated bean of type DBParameterMetaData.

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a listener to the PropertyChange event set.

Overrides:
addPropertyChangeListener in class DBSelect
Parameters:
listener - PropertyChangeListener
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener)

clearMetaData

public void clearMetaData()
                   throws java.sql.SQLException
Clears the descriptions of all result sets for this DBProcedureCall.

java.sql.SQLException
See Also:
createMetaData(int)

createMetaData

public com.ibm.db.beans.DBSelectMetaData createMetaData(int position)
                                                 throws DBException,
                                                        java.sql.SQLException
Creates a new DBSelectMetaData object to describe the specified result set. The index of the first result set is 1.

If there was already a result set described at this position, its description is replaced with a new (empty) one.

There is no public constructor for a DBSelectMetaData object. This method is the only way to create one.

Parameters:
position - the result number
Returns:
a new DBSelectMetaData object
DBException
java.sql.SQLException
See Also:
getMetaData(int), clearMetaData()

findColumn

public int findColumn(java.lang.String columnName)
               throws DBException,
                      java.sql.SQLException
Maps the given column label to its column index. The index of the first column is 1.

Overrides:
findColumn in class DBSelect
Parameters:
columnName - the label of the column
Returns:
the column index
Throws:
DBException - noCurrentResult - if you are not positioned on a result set.
java.sql.SQLException

firstResult

public boolean firstResult()
                    throws DBException,
                           java.sql.SQLException
Applies any changes in the current row of the current result set to the database, and then positions to the first result set.

If there are no result sets, a false is returned.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

Returns:
true if you are positioned to the first result set; false if there are no result sets.
Throws:
DBException - notExecuted - if statement has not been executed
DBException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DBException - rowNotFound - if the lockRows property is true and the new current row cannot be locked
DBException - sqlException - if an SQLException occurred
java.sql.SQLException
See Also:
setResult(int)

getMetaData

public com.ibm.db.beans.DBSelectMetaData getMetaData(int position)
                                              throws DBException,
                                                     java.sql.SQLException
Gets the meta data describing the result set at the specified position. The position of the first result set is 1.

Parameters:
position - the result set number
Returns:
a DBSelectMetaData object
Throws:
DBException - resultNotDefined - if no result set has been defined at this position
java.sql.SQLException
See Also:
getMetaData(int), DBStatement.getParameterMetaData()

getParameter

public java.lang.Object getParameter(int position)
                              throws DBException,
                                     java.sql.SQLException
Gets the value of the parameter at the specified position. If the parameter value is null, a null is returned. The position of the first parameter is 1.

If the parameter is an output or inout parameter, then the first time you use this method after executing the stored procedure, its value will be retrieved from the database. Both the JDBC Statement and Connection must be open for this to succeed. Otherwise an exception will occur. Before executing, or after executing and using this method once, the Statement and Connection need not be open, and the exception will not occur.

Overrides:
getParameter in class DBStatement
Parameters:
position - position of the parameter
Returns:
the parameter value
Throws:
DBException - noSuchParm - if the parameter is not defined
java.sql.SQLException - - if a database access error occurs
See Also:
DBStatement.getParameterAsString(int), DBStatement.setParameter(int, Object)

getResult

public int getResult()
Gets the number of the result set to which you are currently positioned. The number of the first result is 1.

Returns:
the number of the current result set; 0 if not positioned on a result set
See Also:
setResult(int)

getResultCount

public int getResultCount()
Gets the number of result sets.

If you use this method before executing the stored procedure, it reflects only the meta data you have provided about the stored procedure. If you use it after executing, the number returned will be the greater of the number before executing and the number of result sets actually fetched so far. (There could be additional result sets not yet fetched.)

Returns:
the number of result sets

hasResult

public boolean hasResult()
Returns true if the store procedure returns at least one result set; returns false otherwise.

If you use this method before executing the stored procedure, it reflects only the meta data you have provided about the stored procedure.

Returns:
true if the stored procedure returns a result set; otherwise false.

isFetchAllResultsOnExecute

public boolean isFetchAllResultsOnExecute()
Returns true if all result sets produced by this procedure call will be obtained immediately during the execute method. Otherwise, only the first result set will be obtained at that time, and additional result sets will be obtained upon request.

Once all result sets have been obtained, it is not possible to fetch additional rows in any result set. Therefore, if your procedure produces multiple result sets, and you used the cacheLimit property to limit the number of rows initially fetched, you should set this property to false in order to fetch additional rows.

If you do not execute this method, the value defaults to true.

Returns:
true if all result sets will be fetched during execute(); false if only the first result set will be fetched during execute().
See Also:
setFetchAllResultsOnExecute(boolean), nextResult(), DBSelect.setCacheLimit(int)

isLastResult

public boolean isLastResult()
Returns true if the current result set is the last one fetched and either there are known to be no more result sets or the statement has been closed.

It cannot be known that there are no more result sets until you have tried to go past the last result set. Therefore, if you are on the last result set and have not tried to go past it, this method will return false.

If there are no result sets, the method will return false. If you wish to test whether any result sets were obtained by executing the stored procedure, use hasResult() or getResultCount().

Returns:
true if the current result set is the last one fetched and no more result sets can be fetched.
See Also:
hasResult(), getResultCount()

isOpen

public boolean isOpen()
               throws java.sql.SQLException
Returns true if the underlying RowSet is open, otherwise returns false.

If you are positioned to a result set returned by the stored procedure, this method reports the status of that result set. Otherwise it reports the status of the JDBC Statement.

When isOpen returns true, the database Connection, Statement, and current ResultSet (if any) are all open, and the RowSet is fully functional.

When isOpen returns false, it may be because the statement has not been executed, the result set you are positioned to has been closed, or the DBProcedureCall bean has been serialized and then de-serialized.

If you are positioned to a result set which is closed, you can scroll among any rows currently in the cache and you can even perform inserts, updates, and deletes, but you cannot fetch any additional rows.

Overrides:
isOpen in class DBSelect
Returns:
true if the RowSet is open, otherwise false.
java.sql.SQLException
See Also:
DBSelect.isOpen(int), DBSelect.close()

lastResult

public boolean lastResult()
                   throws DBException,
                          java.sql.SQLException
Applies any changes in the current row of the current result set to the database, and then positions to the last result set.

If there are no result sets, a false is returned.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

Returns:
true if you are positioned to the last result set; false if there are no result sets.
Throws:
DBException - notExecuted - if statement has not been executed
DBException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DBException - rowNotFound - if the lockRows property is true and the new current row cannot be locked
DBException - sqlException - if an SQLException occurred
java.sql.SQLException
See Also:
setResult(int)

nextResult

public boolean nextResult()
                   throws DBException,
                          java.sql.SQLException
Applies any changes in the current row of the current result set to the database, and then positions to the next result set.

If the next result set has not already been fetched from the database, it is fetched.

If there is no next result set, a false is returned. Your position does not change, and no exception is thrown. Thus, if there are no result sets, or you are on the last result set, repeatedly invoking this method has no effect. For a discussion of when no more result sets can be fetched, see the isLastResult method.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

Returns:
true if the position moved to the next result set; false if there was no next result set.
Throws:
DBException - notExecuted - if statement has not been executed
DBException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DBException - rowNotFound - if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException - - if an SQLException occurred
See Also:
setResult(int)

previousResult

public boolean previousResult()
                       throws DBException,
                              java.sql.SQLException
Applies any changes in the current row of the current result set to the database, and then positions to the previous result set.

If there is no previous result set, a false is returned. Your position does not change, and no exception is thrown. Thus, if there are no result sets, or you are on the first result set, repeatedly invoking this method has no effect.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

Returns:
true if the position moved to the previous result set; false if there was no previous result set.
Throws:
DBException - notExecuted - if statement has not been executed
DBException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DBException - rowNotFound - if the lockRows property is true and the new current row cannot be locked
DBException - sqlException - if an SQLException occurred
java.sql.SQLException
See Also:
setResult(int)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a listener to the PropertyChange event set.

Overrides:
removePropertyChangeListener in class DBSelect
Parameters:
listener - PropertyChangeListener
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)

setFetchAllResultsOnExecute

public void setFetchAllResultsOnExecute(boolean fetchAll)
If true, all result sets produced by this procedure call will be obtained immediately during the execute method. Otherwise, only the first result set will be obtained at that time, and additional result sets will be obtained upon request.

Once all result sets have been obtained, it is not possible to fetch additional rows in any result set. Therefore, if your procedure produces multiple result sets, and you have limited the cache size of result sets via the cacheLimit property, you should set this property to false in order to fetch additional rows.

If you do not execute this method, the value defaults to true.

Parameters:
fetchAll - true fetch all result sets during execute(); false fetch only the first result set during execute().

See Also:
isFetchAllResultsOnExecute(), nextResult()

setResult

public boolean setResult(int resultNumber)
                  throws DBException,
                         java.sql.SQLException
Applies any changes in the current row of the current result set to the database, and then positions to the specified result set. The index of the first result set is 1.

If the specified result set has not yet been fetched, result sets are fetched until the specified result set is in the cache or no more result sets can be fetched. If no more result sets can be fetched, and the specified result set was not reached, a false is returned to indicate that the request could not be satisfied.

If the current row should be locked ( isLockRows returns true), the current row of the new current result set is locked in the database.

Parameters:
resultNumber - index of the result set
Returns:
true if the position moved to the requested result set; false if the requested result set could not be reached.
Throws:
DBException - notExecuted - if statement has not been executed
DBException - rowChanged - if the current row cannot be updated because it cannot be found in the database
DBException - rowNotFound - if the lockRows property is true and the new current row cannot be locked
java.sql.SQLException - - if an SQLException occurred
See Also:
getResult(), nextResult(), previousResult(), firstResult(), lastResult()