com.jcorporate.expresso.core.db
Class DBConnection

java.lang.Object
  com.jcorporate.expresso.core.db.DBConnection

public class DBConnection

extends Object

Generic database connection object - hides the implementation details of using jdbc and allows for JDBC message and exceptions to be handled better than by default. DBConnection's are also designed to be used in conjunction with connection pooling, and have special methods to support this.

Author:

Michael Nash

Field Summary

static String	DEFAULT_DB_CONTEXT_NAME Constant name for the 'Default' database context
static int	LIMITATION_AFTER_ORDER_BY Insert the limitation syntax after ORDER BY key words SELECT {COLUMNS}...
static int	LIMITATION_AFTER_SELECT Insert the limitation syntax after TABLE nomination SELECT {limitation-syntax} {COLUMNS}...
static int	LIMITATION_AFTER_TABLE Insert the limitation syntax after TABLE nomination SELECT {COLUMNS}...
static int	LIMITATION_AFTER_WHERE Insert the limitation syntax after WHERE key word SELECT {COLUMNS}...
static int	LIMITATION_DISABLED Limitation syntax database vendor specific optimisation is disabled author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
protected DBConnectionPool	parentPool The ConnectionPool that created this connection.
static int	TRANSACTION_DIRTY_MODE Uncommitted read transaction mode author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003
static int	TRANSACTION_EXCLUSIVE_MODE Serializable read transaction mode author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003
static int	TRANSACTION_NORMAL_MODE Committed read transaction mode author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003
static int	TRANSACTION_RESTRICTIVE_MODE Repeatable read transaction mode author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Constructor Summary

DBConnection(com.jcorporate.expresso.core.db.config.JDBCConfig newConfigJdbc)
Constructor Create a new connection object

DBConnection(String newDBDriver, String newDBURL, String newDBConnectFormat)
Constructor Create a new connection object

DBConnection(String newDBDriverType, String newDBDriver, String newDBURL, String newDBConnectFormat)
Constructor Create a new connection object

Method Summary

void	checkTimeOut() Checks if this connectino has timed out.
void	clear() Clear all result sets and statements associated with this connection
void	clearCallableStatement() Clear a callable statement associated with this record.
void	clearPreparedStatement() Clear a prepared statement associated with this record.
void	commit() Send a COMMIT to the database, closing the current transaction If the database driver claims it doesn't support transactions, then we skip this.
void	connect(JndiDataSource newJndiDS) Connect to the database, ready to execute statements
void	connect(String newLogin, String newPassword) Connect to the database, ready to execute statements
void	connectionSetup(String newDBDriverType, String newDBDriver, String newDBURL, String newDBConnectFormat) Sets up the connection whether JDBC or JNDI Datasources
CallableStatement	createCallableStatement(String sqlString) Creates a CallableStatment object.
PreparedStatement	createPreparedStatement(String sqlString) Creates a PreparedStatment object.
Statement	createStatement() Return a Statement object from this connection - for compatibility with the DBConnection object in Turbine
void	disconnect() Close the connection to the database
void	execute() Execute the actual query Queries executed by this method are expected to return a result - use executeUpdate for queries that do not.
void	execute(String theSQL) One-step execute that sets the query on the fly NOTE: Do not use for UPDATE or DELETE, use executeUpdate instead This method throws DBException if no result set is returned
void	executeProcedure() Execute the actual store procedure in callableStatment Store procedures method are expected to return a result - use executeUpdate for queries that do not.
void	executeUpdate(String theSQL) One-step executeUpdate - for statements that don't return a result set No result set is expected from this method, but the getUpdateCount() method can be called to see how many rows were affected
void	finalize() Disconnect abandoned connections
boolean	first() Scroll to the first record in the result set
boolean	getAutoCommit() Return the state of the auto-commit flag
BigDecimal	getBigDecimal(int fieldNum) Retrieves a BigDecimal object from the resultset
InputStream	getBinaryStream(int fieldNum) Retrieves a Large object as a binary stream.
InputStream	getBinaryStream(String fieldName) Retrieves a Large object as a binary stream.
Blob	getBlob(int fieldNum) Retrieves a BLOB object from the result set.
Blob	getBlob(String fieldName) Retrieves a BLOB object from the result set.
byte[]	getBytes(int fieldNum) Get the BLOB bytes for this particular dataset row.
String	getCatalog() Return the Catalog for the current connection
Clob	getClob(int fieldNum) Retrieves a BLOB object from the result set.
Clob	getClob(String fieldName) Retrieves a BLOB object from the result set.
Connection	getConnection() Low level function that allows you to retrieve the JDBC connection associated with this DBConnection.
long	getCreatedTime() Retrieve the time that this connection was created in System time.
String	getDataContext() Retrieve the data context name we're associated with
Date	getDate(int fieldNum) Return the value in the named field as a string, trimming off any trailing whitespace
Date	getDate(String fieldName) Return the value in the named field as a string, trimming off any trailing whitespace
String	getDateTimeType() getDateTimeType allows DBObjects to ask what the correct database type is for date/time values
String	getDBDriver() Send back the name of the JDBC driver class being used to access the database
DatabaseMetaData	getDBMetaData() Return the DatabaseMetaData for the connection
String	getDBName() Returns the name of the currently set DataContext
String	getDBURL() Return the URL field for this connection
String	getDescription() Returns the text description of this connection.
double	getDouble(int fieldNum) Fetch the given field of the current row as a double
EscapeHandler	getEscapeHandler() Gets the Escape Handler class for this connection
Hashtable	getFields(String tableName) Deprecated. Use getFieldsMap() instead
HashMap	getFieldsMap(String tableName) Get a hashtable that contains a set of field/type values for the given table
int	getId() Get's the id of this connection.
boolean	getImmortal() Gets whether or not if this connection times out.
int	getInt(int fieldNum) Fetch the given field of the current row as an integer
com.jcorporate.expresso.core.db.config.JNDIConfig	getJNDIConfig(com.jcorporate.expresso.core.db.config.JDBCConfig curConfig)
long	getLastTouched() getLastTouched method is used to tell when the last time a connection was used.
int	getLimitationPosition() programmatically gets the limitation optimisation insertion position author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001
String	getLimitationSyntax() programmatically gets the limitation syntax string
String	getLogin() Return the login name used to connect to the database
long	getLong(int fieldNum) Fetch the given field of the current row as a long
ResultSetMetaData	getMetaData() Return the ResultSetMetaData from the last executed query
DBConnectionPool	getParentPool() Retrieve what DBConnectionPool 'owns' this pool
String	getPassword() Return the password string being used to connect to the database
ResultSet	getResultSet() Retrieve the current result set in the connection.
String	getSQL() Gets the SQL string to be executed
String	getString(int fieldNum) Return the value in the numbered field as a string, trimming off any trailing whitespace
String	getString(String fieldName) Return the value in the named field as a string, trimming off any trailing whitespace
String	getStringNoTrim(int fieldNum) Return the numbered field as a string, not trimming any trailing spaces
String	getStringNoTrim(String fieldName) Return the value in the named field as a string
Date	getTime(int fieldNum) Return the value in the named field as a string, trimming off any trailing whitespace
Date	getTime(String fieldName) Return the value in the named field as a string, trimming off any trailing whitespace
Date	getTimestamp(int fieldNum) Return the value in the named field as a string, trimming off any trailing whitespace
Date	getTimestamp(String fieldName) Return the value in the named field as a string, trimming off any trailing whitespace
int	getTransactionMode() Return the Database current transaction mode set.
Hashtable	getTypeMap() Attempt to return a mapping of java.sql.Type types to actual type names used by this database.
int	getUpdateCount() Returns the number of rows affected by the last operation .
Enumeration	getWildCards() Deprecated. 9/04, v5.5+ use DBConnectionPool.getDefaultWildCards() instead
ArrayList	getWildCardsList() Deprecated. 9/04, v5.5+ use DBConnectionPool.getDefaultWildCards() instead
boolean	isAvailable() When this connection is used as part of a pool of connections, tell whether or not it is available to be re-allocated
boolean	isClosed() When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated
boolean	isStringNotTrim() Trim or not trim parameter set for this connection
boolean	isTransactionNotActive() Trim or not trim parameter set for this connection
boolean	next() Scroll to the next record in the result set
void	release() Releases the DBConnection back into the parent DBConnectionPool.
void	rollback() Roll back the current transaction, as if it were never requested.
void	setAutoCommit(boolean b) Set auto-commit on or off for this connection.
void	setAvailable(boolean newAvailable) When this connection is used as part of a pool of connections, tell whether or not it is available to be re-allocated
void	setDataContext(String newDBName) Sets the data context for the connection.
void	setDateTimeType(String newDateTimeType) setDateTimeType method allows the default database type of "datetime" to be overridden for databases where this is not the type for date and time values (e.g.
void	setDBName(String newDBName) Sets the data context for the connection.
void	setDescription(String newDescription) Set a description for this database connection.
void	setEscapeHandler(EscapeHandler newValue) Sets the Escape Handler class for this connection
void	setImmortal(boolean newImmortal) Sets this connection to be immortal, ie it never gets removed or disconnected
void	setJDBCCondig(com.jcorporate.expresso.core.db.config.JDBCConfig config)
void	setParentPool(DBConnectionPool newParentPool) Sets the parentPool... this is done by the DBConnecitonPool object.
void	setSQL(String sqlStatement) Set the SQL to be run against the database
void	setTransactionCommittedMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionIsolation(int isolationMode) Set Database transaction isolation mode.
void	setTransactionMode(int transactionMode) Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionRepeatableMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionSerializableMode() Set EXPRESSO transaction mode for the current DBConnection.
void	setTransactionUncommittedMode() Set EXPRESSO transaction mode for the current DBConnection.
boolean	supportsTransactions() Checks if the Database Metadata claims that this database supports transactions.
void	touch() Update the last touched date/time for this connection

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DB_CONTEXT_NAME

public static final String DEFAULT_DB_CONTEXT_NAME

Constant name for the 'Default' database context

See Also:

Constant Field Values

LIMITATION_DISABLED

public static final int LIMITATION_DISABLED

Limitation syntax database vendor specific optimisation is disabled

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

See Also:

Constant Field Values

LIMITATION_AFTER_TABLE

public static final int LIMITATION_AFTER_TABLE

Insert the limitation syntax after TABLE nomination SELECT {COLUMNS}... FROM {TABLE} {limitation-syntax} [ WHERE {where_clause}... ] [ ORDER BY {order_by_clause}... ]

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

See Also:

Constant Field Values

LIMITATION_AFTER_WHERE

public static final int LIMITATION_AFTER_WHERE

Insert the limitation syntax after WHERE key word SELECT {COLUMNS}... FROM {TABLE} [ WHERE {where_clause}... ] AND {limitation-syntax} [ ORDER BY {order_by_clause}... ]

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

See Also:

Constant Field Values

LIMITATION_AFTER_ORDER_BY

public static final int LIMITATION_AFTER_ORDER_BY

Insert the limitation syntax after ORDER BY key words SELECT {COLUMNS}... FROM {TABLE} [ WHERE {where_clause}... ] [ ORDER BY {order_by_clause}... ] {limitation-syntax}

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

See Also:

Constant Field Values

LIMITATION_AFTER_SELECT

public static final int LIMITATION_AFTER_SELECT

Insert the limitation syntax after TABLE nomination SELECT {limitation-syntax} {COLUMNS}... FROM {TABLE} [ WHERE {where_clause}... ] [ ORDER BY {order_by_clause}... ]

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

See Also:

Constant Field Values

TRANSACTION_NORMAL_MODE

public static final int TRANSACTION_NORMAL_MODE

Committed read transaction mode

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3

See Also:

Constant Field Values

TRANSACTION_DIRTY_MODE

public static final int TRANSACTION_DIRTY_MODE

Uncommitted read transaction mode

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3

See Also:

Constant Field Values

TRANSACTION_RESTRICTIVE_MODE

public static final int TRANSACTION_RESTRICTIVE_MODE

Repeatable read transaction mode

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3

See Also:

Constant Field Values

TRANSACTION_EXCLUSIVE_MODE

public static final int TRANSACTION_EXCLUSIVE_MODE

Serializable read transaction mode

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Since:

Expresso 5.3

See Also:

Constant Field Values

parentPool

protected DBConnectionPool parentPool

The ConnectionPool that created this connection.

Constructor Detail

DBConnection

public DBConnection(String newDBDriver,
                    String newDBURL,
                    String newDBConnectFormat)
             throws DBException

Constructor Create a new connection object

Parameters:

newDBDriver - The class name of the JDBC driver to use for this connection

newDBURL - The URL passed to the driver to connect to the database

newDBConnectFormat - The style or format of the call to actually connect to the database. The options are as follows:

1. 1: Create the connection with a call to DriverManager.getConnection(dbURL, login, password) where login and password are the supplied login name and password
2. 2: Create the connection with a call to DriverManager.getConnection(dbURL + "?user=" + login + ";password=" + password) where login and password are the supplied login and password
3. 3: Create the connection by setting the login and password into a properties object and calling DriverManager.getConnection(dbURL, props) where props is the created properties object
4. 4: Create the connection with a string like DriverManager.getConnection(dbURL + "?user=" + newLogin + "&password=" + newPassword)

Throws:

DBException - If the information provided cannot be used to create a new connection

DBConnection

public DBConnection(com.jcorporate.expresso.core.db.config.JDBCConfig newConfigJdbc)
             throws DBException

Constructor Create a new connection object

Parameters:

newConfigJdbc - The JDBC driver configuration retrieve from the context

Throws:

DBException - If the information provided cannot be used to create a new connection

DBConnection

public DBConnection(String newDBDriverType,
                    String newDBDriver,
                    String newDBURL,
                    String newDBConnectFormat)
             throws DBException

Constructor Create a new connection object

Parameters:

newDBDriverType - The JDBC driver Type name to use for this connection

newDBDriver - The class name of the JDBC driver to use for this connection

newDBURL - The URL passed to the driver to connect to the database

newDBConnectFormat - The style or format of the call to actually connect to the database. The options are as follows:

1. 1: Create the connection with a call to DriverManager.getConnection(dbURL, login, password) where login and password are the supplied login name and password
2. 2: Create the connection with a call to DriverManager.getConnection(dbURL + "?user=" + login + ";password=" + password) where login and password are the supplied login and password
3. 3: Create the connection by setting the login and password into a properties object and calling DriverManager.getConnection(dbURL, props) where props is the created properties object
4. 4: Create the connection with a string like DriverManager.getConnection(dbURL + "?user=" + newLogin + "&password=" + newPassword)

Throws:

DBException - If the information provided cannot be used to create a new connection

Method Detail

connectionSetup

public void connectionSetup(String newDBDriverType,
                            String newDBDriver,
                            String newDBURL,
                            String newDBConnectFormat)
                     throws DBException

Sets up the connection whether JDBC or JNDI Datasources

Parameters:

newDBDriverType - The driver type, either "e;datasource"e; or another name if you want a straight JDBC Driver

newDBDriver - The driver name

newDBURL - the URL of the database driver

newDBConnectFormat - The connection format. See the DBConnection constructors for more information on what this paramter means.

Throws:

DBException

checkTimeOut

public void checkTimeOut()
                  throws DBException

Checks if this connectino has timed out.

Throws:

DBException

clear

public void clear()
           throws DBException

Clear all result sets and statements associated with this connection

Throws:

DBException

commit

public void commit()
            throws DBException

Send a COMMIT to the database, closing the current transaction If the database driver claims it doesn't support transactions, then we skip this.

Throws:

DBException - If the commit does not succeed

connect

public void connect(String newLogin,
                    String newPassword)
             throws DBException

Connect to the database, ready to execute statements

Parameters:

newLogin - Login user name to connect with

newPassword - Password to connect with

Throws:

DBException - If the connection does not succeed

connect

public void connect(JndiDataSource newJndiDS)
             throws DBException

Connect to the database, ready to execute statements

Parameters:

newJndiDS - a configuration bean describing the connection datasource properties.

Throws:

DBException - If the connection does not succeed author Yves Henri AMAIZO (Creation)

Since:

Expresso 5.0

createStatement

public Statement createStatement()

Return a Statement object from this connection - for compatibility with the DBConnection object in Turbine

Returns:

The fully created statement

createPreparedStatement

public PreparedStatement createPreparedStatement(String sqlString)

Creates a PreparedStatment object.

Parameters:

sqlString - The string to create the prepared statement with.

Returns:

an instantiated prepared statement, that you then modify for your various parameters May return null if an exception occurred

clearPreparedStatement

public void clearPreparedStatement()

Clear a prepared statement associated with this record.

createCallableStatement

public CallableStatement createCallableStatement(String sqlString)

Creates a CallableStatment object.

Parameters:

sqlString - The string to create the callable statement with.

Returns:

an instantiated callable statement, that you then modify for your various parameters May return null if an exception occurred

clearCallableStatement

public void clearCallableStatement()

Clear a callable statement associated with this record.

disconnect

public void disconnect()
                throws DBException

Close the connection to the database

Throws:

DBException - If the connection could not be closed successfully.

execute

public void execute()
             throws DBException

Execute the actual query Queries executed by this method are expected to return a result - use executeUpdate for queries that do not.

Throws:

DBException - If the query fails or is an update query.

execute

public void execute(String theSQL)
             throws DBException

One-step execute that sets the query on the fly NOTE: Do not use for UPDATE or DELETE, use executeUpdate instead This method throws DBException if no result set is returned

Parameters:

theSQL - An SQL statement to be executed on the database

Throws:

DBException

executeUpdate

public void executeUpdate(String theSQL)
                   throws DBException

One-step executeUpdate - for statements that don't return a result set No result set is expected from this method, but the getUpdateCount() method can be called to see how many rows were affected

Parameters:

theSQL - The SQL Statement to be executed. May be null if you're executing a prepared statement

Throws:

DBException - If the update fails

executeProcedure

public void executeProcedure()
                      throws DBException

Execute the actual store procedure in callableStatment Store procedures method are expected to return a result - use executeUpdate for queries that do not.

Throws:

DBException - If the query fails or is an update query.

finalize

public void finalize()

Disconnect abandoned connections

first

public boolean first()
              throws DBException

Scroll to the first record in the result set

Returns:

boolean True for success, False for failure (e.g. end of set)

Throws:

DBException - If the database connection returns an error

getAutoCommit

public boolean getAutoCommit()
                      throws DBException

Return the state of the auto-commit flag

Returns:

boolean True if auto-commit is enabled, false if it is not

Throws:

DBException - If the current state of auto-commit cannot be determined due to an invalid connection or other database error.

getCatalog

public String getCatalog()
                  throws DBException

Return the Catalog for the current connection

Returns:

Catalog the name of the current catalog

Throws:

DBException

getClob

public Clob getClob(int fieldNum)
             throws DBException

Retrieves a BLOB object from the result set.

Important Note: Unlike any of the other data types, You must be finished with BLOBs and CLOBs before closing the connection or moving on to other result sets

Parameters:

fieldNum - The field number [ie order in the resultset]

Returns:

java.sql.Blob data type

Throws:

DBException - upon error retrieving the BLOB data type.

getClob

public Clob getClob(String fieldName)
             throws DBException

Retrieves a BLOB object from the result set.

Important Note: Unlike any of the other data types, You must be finished with BLOBs and CLOBs before closing the connection or moving on to other result sets

Parameters:

fieldName - The field name to retrieve

Returns:

java.sql.Blob data type

Throws:

DBException - upon error retrieving the BLOB data type.

getCreatedTime

public long getCreatedTime()

Retrieve the time that this connection was created in System time.

Returns:

long integer.

getBigDecimal

public BigDecimal getBigDecimal(int fieldNum)
                         throws DBException

Retrieves a BigDecimal object from the resultset

Parameters:

fieldNum - the column index

Returns:

java.math.BigDecimal object for the field

Throws:

DBException - upon error accessing the object

getBlob

public Blob getBlob(int fieldNum)
             throws DBException

Retrieves a BLOB object from the result set.

Important Note: Unlike any of the other data types, You must be finished with BLOBs and CLOBs before closing the connection or moving on to other result sets

Parameters:

fieldNum - The field number [ie order in the resultset]

Returns:

java.sql.Blob data type

Throws:

DBException - upon error retrieving the BLOB data type.

getBlob

public Blob getBlob(String fieldName)
             throws DBException

Retrieves a BLOB object from the result set.

Important Note: Unlike any of the other data types, You must be finished with BLOBs and CLOBs before closing the connection or moving on to other result sets

Parameters:

fieldName - The field name to retrieve

Returns:

java.sql.Blob data type

Throws:

DBException - upon error retrieving the BLOB data type.

getBinaryStream

public InputStream getBinaryStream(String fieldName)
                            throws DBException

Retrieves a Large object as a binary stream.

Parameters:

fieldName - the name of the field to retrieve

Returns:

java.io.InputStream

Throws:

DBException - if there's an error retrieving from the database

getBinaryStream

public InputStream getBinaryStream(int fieldNum)
                            throws DBException

Retrieves a Large object as a binary stream.

Parameters:

fieldNum - the number of the field to retrieve

Returns:

java.io.InputStream

Throws:

DBException - if there's an error retrieving from the database

getBytes

public byte[] getBytes(int fieldNum)
                throws DBException

Get the BLOB bytes for this particular dataset row.

Parameters:

fieldNum - The number in the row to retrieve

Returns:

an array of bytes.

Throws:

DBException - upon error accessing the stream

getDateTimeType

public String getDateTimeType()

getDateTimeType allows DBObjects to ask what the correct database type is for date/time values

Returns:

The date time datatype as String

getConnection

public Connection getConnection()

Low level function that allows you to retrieve the JDBC connection associated with this DBConnection. This allows you to do several fancy things that would not normally happen within Expresso itself such as prepared statements, and other low level entities.

NOTE: Once you grab the connection yourself, you are on your own as far as the framework is concerned. It doesn't help you to get your connection back in place. So, for example, if you close the connection manually, it will mess up the connection pool. Or if you fail to free a prepared statement, it will register as a resource leak. Be sure to restore your connection to pristine order before releasing this DBConnection back into the pool.

Returns:

a java.sql.Connection JDBC connection.

getDBDriver

public String getDBDriver()

Send back the name of the JDBC driver class being used to access the database

Returns:

String The name of the driver class being used to connect to the database.

getDBMetaData

public DatabaseMetaData getDBMetaData()
                               throws DBException

Return the DatabaseMetaData for the connection

Returns:

DatabaseMetaData The meta-data object for the connection

Throws:

DBException

supportsTransactions

public boolean supportsTransactions()
                             throws DBException

Checks if the Database Metadata claims that this database supports transactions.

Note: Because MySQL supports tables in one database which support tranactions and those that do not, this will return true even if the transaction is not supported.

Returns:

true if the database driver supports transactions. With this check you should be able to call setAutoCommit(false).

Throws:

DBException

getDBURL

public String getDBURL()

Return the URL field for this connection

Returns:

String The URL to connect to the database

getDescription

public String getDescription()

Returns the text description of this connection. When the connection is put in use by a client program a description is set, this method retrieves the description.

Returns:

String A text description of this database connection's purpose

getDouble

public double getDouble(int fieldNum)
                 throws DBException

Fetch the given field of the current row as a double

Parameters:

fieldNum - The number of the field to return

Returns:

double The double value of the given field number

Throws:

DBException - if no such field or some other JDBC error

getFields

public Hashtable getFields(String tableName)
                    throws DBException

Deprecated. Use getFieldsMap() instead

Get a hashtable that contains a set of field/type values for the given table

Parameters:

tableName - Name of the table to read fields for

Returns:

Hashtable A hashtable containing field names & types

Throws:

DBException - If the given table cannot be scanned for it's fields.

getEscapeHandler

public EscapeHandler getEscapeHandler()

Gets the Escape Handler class for this connection

Returns:

the new EscapeHandler compliant interface

getFieldsMap

public HashMap getFieldsMap(String tableName)
                     throws DBException

Get a hashtable that contains a set of field/type values for the given table

Parameters:

tableName - Name of the table to read fields for

Returns:

Hashtable A hashtable containing field names & types

Throws:

DBException - If the given table cannot be scanned for it's fields.

getId

public int getId()

Get's the id of this connection. For use in the DBConnectionPool

Returns:

the connection id.

getImmortal

public boolean getImmortal()

Gets whether or not if this connection times out.

Returns:

true if this connection does not time out.

getInt

public int getInt(int fieldNum)
           throws DBException

Fetch the given field of the current row as an integer

Parameters:

fieldNum - The number of the desired field

Returns:

int The integer value of the field

Throws:

DBException - If an error occurrs accessing the value

getLastTouched

public long getLastTouched()

getLastTouched method is used to tell when the last time a connection was used. This can help determine if it should be dropped from a connection pool.

Returns:

Calendar Calendar object indicating the last time this connection was actually used to communicate with the database

getLimitationPosition

public int getLimitationPosition()

programmatically gets the limitation optimisation insertion position

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Returns:

Integer code for the limitation position

Since:

Expresso 4.0

getLimitationSyntax

public String getLimitationSyntax()

programmatically gets the limitation syntax string

Returns:

the LimitationSyntax String author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Since:

Expresso 4.0

getLogin

public String getLogin()

Return the login name used to connect to the database

Returns:

String The login name being used to connect to the database

getLong

public long getLong(int fieldNum)
             throws DBException

Fetch the given field of the current row as a long

Parameters:

fieldNum - The long value of the given field number

Returns:

long The specified field's value

Throws:

DBException - if no such field or some other JDBC error

getMetaData

public ResultSetMetaData getMetaData()

Return the ResultSetMetaData from the last executed query

Returns:

ResultSetMetaData The meta-data object from the last query

getPassword

public String getPassword()

Return the password string being used to connect to the database

Returns:

String The password being used to connect to the database

getResultSet

public ResultSet getResultSet()

Retrieve the current result set in the connection.

Like any of the lower level methods such as getConnection(), be careful with what you do with the ResultSet or you may leave the entire Connection Pool in an undefined state

You do not have to explicitly close the ResultSet when you're done with it because DBConnectionPool.release(DBConnection) will explicitly clear all resultsets

Returns:

java.sql.ResultSet or possibly null if there is currently no result set.

getSQL

public String getSQL()

Gets the SQL string to be executed

Returns:

The SQL String to be executed.

getString

public String getString(int fieldNum)
                 throws DBException

Return the value in the numbered field as a string, trimming off any trailing whitespace

Parameters:

fieldNum - The desired field number

Returns:

String The value of the field as a string, less any trailing whitespace

Throws:

DBException - If the value cannot be accessed

getStringNoTrim

public String getStringNoTrim(int fieldNum)
                       throws DBException

Return the numbered field as a string, not trimming any trailing spaces

Parameters:

fieldNum - The number of the desired field

Returns:

String The string field value

Throws:

DBException - If an error occurrs accessing the given field

getString

public String getString(String fieldName)
                 throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldName - The desired column name

Returns:

String The value of the field as a string, less any trailing whitespace

Throws:

DBException - If the value cannot be accessed

getStringNoTrim

public String getStringNoTrim(String fieldName)
                       throws DBException

Return the value in the named field as a string

Parameters:

fieldName - The desired column name

Returns:

String The value of the field as a string, less any trailing whitespace

Throws:

DBException - If the value cannot be accessed

getTimestamp

public Date getTimestamp(String fieldName)
                  throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldName - The desired column name

Returns:

Date The value of the field as a Date format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getTimestamp

public Date getTimestamp(int fieldNum)
                  throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldNum - The desired column number

Returns:

Date The value of the field as a Date format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getTime

public Date getTime(String fieldName)
             throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldName - The desired column name

Returns:

Date The value of the field as a Time format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getTime

public Date getTime(int fieldNum)
             throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldNum - The desired column number

Returns:

Date The value of the field as a Time format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getDate

public Date getDate(String fieldName)
             throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldName - The desired column name

Returns:

Date The value of the field as a Time format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getDate

public Date getDate(int fieldNum)
             throws DBException

Return the value in the named field as a string, trimming off any trailing whitespace

Parameters:

fieldNum - The desired column name

Returns:

Date The value of the field as a Time format

Throws:

DBException - If the value cannot be accessed author Yves Henri AMAIZO

Since:

Expresso 5.0

getTypeMap

public Hashtable getTypeMap()

Attempt to return a mapping of java.sql.Type types to actual type names used by this database. If we encounter any error doing this, simply return an empty hashtable

Returns:

a Hashtable of the type map.

getUpdateCount

public int getUpdateCount()

Returns the number of rows affected by the last operation . Only useful after an executeUpdate

Returns:

int: The integer count of the number of rows affected

getWildCards

public Enumeration getWildCards()

Deprecated. 9/04, v5.5+ use DBConnectionPool.getDefaultWildCards() instead

Return a vector of wild card characters for this database type. This can be used to determine if the search criteria supplied by a user has wild-card characters in it or is an exact match

Returns:

Enumeration A list of the wild-card characters used by this database connection

getWildCardsList

public ArrayList getWildCardsList()

Deprecated. 9/04, v5.5+ use DBConnectionPool.getDefaultWildCards() instead

Return a vector of wild card characters for this database type. This can be used to determine if the search criteria supplied by a user has wild-card characters in it or is an exact match.

Returns:

A list of the wild-card characters used by this database connection

getTransactionMode

public int getTransactionMode()
                       throws DBException

Return the Database current transaction mode set.

author Yves Henri AMAIZO, Mon Dec 22 10:30:59 2003

Returns:

Expresso corrresponding values.

Throws:

DBException

Since:

Expresso 5.3

isAvailable

public boolean isAvailable()

When this connection is used as part of a pool of connections, tell whether or not it is available to be re-allocated

Returns:

boolean True if the connection is available for use, false if it is in use already

isClosed

public boolean isClosed()
                 throws DBException

When this connection has lost its connection to the server, tell whether or not it is available to be re-allocated

Returns:

boolean True if the connection has been lost, false if it is still usable

Throws:

DBException

next

public boolean next()
             throws DBException

Scroll to the next record in the result set

Returns:

boolean: true if scrolled successfully, false if end of record set

Throws:

DBException - If a JDBC error occurred while scrolling

rollback

public void rollback()
              throws DBException

Roll back the current transaction, as if it were never requested. If the JDBC driver claims it doesn't support transactions, then this method is a NOOP except for touching the connection

Throws:

DBException - If the rollback encounters an error

setAutoCommit

public void setAutoCommit(boolean b)
                   throws DBException

Set auto-commit on or off for this connection. If auto-commit is on, each statement is immediately written to the database and cannot be rolled back

Parameters:

b - True to enable auto-commit, false to disable it

Throws:

DBException - upon error

setAvailable

public void setAvailable(boolean newAvailable)

When