public class DBCSQLQuery
extends java.lang.Object
Creating an instance of this class results in the creation of a new connection to the database (or the reuse of an existing idle connection if available in the connection pool).
To query the database, ie, a SELECT statement, or any other statement that returns a resultset,
use the open(java.lang.String)
function. For INSERT, UPDATE, DELETE and other statements
that do not return a resultset, use execSql(java.lang.String)
Once the open function is successfully called, the cursor is positioned on the first record of the resultset. This is in contrast to jdbc, which positions the cursor prior to the first record.
The isEOF()
function determines whether another record is present after
the current record.
The next()
function moves the cursor to the next record, while first()
positions the cursor onto the first record of the resultset.
The get
Constructor and Description |
---|
DBCSQLQuery()
This constructor creates a DBCSQLQuery object using the default target.
|
DBCSQLQuery(DBCSQLConnection paDBConnection)
This constructor creates a DBCSQLQuery object using the specified connection.
|
DBCSQLQuery(DBCSQLConnectionTarget paTarget)
This constructor creates a DBCSQLQuery object using the specified target.
|
DBCSQLQuery(I_djSQLQuery realquery)
This constructor is for internal use and should not be used by developers.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
This function closes the internal resultset.
|
boolean |
execSql(java.lang.String paSql)
This function executes an sql statement that does not return a resultset.
|
void |
first()
Positions the cursor on the first record of the resultset.
|
void |
free()
Relinquishes the database connection, ie, sends the connection back to the connection
pool provided it is not being shared with another DBCSQLQuery.
|
java.sql.Blob |
getBlob(java.lang.String paColumnName) |
boolean |
getBoolean(java.lang.String paColumnName)
Gets the data of the specified column/field as a boolean value.
|
byte |
getByte(java.lang.String paColumnName)
Gets the data of the specified column/field as a byte value.
|
java.sql.Clob |
getClob(java.lang.String paColumnName) |
int |
getColumnCount()
Gets the number of columns in the resultset.
|
java.lang.String |
getColumnName(int paColumnIndex)
Gets the name of the nth column in the resultset.
|
int |
getColumnType(int paColumnIndex)
Gets the type of the nth column in the resultset.
|
java.util.Date |
getDate(java.lang.String paColumnName)
Gets the data of the specified column/field as a Date value.
|
DBCSQLConnection |
getDBConnection()
Gets the internal connection associated with this query.
|
double |
getDouble(java.lang.String paColumnName)
Gets the data of the specified column/field as an double value.
|
float |
getFloat(java.lang.String paColumnName)
Gets the data of the specified column/field as a float value.
|
int |
getInt(java.lang.String paColumnName)
Gets the data of the specified column/field as an int value.
|
long |
getLong(java.lang.String paColumnName)
Gets the data of the specified column/field as an long value.
|
int |
getNoOfRecordsAffected()
Returns the number of records that were updated or deleted by the last UPDATE or
DELETE statement executed through this object's execSql function.
|
int |
getRecordCount()
Gets the number of records in the resultset.
|
java.lang.String |
getString(java.lang.String paColumnName)
Gets the data of the specified column/field as a String.
|
void |
gotoRecordForRowNo(int paRowNo)
Navigates to the nth record of the resultset.
|
boolean |
isEOF()
Call this function to determine whether the cursor is on the last record of the resultset.
|
boolean |
next()
Positions the cursor on the next record of the resultset, unless there are no more
records, or the resultset is empty.
|
boolean |
open(java.lang.String paSql)
This function executes an sql statement that returns a resultset.
|
boolean |
open(java.lang.String paSql,
boolean paOldStyle)
The same features as the
open(String) except the inclusion of the paOldStyle parameter. |
public DBCSQLQuery() throws java.sql.SQLException
The object extracts a connection from the connection pool for the targetted database, or creates a new one if no free connections are available.
java.sql.SQLException
- On errors in creating a database connection or setup.public DBCSQLQuery(DBCSQLConnectionTarget paTarget) throws java.sql.SQLException
The object extracts a connection from the connection pool for the targetted database, or creates a new one if no free connections are available.
paTarget
- The target to which this object will query.java.sql.SQLException
- On errors in creating a database connection or setup.public DBCSQLQuery(DBCSQLConnection paDBConnection) throws java.sql.SQLException
The object uses the passed connection, thereby not extracting a connection from the connection pool.
If the connection was taken from another DBCSQLQuery object, then they both share the same connection, which is useful for database-level locking.
paDBConnection
- The DBCSQLConnection which this object will use to query the database.java.sql.SQLException
public DBCSQLQuery(I_djSQLQuery realquery)
public void free()
It is highly recommended that applications call this function once they are done using this object.
public boolean execSql(java.lang.String paSql) throws java.sql.SQLException
Typically, this function will be used for DELETE and UPDATE statements. INSERT can also be carried
out through this, but the DBCSQLInsert
object is more suited to inserts.
paSql
- The sql statement to be executed.java.sql.SQLException
- On any errors in the sql execution, including invalid sql statements.public boolean open(java.lang.String paSql) throws java.sql.SQLException
Typically, this function will be used for SELECT statements.
On a successful execution, the result is stored in the object, and the cursor is positioned on the first record
of the resultset. Fields in the current record can be accessed through the getXXX functions, like the
getString(String)
or getInt(String)
functions.
Navigation through the other records is accomplished through the next()
function,
while isEOF()
and getRecordCount()
are helper functions.
paSql
- The sql statement to be executed.java.sql.SQLException
- On any errors in the sql execution, including invalid sql statements.public boolean open(java.lang.String paSql, boolean paOldStyle) throws java.sql.SQLException
open(String)
except the inclusion of the paOldStyle parameter.paOldStyle
- Passing true to this param creates the internal statement using the default jdbc parameters.
Features like getRecordCount()
will not be available if queried in this fashion.
The query parameters when paOldStyle is false are TYPE_SCROLL_INSENSITIVE and CONCUR_READ_ONLY. The new style allows us to scroll forwards and backwards through the resultset, which is required for paging. So if using paging, set paOldStyle to false.
java.sql.SQLException
public void close()
free()
.Data-access on this object after a close() has been called will result in an exception.
public java.lang.String getString(java.lang.String paColumnName) throws java.sql.SQLException
Note that the function is guaranteed to always return a valid string, never a null. A null value in the database is returned as a blank string.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public boolean getBoolean(java.lang.String paColumnName) throws java.sql.SQLException
The function returns true if the column contains a string value of 'T' or 'Y', case-insensitive. In all other cases, except exceptions, the function returns false.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public int getInt(java.lang.String paColumnName) throws java.sql.SQLException
It will return 0 if called on a field that holds a null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public long getLong(java.lang.String paColumnName) throws java.sql.SQLException
It will return 0 if called on a field that holds a null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public double getDouble(java.lang.String paColumnName) throws java.sql.SQLException
It will return 0 if called on a field that holds a null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public byte getByte(java.lang.String paColumnName) throws java.sql.SQLException
It will return 0 if called on a field that holds a null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public float getFloat(java.lang.String paColumnName) throws java.sql.SQLException
It will return 0 if called on a field that holds a null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public java.util.Date getDate(java.lang.String paColumnName) throws java.sql.SQLException
Returns a Date object with the internal value 0 (ie, the epoch) if the field data is null.
paColumnName
- The name of the column, case-insensitive.java.sql.SQLException
public java.sql.Blob getBlob(java.lang.String paColumnName) throws java.sql.SQLException
java.sql.SQLException
public java.sql.Clob getClob(java.lang.String paColumnName) throws java.sql.SQLException
java.sql.SQLException
public boolean isEOF()
It returns true in the following cases:
public boolean next() throws java.sql.SQLException
false if there are no more records.
java.sql.SQLException
public int getNoOfRecordsAffected()
public DBCSQLConnection getDBConnection()
DBCSQLQuery(DBCSQLConnection)
so that multiple queries can be performed on the same connection, and usually, in the same transaction.public int getColumnCount() throws java.sql.SQLException
java.sql.SQLException
public java.lang.String getColumnName(int paColumnIndex) throws java.sql.SQLException
getColumnCount()
java.sql.SQLException
public int getColumnType(int paColumnIndex) throws java.sql.SQLException
getColumnCount()
.
Refer to the JDBC reference for the meaning of the returned value.java.sql.SQLException
public int getRecordCount() throws java.sql.SQLException
Note that this operation may be slow on large resultsets.
This is also not available if the query was opened with the paOldStyle parameter true.
java.sql.SQLException
public void first() throws java.sql.SQLException
java.sql.SQLException
public void gotoRecordForRowNo(int paRowNo) throws java.sql.SQLException
java.sql.SQLException