com.ibm.db.beans
Class DBStatement

java.lang.Object
  |
  +--com.ibm.db.beans.DBStatement
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
DBModify, DBSelect

public abstract class DBStatement
extends java.lang.Object
implements java.io.Serializable

This abstract class is the parent for several other classes that expose JDBC 2.0 RowSet functionality. The JDBC RowSet "wraps" a connection, a statement, and a result set as a bean, and provides properties, methods, and events for using them.

Classes that extend this one include DBSelect, for executing a query and using its result set; DBProcedureCall, for calling a stored procedure and using any parameters or result sets it returns; and DBModify for executing an SQL statement that does not return a result set.

See Also:
Serialized Form

Field Summary
static int LEVEL_CONNECTION
          JDBC resource level representing java.sql.Connection object
static int LEVEL_RESULTSET
          JDBC resource level representing java.sql.ResultSet object
static int LEVEL_STATEMENT
          JDBC resource level representing java.sql.Statement object
static int TRANSACTION_DEFAULT
          Use default transaction isolation level for database.
 
Constructor Summary
DBStatement()
           
 
Method Summary
abstract  void addDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
          Adds a listener to the DBAfter event set.
abstract  void addDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
          Adds a listener to the DBBefore event set.
abstract  void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a listener to the PropertyChange event set.
 void cancelAction()
          Cancels execution of the database action which is currently being performed via this bean.
 void clearParameters()
          Clears the values of all statement parameters.
abstract  void close()
          Releases the underlying database and JDBC resources immediately instead of waiting for this to happen when the object is finalized.
abstract  void close(int resourceLevel)
          Releases the underlying database and JDBC resources immediately instead of waiting for this to happen when the object is finalized.
 void commit()
          Commits changes to the database.
abstract  void execute()
          Executes the SQL statement, connecting to the database if not already connected.
 int findParameter(java.lang.String parameterName)
          Maps the given parameter name to its position.
 boolean getAutoCommit()
          Gets the value of the autoCommit property.
 java.lang.String getCommand()
          Gets the SQL statement serving as the rowset's command property.
 java.sql.Connection getConnection()
          Gets the java.sql.Connection object used by this DBStatement.
 com.ibm.db.beans.DBConnectionSpec getConnectionSpec()
          Gets the DBConnectionSpec object used by this DBStatement.
 java.lang.String getDataSourceName()
          Gets the JNDI name of the javax.sql.DataSource to use when opening a database connection.
 java.lang.String getDriverName()
          Gets the class name of the JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.
 java.lang.String getInitialContextFactory()
          Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.
 java.lang.String getJspNullToken()
          Gets the String that will be used by default in JSPs that use this bean to represent a null value.
 java.io.PrintWriter getLogWriter()
          Gets the PrintWriter being used to log any error or trace information written by this bean.
 java.lang.Object getParameter(int position)
          Returns the value of the parameter at the specified position.
 java.lang.Object getParameter(java.lang.String parameterName)
          Returns the value of the parameter with the specified name.
 java.lang.String getParameterAsString(int position)
          Returns the value of the parameter at the specified position as a String.
 java.lang.String getParameterAsString(java.lang.String parameterName)
          Returns the value of the parameter with the specified name as a String.
 int getParameterCount()
          Returns the number of parameters in the SQL statement.
 com.ibm.db.beans.DBParameterMetaData getParameterMetaData()
          Retrieves the DBParameterMetaData object describing any statement parameters.
 java.lang.String getParameterName(int position)
          Returns the name of the parameter at position.
 java.lang.String getPassword()
          Returns a String of asterisks (*) the length of the password used to create a database connection.
 java.lang.String getProviderUrl()
          Gets the URL of the machine where the naming service should look for a javax.sql.DataSource.
 int getQueryTimeout()
          Gets the number of seconds to wait for a statement to execute.
 boolean getTrace()
          Gets the tracing option of this bean.
 int getTransactionIsolation()
          Gets the transaction isolation level.
 java.lang.String getUrl()
          Gets the url of the database to connect to using the DriverManager.
 java.lang.String getUsername()
          Gets the user name used to create a database connection.
 boolean isExecuted()
          Returns true if execute has been invoked.
abstract  boolean isOpen()
          Returns true if the underlying JDBC objects are open, otherwise returns false.
abstract  boolean isOpen(int resourceLevel)
          Returns true if the underlying JDBC resource at the specified level is open, otherwise returns false.
 boolean isOptimizeConvertToString()
          Indicates whether optimization for String conversion is on or off.
 boolean isOptimizeForJsp()
          Indicates whether optimization for use in a Java Server Page (JSP) is on or off.
 boolean isOptimizeForNoListeners()
          Indicates whether optimization for no event listeners is on or off.
abstract  void reExecute()
          Re-executes the statement.
abstract  void removeDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
          Removes a listener to the DBAfter event set.
abstract  void removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
          Removes a listener to the DBBefore event set.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a listener to the PropertyChange event set.
 void rollback()
          Rollback changes in the database.
 void setAutoCommit(boolean autoCommit)
          Sets the value of the autoCommit property.
 void setCommand(java.lang.String cmd)
          Sets the SQL statement serving as the rowset's command property.
 void setConnection(java.sql.Connection connection)
          Sets the java.sql.Connection object used by this DBStatement.
 void setConnectionSpec(com.ibm.db.beans.DBConnectionSpec aConnectionSpec)
          Sets the DBConnectionSpec object used by this DBStatement.
 void setDataSourceName(java.lang.String name)
          Specifies the name of a javax.sql.DataSource to use when opening a database connection, and clears any value previously set for the url property.
 void setDriverName(java.lang.String driverName)
          Specifies the class name of a JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.
 void setInitialContextFactory(java.lang.String initialContextFactory)
          Specifies the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.
 void setJspNullToken(java.lang.String token)
          Sets the String that will be used by default in JSPs that use this bean to represent a null value.
 void setLogWriter(java.io.PrintWriter out)
          Provides the PrintWriter that will be used to log any error or trace information written by this bean.
 void setOptimizeConvertToString(boolean optimize)
          Turns optimization for String conversion on or off.
 void setOptimizeForJsp(boolean optimize)
          Turns optimization for use in a Java Server Page (JSP) on or off.
 void setOptimizeForNoListeners(boolean optimize)
          Turns optimization for no event listeners on or off.
 void setParameter(int parameterNumber, java.lang.Object aValue)
          Sets the parameter at the specified index to the specified value.
 void setParameter(java.lang.String parameterName, java.lang.Object aValue)
          Sets the parameter with the specified name to the specified value.
 void setParameterFromString(int parameterNumber, java.lang.String stringValue)
          Sets the parameter at the specified index to the specified value.
 void setParameterFromString(java.lang.String parameterName, java.lang.String stringValue)
          Sets the parameter with the specified name to the specified value.
 void setPassword(java.lang.String password)
          Sets the password used to create a database connection.
 void setProviderUrl(java.lang.String providerUrl)
          Specifies the URL of the machine where the naming service should look for a javax.sql.DataSource.
 void setQueryTimeout(int seconds)
          Sets the number of seconds to wait for a statement to execute.
 void setTrace(boolean choice)
          Sets the tracing option of this bean on or off.
 void setTransactionIsolation(int level)
          Sets the transaction isolation level.
 void setUrl(java.lang.String url)
          Specifies the url of the database to connect to using the DriverManager, and clears any value previously set for the dataSourceName property.
 void setUsername(java.lang.String name)
          Sets the user name used to create a database connection.
 void shareConnectionWith(com.ibm.db.beans.DBStatement statement)
          Makes this DBStatement object share the same java.sql.Connection object as another DBStatement object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LEVEL_CONNECTION

public static final int LEVEL_CONNECTION
JDBC resource level representing java.sql.Connection object

See Also:
Constant Field Values

LEVEL_STATEMENT

public static final int LEVEL_STATEMENT
JDBC resource level representing java.sql.Statement object

See Also:
Constant Field Values

LEVEL_RESULTSET

public static final int LEVEL_RESULTSET
JDBC resource level representing java.sql.ResultSet object

See Also:
Constant Field Values

TRANSACTION_DEFAULT

public static final int TRANSACTION_DEFAULT
Use default transaction isolation level for database.

See Also:
Constant Field Values
Constructor Detail

DBStatement

public DBStatement()
Method Detail

addDBAfterListener

public abstract void addDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
Adds a listener to the DBAfter event set. DBAfter events occur after significant actions have been completed via the DBStatement.

Parameters:
listener - DBAfterListener
See Also:
DBAfterListener, removeDBAfterListener(com.ibm.db.beans.DBAfterListener)

addDBBeforeListener

public abstract void addDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
Adds a listener to the DBBefore event set. DBBefore events occur before significant actions have been completed via the DBStatement.

Parameters:
listener - DBBeforeListener
See Also:
DBBeforeListener, removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener)

addPropertyChangeListener

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

Parameters:
listener - PropertyChangeListener
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener)

cancelAction

public void cancelAction()
                  throws DBException,
                         java.sql.SQLException
Cancels execution of the database action which is currently being performed via this bean. In order to use this method, it must be invoked from a thread different from the one in which the database action is occurring.

The database action is either execution of the SQL statement in the command property, or for some subclasses of this one, execution of a secondary related SQL statement, such as one to update, delete, or insert a row in the result set.

Throws:
DBException - noConnection - if no associated DatabaseConnection
DBException - notExecuting - if the statement is not currently being executed
java.sql.SQLException - - if an SQLException occurred

clearParameters

public void clearParameters()
                     throws java.sql.SQLException
Clears the values of all statement parameters.

After using this method, you must set a value for each input parameter before executing the statement.

In general, parameter values remain in force for repeated use of a RowSet. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values; this can be done by calling clearParameters.

Throws:
java.sql.SQLException - if a database-access error occurs.

close

public abstract void close()
                    throws DBException,
                           java.sql.SQLException
Releases the underlying database and JDBC resources immediately instead of waiting for this to happen when the object is finalized.

If autoCommit is false, you must explicitly do a commit or rollback before using the close method.

Throws:
java.sql.SQLException - if a database access error occurs
DBException
See Also:
close(int), isOpen()

close

public abstract void close(int resourceLevel)
                    throws DBException,
                           java.sql.SQLException
Releases the underlying database and JDBC resources immediately instead of waiting for this to happen when the object is finalized.

The value of the resourceLevel parameter determines which resources are released. If all resources, including the Connection, are released, and autoCommit is false, you must explicitly do a commit or rollback before using the close method.

Parameters:
resourceLevel - LEVEL_RESULTSET indicates only ResultSet resources should be released. ;LEVEL_STATEMENT indicates Statement and ResultSet resources should be released. LEVEL_CONNECTION indicates Connection, Statement, and ResultSet resources should be released. (Note that not all subclasses of DBStatement have resources at the ResultSet level.)

Throws:
DBException - invalidResourceLevel - if the resource level is not valid
java.sql.SQLException - if a database access error occurs
See Also:
close(), isOpen(int)

commit

public void commit()
            throws DBException,
                   java.sql.SQLException
Commits changes to the database. All outstanding changes made to the database using the underlying java.sql.Connection 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.

Throws:
DBException - noActiveConnection - if no active connection exists
java.sql.sqlException - - if an SQL exception occurs
java.sql.SQLException
See Also:
rollback(), setAutoCommit(boolean)

execute

public abstract void execute()
                      throws DBException,
                             java.sql.SQLException
Executes the SQL statement, connecting to the database if not already connected.

Throws:
DBException - badUidPwd - if incorrect username or password specified
DBException - noSQL - if the SQL statement is null
DBException - noTransactions - if database does not support transactions and autoCommit set to false
java.sql.SQLException - - if a database access error occurred

findParameter

public int findParameter(java.lang.String parameterName)
                  throws DBException,
                         java.sql.SQLException
Maps the given parameter name to its position. The position of the first parameter is 1.

Parameters:
parameterName - the name of the parameter
Returns:
the parameter position
Throws:
DBException - parameterNotDefined - the parameter with the specified name is not defined
java.sql.SQLException

getAutoCommit

public boolean getAutoCommit()
Gets the value of the autoCommit property. If you do not explicitly set this property, it defaults to true.

Returns:
true if autoCommit is on, false if autoCommit is off.
See Also:
setAutoCommit(boolean)

getCommand

public java.lang.String getCommand()
Gets the SQL statement serving as the rowset's command property. The command property contains a command string that can be executed. The default value is null.

Returns:
the SQL statement
See Also:
setCommand(java.lang.String)

getConnection

public java.sql.Connection getConnection()
Gets the java.sql.Connection object used by this DBStatement.

In general, it is expected that all operations involving the connection, the statement, or the result set will be performed via the DBStatement object. However, since not all methods of java.sql.Connection are made available via the DBStatement, you can use this method to get the Connection object and call any of its methods directly.

Returns:
the Connection used by this DBStatement. If the DBStatement is not currently connected to the database, returns null.

getConnectionSpec

public com.ibm.db.beans.DBConnectionSpec getConnectionSpec()
Gets the DBConnectionSpec object used by this DBStatement.

Returns:
the DBConnectionSpec used by this DBStatement

getDataSourceName

public java.lang.String getDataSourceName()
Gets the JNDI name of the javax.sql.DataSource to use when opening a database connection. Users should set either the url or dataSourceName property.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

Returns:
the name of the javax.sql.DataSource
See Also:
setDataSourceName(java.lang.String), getInitialContextFactory(), getProviderUrl()

getDriverName

public java.lang.String getDriverName()
Gets the class name of the JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection.

If this property is null or an empty string, no driver will be automaticaly loaded and registered. It may still be possible to connect via the DriverManager if an appropriate driver has been loaded and registered independently of this bean.

This property is only used if the url property is not null. If the url property is null, then this field is ignored and the connection is obtained using the DataSource specified in the dataSourceName property.

Returns:
the class name of the JDBC driver to load and register
See Also:
setDriverName(java.lang.String), getUrl()

getInitialContextFactory

public java.lang.String getInitialContextFactory()
Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource.

If this property is null, the default InitialContextFactory identified by the java.naming.factory.initial property in your java environment will be used.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Returns:
the class name of the InitialContexFactory used to locate the DataSource.
See Also:
setInitialContextFactory(java.lang.String), getDriverName(), getProviderUrl()

getJspNullToken

public java.lang.String getJspNullToken()
Gets the String that will be used by default in JSPs that use this bean to represent a null value.

Although this method is public, it is expected only to be used by the code implementing the JSP SQL tags. The tags allow you to specify a null token at the level of a DBStatement which will be used when getting/setting any parameter or column whose tag does not override this null token with its own.

Returns:
the String used to represent a null value
See Also:
setJspNullToken(java.lang.String)

getLogWriter

public java.io.PrintWriter getLogWriter()
Gets the PrintWriter being used to log any error or trace information written by this bean.

The default log writer logs to the Java console. When this property is set to null, no information is logged.

See Also:
setLogWriter(java.io.PrintWriter)

getParameter

public java.lang.Object getParameter(int position)
                              throws DBException,
                                     java.sql.SQLException
Returns 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.

Parameters:
position - position of the parameter
Returns:
the parameter value
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
java.sql.SQLException - - if a database access error occurs (only occurs for stored procedure parameters)
See Also:
getParameterAsString(int), setParameter(int, Object)

getParameter

public java.lang.Object getParameter(java.lang.String parameterName)
                              throws DBException,
                                     java.sql.SQLException
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:
DBException - parameterNotDefined - if no parameter has been defined at this position
java.sql.SQLException - - if a database access error occurs (only occurs for stored procedure parameters)
See Also:
getParameterAsString(String), setParameter(String, Object)

getParameterAsString

public java.lang.String getParameterAsString(int position)
                                      throws DBException,
                                             java.sql.SQLException
Returns the value of the parameter at the specified position 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 position of the first parameter is 1.

Parameters:
position - position of the parameter
Returns:
value of the parameter as a String
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
DBException - cannotConvertToString - if value cannot be converted to a String
java.sql.SQLException - - if a database access error occurs (only occurs for stored procedure parameters)
See Also:
getParameter(int), setParameterFromString(int, String)

getParameterAsString

public java.lang.String getParameterAsString(java.lang.String parameterName)
                                      throws DBException,
                                             java.sql.SQLException
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:
DBException - parameterNotDefined - if no parameter has been defined at this position
DBException - cannotConvertToString - if value cannot be converted to a String
java.sql.SQLException - - if a database access error occurs (only occurs for stored procedure parameters)
See Also:
getParameter(String), setParameterFromString(String, String)

getParameterCount

public int getParameterCount()
Returns the number of parameters in the SQL statement. The number returned is based on parameter definitions in the associated DBParameterMetaData, not on the string in the command property of this bean. However, the number of parameters in those two places must match when you execute.

Returns:
the number of parameters in the SQL statement

getParameterMetaData

public com.ibm.db.beans.DBParameterMetaData getParameterMetaData()
                                                          throws java.sql.SQLException
Retrieves the DBParameterMetaData object describing any statement parameters.

To provide meta data, use this method to get the empty meta data object created when this object was constructed, and fill it in.

Returns:
the DBParameterMetaData describing this object
Throws:
java.sql.SQLException - if a database access error occurs

getParameterName

public java.lang.String getParameterName(int position)
                                  throws DBException,
                                         java.sql.SQLException
Returns the name of the parameter at position. The position of the first parameter is 1.

Parameters:
position - the position of parameter
Returns:
the name of the parameter
Throws:
DBException - parameterNotDefined - if no parameter has been defined at this position
java.sql.SQLException

getPassword

public java.lang.String getPassword()
Returns a String of asterisks (*) the length of the password used to create a database connection. The actual password is not returned so that the return value of this method can be displayed in a GUI without compromising security.

Returns:
a String of asterisks (*) the length of the password
See Also:
setPassword(java.lang.String)

getProviderUrl

public java.lang.String getProviderUrl()
Gets the URL of the machine where the naming service should look for a javax.sql.DataSource.

If this property is null, the naming service will look on the local host.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Returns:
the URL of the machine where the naming service should look for a DataSource
See Also:
setProviderUrl(java.lang.String), getDataSourceName(), getInitialContextFactory()

getQueryTimeout

public int getQueryTimeout()
                    throws java.sql.SQLException
Gets the number of seconds to wait for a statement to execute. If the limit is exceeded, an exception is thrown.

Returns:
the current query timeout limit in seconds; zero means unlimited
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
setQueryTimeout(int)

getTrace

public boolean getTrace()
Gets the tracing option of this bean. If you do not set this option explicitly, it is off by default.

When the tracing option is on, entries are written to the PrintWriter specified in the logWriter property.

Returns:
true if tracing is on, otherwise false.
See Also:
setTrace(boolean)

getTransactionIsolation

public int getTransactionIsolation()
Gets the transaction isolation level.

If you have not explicitly set this property, the method returns the constant DBStatement.TRANSACTION_DEFAULT. In this case, once you connect, transactionIsolation will be the default level for the database product you are using.

Returns:
the transaction isolation level

getUrl

public java.lang.String getUrl()
                        throws java.sql.SQLException
Gets the url of the database to connect to using the DriverManager. The default value is null.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

Returns:
the url of the database
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
setUrl(java.lang.String), getDriverName()

getUsername

public java.lang.String getUsername()
Gets the user name used to create a database connection.

Returns:
a user name
See Also:
setUsername(java.lang.String)

isExecuted

public boolean isExecuted()
Returns true if execute has been invoked.

Returns:
true if execute has been invoked. otherwise false.
See Also:
execute()

isOpen

public abstract boolean isOpen()
                        throws java.sql.SQLException
Returns true if the underlying JDBC objects are open, otherwise returns false.

When isOpen returns true, all underlying JDBC objects are open, and the bean is fully functional.

When isOpen returns false, it may be because the statement has not been executed, the close method has been invoked, or the bean has been serialized and then de-serialized.

Returns:
true if the bean is open, otherwise false.
java.sql.SQLException
See Also:
isOpen(int), close()

isOpen

public abstract boolean isOpen(int resourceLevel)
                        throws DBException,
                               java.sql.SQLException
Returns true if the underlying JDBC resource at the specified level is open, otherwise returns false.

If the resourceLevel is LEVEL_CONNECTION, a return value of true indicates that the Connection is open. If the resourceLevel is LEVEL_STATEMENT, a return value of true indicates that the Statement, and therefore also the Connection are open. If the resourceLevel is LEVEL_RESULTSET, a return value of true indicates that the ResultSet, and therefore also the Statement, and Connection are open. (Note that not all subclasses of DBStatement have resources at the ResultSet level.)

Parameters:
resourceLevel - A resource level: LEVEL_CONNECTION, LEVEL_STATEMENT, or LEVEL_RESULTSET.
Returns:
true if the JDBC resource at the specified level is open, otherwise false.
Throws:
DBException - invalidResourceLevel - if the resource level is not valid
java.sql.SQLException - if a database-access error occurs.
See Also:
isOpen(), close(int)

isOptimizeConvertToString

public boolean isOptimizeConvertToString()
Indicates whether optimization for String conversion is on or off. When this optimization is on, all values cached for the underlying RowSet and all parameter values are stored as Strings. When it is off, all values are stored in their default types.

Returns:
true if automatic String conversion is on; false if it is off
See Also:
setOptimizeConvertToString(boolean), isOptimizeForJsp()

isOptimizeForJsp

public boolean isOptimizeForJsp()
Indicates whether optimization for use in a Java Server Page (JSP) is on or off. Turning on this optimization is equivalent to turning on both automatic String conversion (via optimizeConvertToString()) and suppression of event firing (via optimizeForNoListeners()). Turning off this optimization is equivalent to turning off both automatic String conversion and suppression of event firing.

Returns:
true if automatic String conversion and suppression of event firing are on; false if they are off
See Also:
setOptimizeForJsp(boolean), isOptimizeConvertToString(), isOptimizeForNoListeners()

isOptimizeForNoListeners

public boolean isOptimizeForNoListeners()
Indicates whether optimization for no event listeners is on or off. When this optimization is on, no events are fired. When it is off, events are fired.

Returns:
true if suppression of event firing is on; false if it is off
See Also:
setOptimizeForNoListeners(boolean), isOptimizeForJsp()

reExecute

public abstract void reExecute()
                        throws DBException,
                               java.sql.SQLException
Re-executes the 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 statement itself, that change will not take effect. (To make the latter change take effect, use the execute method.

Throws:
DBException - noActiveConnection - if no active connection exists
DBException - notOpen - if the statement is not open
java.sql.SQLException - - if a database access error occurred
See Also:
execute()

removeDBAfterListener

public abstract void removeDBAfterListener(com.ibm.db.beans.DBAfterListener listener)
Removes a listener to the DBAfter event set. DBAfter events occur after significant actions have been completed via the DBStatement.

Parameters:
listener - DBAfterListener
See Also:
DBAfterListener, addDBAfterListener(com.ibm.db.beans.DBAfterListener)

removeDBBeforeListener

public abstract void removeDBBeforeListener(com.ibm.db.beans.DBBeforeListener listener)
Removes a listener to the DBBefore event set. DBBefore events occur before significant actions have been completed via the DBStatement.

Parameters:
listener - DBBeforeListener
See Also:
DBBeforeListener, addDBBeforeListener(com.ibm.db.beans.DBBeforeListener)

removePropertyChangeListener

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

Parameters:
listener - PropertyChangeListener
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)

rollback

public void rollback()
              throws DBException,
                     java.sql.SQLException
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.

Throws:
DBException - noActiveConnection - if no active connection exists
java.sql.SQLException - - if an SQL exception occurs
See Also:
commit(), setAutoCommit(boolean)

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws DBException,
                          java.sql.SQLException
Sets the value of the autoCommit property.

You may set the property before or after connecting to the database. If you are already connected, the new setting is propagated immediately to the underlying java.sql.Connection object. If not, the new value will be used when you connect.

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback.

The default value of this property is true.

Parameters:
autoCommit - true to turn autoCommit on; false to turn autoCommit off.
Throws:
DBException - noTransactions - if database does not support transactions and autoCommit set to false
java.sql.SQLException - if a database access error occurs
See Also:
getAutoCommit()

setCommand

public void setCommand(java.lang.String cmd)
                throws java.sql.SQLException
Sets the SQL statement serving as the rowset's command property.

The command property contains a command string that can be executed. The default value is null.

Parameters:
cmd - the SQL statement
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
getCommand()

setConnection

public void setConnection(java.sql.Connection connection)
                   throws DBException,
                          java.sql.SQLException
Sets the java.sql.Connection object used by this DBStatement.

In general, it is expected that the DBStatement will obtain a java.sql.Connection object at the time it is executed, based on the connection specification information you have provided. However, this method provides the flexibility to use a Connection you obtained outside the context of a DBStatement for whatever reason,

You should only use this method if there is a limitation of the connection semantics of the DBStatement which you must circumvent.

This method is not the recommended way of sharing a connection between two DBStatement objects in order, for example, to execute within the same transaction scope. For that purpose, use the shareConnectionWith method.

Parameters:
connection - the java.sql.Connection being assigned to this object
Throws:
DBException - connectionClosed - if the java.sql.Connection is closed
java.sql.SQLException
See Also:
shareConnectionWith(com.ibm.db.beans.DBStatement)

setConnectionSpec

public void setConnectionSpec(com.ibm.db.beans.DBConnectionSpec aConnectionSpec)
Sets the DBConnectionSpec object used by this DBStatement.

A user can set the connection properties directly on the statement (DBSelect, DBModify, or DBProcedureCalll) or use similar methods to set them on the DBConnectSpec and then set the statement's connectionSpec.


setDataSourceName

public void setDataSourceName(java.lang.String name)
                       throws java.sql.SQLException
Specifies the name of a javax.sql.DataSource to use when opening a database connection, and clears any value previously set for the url property.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
getDataSourceName(), setInitialContextFactory(java.lang.String), setProviderUrl(java.lang.String)

setDriverName

public void setDriverName(java.lang.String driverName)
                   throws java.sql.SQLException
Specifies the class name of a JDBC driver that will automatically be loaded and registered for you before using the DriverManager to open a database connection. The name must be fully qualified with the package containing the driver. For example, the DB2 application JDBC driver is COM.ibm.db2.jdbc.appDB2Driver.

If this property is null or an empty string, no driver will be automaticaly loaded and registered. It may still be possible to connect via the DriverManager if an appropriate driver has been loaded and registered independently of this bean.

This property is only used if the url property is not null. If the url property is null, then this field is ignored and the connection is obtained using the DataSource specified in the dataSourceName property.

java.sql.SQLException
See Also:
getDriverName(), setUrl(java.lang.String)

setInitialContextFactory

public void setInitialContextFactory(java.lang.String initialContextFactory)
                              throws java.sql.SQLException
Specifies the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource. The name must be fully qualified with the package containing the class. For example, the InitialContextFactory for the WebSphere naming service is com.ibm.ejs.ns.jndi.CNInitialContextFactory.

If you set this property to null, the default InitialContextFactory identified by the property java.naming.factory.initial in your java environment will be used.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Parameters:
initialContextFactory - the class name of the InitialContextFactory used locate the DataSource.
java.sql.SQLException
See Also:
getInitialContextFactory(), setDataSourceName(java.lang.String), setProviderUrl(java.lang.String)

setJspNullToken

public void setJspNullToken(java.lang.String token)
Sets the String that will be used by default in JSPs that use this bean to represent a null value. The default value is the empty string ("").

Although this method is public, it is expected only to be used by the code implementing the JSP SQL tags. The tags allow you to specify a null token at the level of a DBStatement which will be used when getting/setting any parameter or column whose tag does not override this null token with its own.

Parameters:
token - the String used to represent a null value
See Also:
getJspNullToken()

setLogWriter

public void setLogWriter(java.io.PrintWriter out)
                  throws java.sql.SQLException
Provides the PrintWriter that will be used to log any error or trace information written by this bean.

If you do not explicitly use this method to provide a PrintWriter, information is logged by default to the Java console. If you wish to have no information logged, you can provide a null value here. If you wish to have log information for this bean and log information for your database written to the same place, provide the same PrintWriter for both the DriverManager.setLogWriter() method and this method.

Parameters:
out - the PrintWriter that will be used for logging
Throws:
DBException - noLogWriter - if trace is enabled and LogWriter is set to null
java.sql.SQLException
See Also:
setTrace(boolean), getLogWriter()

setOptimizeConvertToString

public void setOptimizeConvertToString(boolean optimize)
                                throws DBException
Turns optimization for String conversion on or off. When this optimization is on, all parameter and column values are stored as Strings unless you have explicitly mapped them to some other Java class. When it is off, all values are stored in their default types or the types to which you have mapped them.

You can only change the setting of this property before executing the SQL statement. If you never use this method to explicitly set the property, optimization is off by default.

Parameters:
optimize - true if optimization for String conversion should be on; false if it should be off.
Throws:
DBException - cannotSetAfterExecute - if attempt to change this property after executing the SQL statement
See Also:
isOptimizeConvertToString(), setOptimizeForJsp(boolean)

setOptimizeForJsp

public void setOptimizeForJsp(boolean optimize)
                       throws DBException
Turns optimization for use in a Java Server Page (JSP) on or off. Turning on this optimization is equivalent to turning on both automatic String conversion (via optimizeConvertToString()) and suppression of event firing (via optimizeForNoListeners()).

You can only change the setting of this property before executing the SQL statement. If you never use this method to explicitly set the property, optimization is off by default.

Parameters:
optimize - true if optimization for use in a JSP should be on; false if it should be off.
Throws:
DBException - cannotSetAfterExecute - if attempt to change this property after executing the SQL statement
See Also:
isOptimizeForJsp(), setOptimizeConvertToString(boolean), setOptimizeForNoListeners(boolean)

setOptimizeForNoListeners

public void setOptimizeForNoListeners(boolean optimize)
                               throws DBException
Turns optimization for no event listeners on or off. When this optimization is on, no events are fired. When it is off, events are fired.

If you never use this method to explicitly set the property, optimization is off by default.

Parameters:
optimize - true if optimization for no event listeners should be on; false if it should be off.
DBException
See Also:
isOptimizeForNoListeners(), setOptimizeForJsp(boolean)

setParameter

public void setParameter(int parameterNumber,
                         java.lang.Object aValue)
                  throws DBException,
                         java.sql.SQLException
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:
DBException - noSuchParm - if the parameter is not defined
DBException - wrongObjectType - if the value does not match the object type of the parameter
java.sql.SQLException
See Also:
setParameterFromString(int, String), getParameter(int)

setParameter

public void setParameter(java.lang.String parameterName,
                         java.lang.Object aValue)
                  throws DBException,
                         java.sql.SQLException
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:
DBException - noSuchParm - if the parameter is not defined
DBException - wrongObjectType - if the value does not match the object type of the parameter
java.sql.SQLException
See Also:
setParameterFromString(String, String), getParameter(String)

setParameterFromString

public void setParameterFromString(int parameterNumber,
                                   java.lang.String stringValue)
                            throws DBException,
                                   java.sql.SQLException
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:
DBException - noSuchParm - if the parameter is not defined
DBException - wrongObjectType - if the value does not match the object type of the parameter
java.sql.SQLException
See Also:
setParameter(int, Object), getParameterAsString(String)

setParameterFromString

public void setParameterFromString(java.lang.String parameterName,
                                   java.lang.String stringValue)
                            throws DBException,
                                   java.sql.SQLException
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:
DBException - noSuchParm - if the parameter is not defined
DBException - wrongObjectType - if the value does not match the object type of the parameter
java.sql.SQLException
See Also:
setParameter(String, Object), getParameterAsString(String)

setPassword

public void setPassword(java.lang.String password)
                 throws java.sql.SQLException
Sets the password used to create a database connection.

If the value passed in is a String of asterisks (*) the length of the current password, the value is not set. It is assumed in this case that a property editor has used getPassword() to get the password shape, and has used that same value to set the password, without real intent to change the password.

Parameters:
password - the password string
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
getPassword()

setProviderUrl

public void setProviderUrl(java.lang.String providerUrl)
                    throws java.sql.SQLException
Specifies the URL of the machine where the naming service should look for a javax.sql.DataSource.

If you set this property to null, the naming service will look on the local host.

This property is only used if the dataSourceName property is not null. If the dataSourceName property is null, then this field is ignored and the connection is obtained using the DriverManager.

Parameters:
providerUrl - the URL of the machine where the naming service should look for a DataSource
java.sql.SQLException
See Also:
getProviderUrl(), setDataSourceName(java.lang.String), setInitialContextFactory(java.lang.String)

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws DBException,
                            java.sql.SQLException
Sets the number of seconds to wait for a statement to execute. If the limit is exceeded, an exception is thrown.

Parameters:
seconds - the new query timeout limit in seconds; zero means unlimited
Throws:
java.sql.SQLException - if a database-access error occurs.
DBException
See Also:
getQueryTimeout()

setTrace

public void setTrace(boolean choice)
              throws java.sql.SQLException
Sets the tracing option of this bean on or off. If you do not set this option explicitly, it is off by default.

When the tracing option is on, entries are written to the PrintWriter specified in the logWriter property.

Parameters:
choice - turns tracing on if true; off if false
Throws:
DBException - noLogWriter - if LogWriter is null and trace is set to true
java.sql.SQLException
See Also:
setLogWriter(java.io.PrintWriter)

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws DBException,
                                    java.sql.SQLException
Sets the transaction isolation level. You may set the property before or after connecting to the database. If you are already connected, the new setting is propagated immediately to the underlying java.sql.Connection object. If not, the new value will be used when you connect.

The default value for this property is the constant DBStatement.TRANSACTION_DEFAULT. When the property has this value, once you connect, transactionIsolation will be the default level for the database product you are using.

Parameters:
level - the transaction isolation level
Throws:
java.sql.SQLException - if a database-access error occurs.
DBException
See Also:
getTransactionIsolation()

setUrl

public void setUrl(java.lang.String url)
            throws java.sql.SQLException
Specifies the url of the database to connect to using the DriverManager, and clears any value previously set for the dataSourceName property. The default value is null.

When a connection is established, either the dataSourceName property or the url property is used, whichever was specified most recently. If the dataSourceName is used, a connection is established via a javax.sql.DataSource object. If the url is used, a connection is established via the Driver Manager.

To connect using the Driver Manager, you must either insure that a driver that accepts the url has been loaded and registered, or use the setDriverName method to cause such a driver to be automatically loaded and registered for you.

Parameters:
url - the url of the database
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
getUrl(), setDriverName(java.lang.String)

setUsername

public void setUsername(java.lang.String name)
                 throws java.sql.SQLException
Sets the user name used to create a database connection.

Parameters:
name - a user name
Throws:
java.sql.SQLException - if a database-access error occurs.
See Also:
getUsername()

shareConnectionWith

public void shareConnectionWith(com.ibm.db.beans.DBStatement statement)
Makes this DBStatement object share the same java.sql.Connection object as another DBStatement object.

This allows multiple statements to occur within the same transaction if need be. *

If two DBStatement objects share the same java.sql.Connection, they also share the same DBConnectionSpec. However, two DBStatement objects which share the same DBConnectionSpec do not necessarily share the same java.sql.Connection.

If a NULL is passed as the parameter, the statement will be reset so it is no longer sharing a connection. The default connection spec, autoCommit, and transaction isolation settings will be the same as the previously shared connection.

Parameters:
statement - the DBStatement with which to share a Connection