public abstract class DBConnection
extends java.lang.Object
This class contains the methods for performing basic database operations (insert, update, and so on) on the database to which this object is connected. All of these methods use the abstract method execSQL to perform their work.
The lifetime of a DBConnection object is determined by parameters set in DBConnectionManager when a DBConnection object is instantiated.
Any subclasses that you derive from this class should implement the following methods:Constructor and Description |
---|
DBConnection() |
Modifier and Type | Method and Description |
---|---|
Values |
call(java.lang.String proc,
Values data)
Calls the specified SQL stored procedure.
|
Values |
call(java.lang.String proc,
Values[] sig,
Values data,
boolean paramsByOrder)
Calls the specified SQL stored procedure with the specified signature.
|
Values |
call(java.lang.String proc,
Values data,
boolean paramsByOrder)
Calls the specified SQL stored procedure, fetching parameter values by name or order, as specified.
|
void |
clearCatSchemDefaults()
Resets (clears) the current default catalog and schema settings.
|
void |
clearTransaction()
Voids the current transaction without performing a rollback or a commit.
|
void |
close()
Closes this connection to the database.
|
void |
commit()
Permanently commits the database operations that have been performed since the last startTransaction and ends the transaction.
|
Values |
delete(java.lang.String table,
Values criteria)
Removes all rows from the specified table that meet the given criteria.
|
Values |
execSQL(java.lang.String sql)
Executes the specified SQL statement and returns the results in a Values object.
|
Values |
execSQL(java.lang.String sql,
java.lang.Object[] params,
int[] paramTypes)
Executes the specified SQL statement using host variables from a specified Object [].
|
abstract Values |
execSQL(java.lang.String sql,
java.lang.Object[] params,
int[] paramTypes,
boolean processEscapes)
Executes the specified SQL statement using host variables from a specified Object [] and optionally processes embedded escape sequences.
|
java.lang.String |
getPassword()
Returns the password for this DBConnection object.
|
Values |
getProcInfo(java.lang.String proc)
Returns the signature of a specified stored procedure.
|
Values |
getProcInfo(java.lang.String catalog,
java.lang.String schemaPattern,
java.lang.String proc)
Returns the signatures for the stored procedure matching the specified catalog, schema, and procedure name criteria.
|
Values |
getProcs()
Returns a list of stored procedures that exist in the database.
|
Values |
getProcs(java.lang.String catalog,
java.lang.String schemaPattern,
java.lang.String procNamePattern)
Returns a list of stored procedures matching the specified catalog, schema, and procedure name criteria.
|
Values |
getTableInfo(java.lang.String table)
Returns column information about a specific table.
|
Values |
getTableInfo(java.lang.String catalog,
java.lang.String schemaPattern,
java.lang.String table,
java.lang.String colNamePattern)
Returns information (name, type, and so forth) about the columns in a table matching the specified catalog, schema, and column name criteria.
|
Values |
getTables()
Returns a list of all tables in the database to which this DBConnection object is connected.
|
Values |
getTables(java.lang.String catalog,
java.lang.String schemaPattern,
java.lang.String tableNamePattern,
java.lang.String[] tableTypes)
Returns a list of tables matching the specified catalog, schema, table name, and table type criteria.
|
java.lang.String |
getUrl()
Returns the URL of the database to which this DBConnection object is connected.
|
java.lang.String |
getUser()
Returns the user name for this DBConnection object.
|
Values |
insert(java.lang.String table,
Values[] data,
boolean rollbackOnFail)
Inserts one or more rows in the specified table.
|
Values |
insert(java.lang.String table,
Values data,
boolean rollbackOnFail)
Inserts one row in the specified table.
|
Values |
query(java.lang.String table,
Values criteria)
Executes the specified query and returns the set of rows matching the given criteria.
|
void |
rollback()
Reverses all database operations that have been performed since the last startTransaction and ends that transaction.
|
void |
setCatSchemDefaults(java.lang.String catalog,
java.lang.String schemaPattern)
Sets the default catalog and schema values for methods that take catalog and schema parameters.
|
void |
startTransaction()
Starts a transaction.
|
Values |
update(java.lang.String table,
Values criteria,
Values set)
Updates all rows in the specified table that meet the given criteria.
|
public final java.lang.String getUrl()
public final java.lang.String getUser()
public final java.lang.String getPassword()
public void close()
public Values insert(java.lang.String table, Values data, boolean rollbackOnFail)
table
- A String specifying the table into which you want to insert a row.data
- A Values object containing the data that you want to insert. The keys in this object represent column names.rollbackOnFail
- A boolean specifying whether the change is to be rolled back if a failure occurs while inserting the row.
Set rollbackOnFail to
|
To
|
true | Undo change on failure |
false | Do no transaction management operation on success or failure |
public Values insert(java.lang.String table, Values[] data, boolean rollbackOnFail)
table
- A String specifying the table into which you want to insert rows.data
- A Values [] containing the data that you want inserted, where keys specify column names and values specify the data that is to be inserted into those columns. The first object in the array establishes the column names that this method will use for every member of the array, so the data structure of all members in the array must be identical.rollbackOnFail
- A boolean specifying whether the changes are to be rolled back if a failure occurs while inserting a row.
Set rollbackOnFail to
|
To
|
true | Undo change on failure |
false | Do no transaction management operation on success or failure |
Key |
Description |
$updateCount | Number of rows this method successfully inserted. |
$failCount | Number of rows this method failed to insert. |
$errors | An array of IData objects, containing an entry for each error that occurred. |
public Values delete(java.lang.String table, Values criteria)
Note: If you do not specify any criteria, all rows are deleted from the table.
table
- A String specifying the table from which you want to delete rows.criteria
- A Values object that specifies the criteria that must be met, where keys represent column names and values specify criteria.public Values update(java.lang.String table, Values criteria, Values set)
table
- A String specifying the table whose rows you want to update.criteria
- A Values object that specifies which rows are to be updated, where keys specify column names and values specify the criteria that a column must match.set
- A Values object containing the data that is to be written to rows matching criteria, where keys represent column names and values contain the data to be written into those columns.public Values query(java.lang.String table, Values criteria)
table
- A String specifying the table that you want to query.criteria
- A Values object that specifies which rows are to be returned, where keys specify column names and values specify the criteria that a column must match.Key |
Value |
results | A com.wm.util.Table containing the results of the query. |
$rowCount | Number of rows returned by the query. |
public Values call(java.lang.String proc, Values data)
Note: inout and out parameters are not supported at this time.
proc
- A String specifying the name of the stored procedure.data
- A Values object specifying the parameter values for the procedure.Key |
Value |
results | A com.wm.util.Table containing the results of the first result set returned by the stored procedure. |
$rowCount | Number of rows returned by the stored procedure. |
Or any errors encountered.
public Values call(java.lang.String proc, Values data, boolean paramsByOrder)
Note: inout and out parameters are not supported at this time.
proc
- A String specifying the name of the stored procedure.data
- A Values object containing the parameter values that are to be passed to the procedure.paramsByOrder
- A boolean specifying whether parameter values are to be retrieved from data by order or name.
Set paramsByOrder to
|
To
|
true | Access parameters by order |
false | Access parameters by name |
Key |
Value |
results | A com.wm.util.Table containing the results of the first result set returned by the stored procedure. |
$rowCount | Number of rows returned by the stored procedure. |
Or any errors encountered.
public Values call(java.lang.String proc, Values[] sig, Values data, boolean paramsByOrder)
Note: inout and out parameters are not supported at this time.
proc
- A String specifying the name of the stored procedure.sig
- A Values [] in which each member contains the following keys:
Key |
Value |
name | The name of the parameter ("RETURN_VALUE" for the return val). |
sqlType | The parameter's SQL type (e.g. "VARCHAR") |
direction | The parameter's purpose, which must be one of the following: - in - out - inout - return value |
Note: If you do not specify sig, the JDBC version will use DatabaseMetaData to retrieve parameter information and make the call.
data
- A Values object containing the parameter values that are to be passed to the procedure.paramsByOrder
- A boolean specifying whether parameter values are to be retrieved from data by order or name.
Set paramsByOrder to
|
To
|
true | Access parameters by order |
false | Access parameters by name |
Key |
Value |
results | A com.wm.util.Table containing the results of the first result set returned by the stored procedure. |
$rowCount | Number of rows returned by the stored procedure. |
Or any errors encountered.
public Values execSQL(java.lang.String sql)
sql
- A String specifying the SQL statement that you want to execute. (No parsing or checking is performed on this string.)
Note: inout and out parameters are not supported at this time.
Key |
Value |
results | A com.wm.util.Table containing the results of the first result set returned by the SQL statement (if the SQL statement produced a result set). |
$rowCount | Number of rows returned by the SQL statement. |
Or any errors encountered.
public Values execSQL(java.lang.String sql, java.lang.Object[] params, int[] paramTypes)
Note: inout and out parameters are not supported at this time.
sql
- A String specifying the SQL statement that you want to execute. (No parsing or checking is performed on this string.)params
- An Object [] containing the values that will be assigned to the host variables in the SQL statement.paramTypes
- A String [] specifying the SQL types in of the objects in params (using JDBC 1.2 type names; e.g., INTEGER, VARCHAR).Key |
Value |
results | A com.wm.util.Table containing the results of the first result set returned by the SQL statement (if the SQL statement produced a result set). |
$rowCount | Number of rows returned by the SQL statement. |
Or any errors encountered.
public abstract Values execSQL(java.lang.String sql, java.lang.Object[] params, int[] paramTypes, boolean processEscapes)
sql
- A String specifying the SQL statement that you want to execute. (No parsing or checking of this string is performed.)params
- An Object [] containing the values that will be assigned to the host variables ('?'s) in the SQL statement.paramTypes
- A String [] specifying the SQL types in of the objects in param (using JDBC 1.2 type names; e.g., INTEGER, VARCHAR).processEscapes
- A boolean specifying whether SQL escapes in the SQL statement are to be processed.
Set processEscapes to
|
To
|
true | Process SQL escapes |
false | Ignore SQL escapes |
Key |
Value |
results | A com.wm.util.Table containing the result set. |
$rowCount | Number of rows in the result set. |
public Values getTables()
Note: If catalog and schema defaults are set, they will automatically be applied to the search.
setCatSchemDefaults(java.lang.String, java.lang.String)
public Values getTables(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String tableNamePattern, java.lang.String[] tableTypes)
catalog
- A String specifying the catalog you want to search.schemaPattern
- A String specifying the schema whose tables you want information about. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.tableNamePattern
- A String specifying the table you want information about. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.tableTypes
- A String [] specifying the types of tables you want information about (e.g., TABLE, VIEW).public Values getTableInfo(java.lang.String table)
Note: If catalog and schema defaults are set, they will automatically be applied to the search.
table
- A String specifying the table about which you want information.setCatSchemDefaults(java.lang.String, java.lang.String)
public Values getTableInfo(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String table, java.lang.String colNamePattern)
catalog
- A String specifying the catalog that you want to search.schemaPattern
- A String specifying the schema whose tables you want information about. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.table
- A String specifying the name of the table for which you want information. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.colNamePattern
- A String specifying a column name. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.public Values getProcs()
Note: If catalog and schema defaults are set, they will automatically be applied to the search.
public Values getProcs(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String procNamePattern)
catalog
- A String specifying the catalog you want to search.schemaPattern
- A String specifying the schema whose procedures you want information about. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.procNamePattern
- A String specifying the name of the stored procedure about which you want information. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.public Values getProcInfo(java.lang.String proc)
proc
- A String specifying the name of the stored procedure about which you want information.
Note: If catalog and schema defaults are set, they will automatically be applied to the search.
setCatSchemDefaults(java.lang.String, java.lang.String)
public Values getProcInfo(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String proc)
catalog
- A String specifying the catalog that you want to search.schemaPattern
- A String specifying the schema whose stored procedures you want information about. If the database supports pattern matching on schemas, you may specify a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.proc
- A String specifying the name of the stored procedure whose signature you want.public void setCatSchemDefaults(java.lang.String catalog, java.lang.String schemaPattern)
catalog
- A String specifying the name of the database catalog to which the method will be applied.schemaPattern
- A String specifying the schema to which the method will be applied. If your database system supports pattern matching on schemas, you may use a pattern-matching string, where '%' matches one or more characters and a '_' matches one character.clearCatSchemDefaults()
public void clearCatSchemDefaults()
public void startTransaction() throws DBException
DBException
- If the database returns an error (most likely, because it doesn't support transaction processing).commit()
,
rollback()
,
clearTransaction()
public void commit() throws DBException
DBException
- If the database returns an error. This can happen if the database doesn't support transaction processing or if a transaction was never started.rollback()
,
startTransaction()
public void rollback() throws DBException
DBException
- If the database returns an error. This can happen if the database doesn't support transaction processing or if a transaction was never started.commit()
,
startTransaction()
public void clearTransaction() throws DBException
DBException
- If the database returns an error. This can happen if the database doesn't support transaction processing or if a transaction was never started.startTransaction()
,
commit()
,
rollback()