java.lang.Object com.ibm.db.beans.DBStatement
public abstract class DBStatement
implements Serializable
extends Object
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.
Field | Description |
---|---|
LEVEL_CONNECTION | JDBC resource level representing java.sql.Connection object |
LEVEL_RESULTSET | JDBC resource level representing java.sql.ResultSet object |
LEVEL_STATEMENT | JDBC resource level representing java.sql.Statement object |
TRANSACTION_DEFAULT | Use default transaction isolation level for database. |
Constructor | Description |
---|---|
DBStatement() |
Method | Description |
---|---|
void addDBAfterListener(DBAfterListener) | Adds a listener to the DBAfter event set. |
void addDBBeforeListener(DBBeforeListener) | Adds a listener to the DBBefore event set. |
void addPropertyChangeListener(PropertyChangeListener) | 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. |
void close() | Releases the underlying database and JDBC resources immediately instead of waiting for this to happen when the object is finalized. |
void close(int) | 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. |
void execute() | Executes the SQL statement, connecting to the database if not already connected. |
int findParameter(String) | Maps the given parameter name to its position. |
boolean getAutoCommit() | Gets the value of the autoCommit property. |
String getCommand() | Gets the SQL statement serving as the rowset's command property. |
Connection getConnection() | Gets the java.sql.Connection object used by this DBStatement. |
DBConnectionSpec getConnectionSpec() | Gets the DBConnectionSpec object used by this DBStatement. |
String getDataSourceName() | Gets the JNDI name of the javax.sql.DataSource to use when opening a database connection. |
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. |
String getInitialContextFactory() | Gets the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource. |
String getJspNullToken() | Gets the String that will be used by default in JSPs that use this bean to represent a null value. |
PrintWriter getLogWriter() | Gets the PrintWriter being used to log any error or trace information written by this bean. |
Object getParameter(int) | Returns the value of the parameter at the specified position. |
Object getParameter(String) | Returns the value of the parameter with the specified name. |
String getParameterAsString(int) | Returns the value of the parameter at the specified position as a String. |
String getParameterAsString(String) | Returns the value of the parameter with the specified name as a String. |
int getParameterCount() | Returns the number of parameters in the SQL statement. |
DBParameterMetaData getParameterMetaData() | Retrieves the DBParameterMetaData object describing any statement parameters. |
String getParameterName(int) | Returns the name of the parameter at position. |
String getPassword() | Returns a String of asterisks (*) the length of the password used to create a database connection. |
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. |
String getUrl() | Gets the url of the database to connect to using the DriverManager. |
String getUsername() | Gets the user name used to create a database connection. |
boolean isExecuted() | Returns true if execute has been invoked. |
boolean isOpen() | Returns true if the underlying JDBC objects are open, otherwise returns false. |
boolean isOpen(int) | 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. |
void reExecute() | Re-executes the statement. |
void removeDBAfterListener(DBAfterListener) | Removes a listener to the DBAfter event set. |
void removeDBBeforeListener(DBBeforeListener) | Removes a listener to the DBBefore event set. |
void removePropertyChangeListener(PropertyChangeListener) | Removes a listener to the PropertyChange event set. |
void rollback() | Rollback changes in the database. |
void setAutoCommit(boolean) | Sets the value of the autoCommit property. |
void setCommand(String) | Sets the SQL statement serving as the rowset's command property. |
void setConnection(Connection) | Sets the java.sql.Connection object used by this DBStatement. |
void setConnectionSpec(DBConnectionSpec) | Sets the DBConnectionSpec object used by this DBStatement. |
void setDataSourceName(String) | 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(String) | 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(String) | Specifies the class name of the InitialContextFactory that will be used to locate a javax.sql.DataSource. |
void setJspNullToken(String) | Sets the String that will be used by default in JSPs that use this bean to represent a null value. |
void setLogWriter(PrintWriter) | Provides the PrintWriter that will be used to log any error or trace information written by this bean. |
void setOptimizeConvertToString(boolean) | Turns optimization for String conversion on or off. |
void setOptimizeForJsp(boolean) | Turns optimization for use in a Java Server Page (JSP) on or off. |
void setOptimizeForNoListeners(boolean) | Turns optimization for no event listeners on or off. |
void setParameter(int, Object) | Sets the parameter at the specified index to the specified value. |
void setParameter(String, Object) | Sets the parameter with the specified name to the specified value. |
void setParameterFromString(int, String) | Sets the parameter at the specified index to the specified value. |
void setParameterFromString(String, String) | Sets the parameter with the specified name to the specified value. |
void setPassword(String) | Sets the password used to create a database connection. |
void setProviderUrl(String) | Specifies the URL of the machine where the naming service should look for a javax.sql.DataSource. |
void setQueryTimeout(int) | Sets the number of seconds to wait for a statement to execute. |
void setTrace(boolean) | Sets the tracing option of this bean on or off. |
void setTransactionIsolation(int) | Sets the transaction isolation level. |
void setUrl(String) | Specifies the url of the database to connect to using the DriverManager, and clears any value previously set for the dataSourceName property. |
void setUsername(String) | Sets the user name used to create a database connection. |
void shareConnectionWith(DBStatement) | Makes this DBStatement object share the same java.sql.Connection object as another DBStatement object. |
public static final int LEVEL_CONNECTIONJDBC resource level representing java.sql.Connection object
public static final int LEVEL_RESULTSETJDBC resource level representing java.sql.ResultSet object
public static final int LEVEL_STATEMENTJDBC resource level representing java.sql.Statement object
public static final int TRANSACTION_DEFAULTUse default transaction isolation level for database.
public DBStatement()
public abstract void addDBAfterListener(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
public abstract void addDBBeforeListener(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
public abstract void addPropertyChangeListener(PropertyChangeListener listener)Adds a listener to the PropertyChange event set.
- Parameters
- listener - PropertyChangeListener
- See Also
public void cancelAction() throws DBException, SQLExceptionCancels 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- Throws
DBException
notExecuting - if the statement is not currently being executed- Throws
SQLException
- if an SQLException occurred
public void clearParameters() throws SQLExceptionClears 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
SQLException
if a database-access error occurs.
public abstract void close() throws DBException, SQLExceptionReleases 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
SQLException
if a database access error occurs
public abstract void close(int resourceLevel) throws DBException, SQLExceptionReleases 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- Throws
SQLException
if a database access error occurs
public void commit() throws DBException, SQLExceptionCommits 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- Throws
java.sql.sqlException
- if an SQL exception occurs
- See Also
public abstract void execute() throws DBException, SQLExceptionExecutes the SQL statement, connecting to the database if not already connected.
- Throws
DBException
badUidPwd - if incorrect username or password specified- Throws
DBException
noSQL - if the SQL statement is null- Throws
DBException
noTransactions - if database does not support transactions and autoCommit set to false- Throws
SQLException
- if a database access error occurred
public int findParameter(String parameterName) throws DBException, SQLExceptionMaps 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
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
public 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
public 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.
public DBConnectionSpec getConnectionSpec()Gets the DBConnectionSpec object used by this DBStatement.
- Returns
- the DBConnectionSpec used by this DBStatement
public 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
public 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
public 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.
public 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
public 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.
- Parameters
- out - the PrintWriter that will be used for logging
- See Also
public Object getParameter(int position) throws DBException, SQLExceptionReturns 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- Throws
SQLException
- if a database access error occurs (only occurs for stored procedure parameters)
- See Also
public Object getParameter(String parameterName) throws DBException, SQLExceptionReturns 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- Throws
SQLException
- if a database access error occurs (only occurs for stored procedure parameters)
- See Also
public String getParameterAsString(int position) throws DBException, SQLExceptionReturns 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- Throws
DBException
cannotConvertToString - if value cannot be converted to a String- Throws
SQLException
- if a database access error occurs (only occurs for stored procedure parameters)
- See Also
public String getParameterAsString(String parameterName) throws DBException, SQLExceptionReturns 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- Throws
DBException
cannotConvertToString - if value cannot be converted to a String- Throws
SQLException
- if a database access error occurs (only occurs for stored procedure parameters)
- See Also
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
public DBParameterMetaData getParameterMetaData() throws SQLExceptionRetrieves 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
SQLException
if a database access error occurs
public String getParameterName(int position) throws DBException, SQLExceptionReturns 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
public 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
public 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
public int getQueryTimeout() throws SQLExceptionGets 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
SQLException
if a database-access error occurs.
- See Also
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
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
public String getUrl() throws SQLExceptionGets 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
SQLException
if a database-access error occurs.
- See Also
public String getUsername()Gets the user name used to create a database connection.
- Returns
- a user name
- See Also
public boolean isExecuted()Returns true if
execute
has been invoked.
- Returns
- true if
execute
has been invoked. otherwise false.
- See Also
public abstract boolean isOpen() throws SQLExceptionReturns 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, theclose
method has been invoked, or the bean has been serialized and then de-serialized.
- Returns
- true if the bean is open, otherwise false.
public abstract boolean isOpen(int resourceLevel) throws DBException, SQLExceptionReturns 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- Throws
SQLException
if a database-access error occurs.
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
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 (viaoptimizeForNoListeners()
). 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
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
public abstract void reExecute() throws DBException, SQLExceptionRe-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- Throws
DBException
notOpen - if the statement is not open- Throws
SQLException
- if a database access error occurred
- See Also
public abstract void removeDBAfterListener(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
public abstract void removeDBBeforeListener(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
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)Removes a listener to the PropertyChange event set.
- Parameters
- listener - PropertyChangeListener
- See Also
public void rollback() throws DBException, SQLExceptionRollback 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- Throws
SQLException
- if an SQL exception occurs
- See Also
public void setAutoCommit(boolean autoCommit) throws DBException, SQLExceptionSets 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 methodrollback
.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- Throws
SQLException
if a database access error occurs
- See Also
public void setCommand(String cmd) throws SQLExceptionSets 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
SQLException
if a database-access error occurs.
- See Also
public synchronized void setConnection(Connection connection) throws DBException, SQLExceptionSets 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
- See Also
public void setConnectionSpec(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.
public void setDataSourceName(String name) throws SQLExceptionSpecifies 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.
- Parameters
- the - name of a javax.sql.DataSource
- Throws
SQLException
if a database-access error occurs.
public void setDriverName(String driverName) throws SQLExceptionSpecifies 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.
- Parameters
- the - class name of a JDBC driver to load and register
- See Also
public void setInitialContextFactory(String initialContextFactory) throws SQLExceptionSpecifies 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.
public void setJspNullToken(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
public synchronized void setLogWriter(PrintWriter out) throws SQLExceptionProvides 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
- See Also
public synchronized void setOptimizeConvertToString(boolean optimize) throws DBExceptionTurns 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
public synchronized void setOptimizeForJsp(boolean optimize) throws DBExceptionTurns 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 (viaoptimizeForNoListeners()
).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
public synchronized void setOptimizeForNoListeners(boolean optimize) throws DBExceptionTurns 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.
public void setParameter(int parameterNumber, Object aValue) throws DBException, SQLExceptionSets 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- Throws
DBException
wrongObjectType - if the value does not match the object type of the parameter
- See Also
public void setParameter(String parameterName, Object aValue) throws DBException, SQLExceptionSets 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- Throws
DBException
wrongObjectType - if the value does not match the object type of the parameter
- See Also
public void setParameterFromString(int parameterNumber, String stringValue) throws DBException, SQLExceptionSets 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- Throws
DBException
wrongObjectType - if the value does not match the object type of the parameter
- See Also
public void setParameterFromString(String parameterName, String stringValue) throws DBException, SQLExceptionSets 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- Throws
DBException
wrongObjectType - if the value does not match the object type of the parameter
- See Also
public void setPassword(String password) throws SQLExceptionSets 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
SQLException
if a database-access error occurs.
- See Also
public void setProviderUrl(String providerUrl) throws SQLExceptionSpecifies 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
public void setQueryTimeout(int seconds) throws DBException, SQLExceptionSets 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
SQLException
if a database-access error occurs.
- See Also
public synchronized void setTrace(boolean choice) throws SQLExceptionSets 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
- See Also
public void setTransactionIsolation(int level) throws DBException, SQLExceptionSets 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
SQLException
if a database-access error occurs.
- See Also
public void setUrl(String url) throws SQLExceptionSpecifies 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
SQLException
if a database-access error occurs.
- See Also
public void setUsername(String name) throws SQLExceptionSets the user name used to create a database connection.
- Parameters
- name - a user name
- Throws
SQLException
if a database-access error occurs.
- See Also
public void shareConnectionWith(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.
- Parameters
- statement - the DBStatement with which to share a Connection