CarobNS::DriverResultSet Class Reference

A ResultSet provides access to a table of data generated by executing a Statement. More...

#include <DriverResultSet.hpp>

List of all members.

Public Member Functions

 DriverResultSet (Connection *conn) throw (ProtocolException, SocketIOException, NotImplementedException, UnexpectedException)
 Creates a DriverResultSet by deserializing infos from the given connection.
virtual ~DriverResultSet ()
 Frees dynamically allocated fields.
 operator std::wstring ()
 Cast to wstring.
bool next () throw (SocketIOException, ControllerException, ProtocolException, BackendException, UnexpectedException)
 A ResultSet is initially positioned before its first row, the first call to next makes the first row the current row; the second call makes the second row the current row, etc.
std::wstring getString (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the string value of a column in the current row only if the given column is of string type.
std::wstring getAsString (int columnIndex, const std::locale &loc=std::locale()) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as a wstring with the given locale.
int32_t getInt32 (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the 32bits integer value of a column in the current row only if the given column is of int type, throws an exception otherwise.
int getAsInt (int columnIndex) throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as an int.
int64_t getInt64 (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the 64bits integer value of a column in the current row only if the given column is of int type, throws an exception otherwise.
int64_t getAsInt64 (int columnIndex) throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as an int64.
uint64_t getAsUInt64 (int columnIndex) throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as an uint64.
float getFloat (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the float value of a column in the current row only if the given column is of float type, throws an exception otherwise.
float getAsFloat (int columnIndex) throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as a float.
double getDouble (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the double value of a column in the current row only if the given column is of double type, throws an exception otherwise.
double getAsDouble (int columnIndex) throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)
 Tries to get the value of a column in the current row as a double.
SQLTimeStamp getTimeStamp (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the timestamp value of a column in the current row only if the given column is of timestamp type, throws an exception otherwise.
LargeDatagetBlob (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the blob data value of a column in the current row only if the given column is of blob type, throws an exception otherwise.
LargeDatagetClob (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the clob data value of a column in the current row only if the given column is of blob type, throws an exception otherwise.
LargeDatagetByteArray (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the byte array value of a column in the current row only if the given column is of byte array type, throws an exception otherwise.
const BigDecimalgetBigDecimal (int columnIndex) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)
 Gets the bigdecimal value of a column in the current row only if the given column is of bigdecimal type, throws an exception otherwise.
void close () throw (SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Closes the remote ResultSet if the ResultSet was streamed else just closes the ResultSet locally.
int getNumberOfColumns ()
 Gets the number of column in this resultSet.
int getNumberOfRowsInMemory ()
 Gets the number of rows that have been fetched yet.
bool wasNull () const
 A column may have the value of SQL NULL; wasNull() reports whether the last column read had this special value.
bool isNull (int columnIndex) const throw (DriverException, UnexpectedException)
 A column may have the value of SQL NULL; isNull(int) reports whether the value at the given column and current row is NULL.
SQLWarninggetWarnings () throw (DriverException, UnexpectedException)
 Gets the SQL warnings associated to this ResultSet.
void setStatementWarnings (SQLWarning *stWarns)
 Sets the owning statement warnings.
SQLWarninggetStatementWarnings ()
 Retrieves the warnings linked to the owning statement.

Protected Member Functions

void receiveRows (const DriverSocket &socket) throw (SocketIOException, ProtocolException, UnexpectedException)
 De-serialize only data rows, not any metadata.
void setStatement (Statement *stmtPtr)
 Sets the statement.

Friends

class Statement
class ResultSetMetaData


Detailed Description

A ResultSet provides access to a table of data generated by executing a Statement.

The table rows are retrieved in sequence. Within a row its column values can be accessed in any order.

A ResultSet maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The 'next' method moves the cursor to the next row.

The getXXX methods retrieve column values for the current row. You can retrieve values either using the index number of the column, or by using the name of the column. In general using the column index will be more efficient. Columns are numbered from 1.

For maximum portability, ResultSet columns within each row should be read in left-to-right order and each column should be read only once.

Column names used as input to getXXX methods are case insensitive. When performing a getXXX using a column name, if several columns have the same name, then the value of the first matching column will be returned. The column name option is designed to be used when column names are used in the SQL Query. For columns that are NOT explicitly named in the query, it is best to use column numbers. If column names were used there is no way for the programmer to guarentee that they actually refer to the intended columns.

A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results.

The number, types and properties of a ResultSet's columns are provided by the ResultSetMetaData object returned by the getMetaData method.


Constructor & Destructor Documentation

CarobNS::DriverResultSet::DriverResultSet ( Connection conn  )  throw (ProtocolException, SocketIOException, NotImplementedException, UnexpectedException)

Creates a DriverResultSet by deserializing infos from the given connection.

Parameters:
conn connection from which to deserialize information
Exceptions:
ProtocolException if unexpected data is read
SocketIOException if an error occurs on the stream


Member Function Documentation

CarobNS::DriverResultSet::operator std::wstring (  ) 

Cast to wstring.

Handy for displaying the result set infos

bool CarobNS::DriverResultSet::next (  )  throw (SocketIOException, ControllerException, ProtocolException, BackendException, UnexpectedException)

A ResultSet is initially positioned before its first row, the first call to next makes the first row the current row; the second call makes the second row the current row, etc.

If an input stream from the previous row is open, it is implicitly closed. The ResultSet's warning chain is cleared when a new row is read

Returns:
true if the new current is valid; false if there are no more rows

std::wstring CarobNS::DriverResultSet::getString ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the string value of a column in the current row only if the given column is of string type.

Throws an exception otherwise. To get the value as a string anyway, use getAsString(int, const std::locale&)

Parameters:
columnIndex the first column is 1, the second is 2...
Returns:
the column value, null for SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

std::wstring CarobNS::DriverResultSet::getAsString ( int  columnIndex,
const std::locale &  loc = std::locale() 
) throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as a wstring with the given locale.

If the value at the given row/col is not of type string, tries to convert it using STL std::wostringstream conversion functions

Parameters:
columnIndex the first column is 1, the second is 2...
loc (optional) the locale to be used for string conversions. Ignored if the column is of type STRING
Returns:
the column value, null for SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL

int32_t CarobNS::DriverResultSet::getInt32 ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the 32bits integer value of a column in the current row only if the given column is of int type, throws an exception otherwise.

To get the value as an int anyway, use getAsInt(int)

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

int CarobNS::DriverResultSet::getAsInt ( int  columnIndex  )  throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as an int.

If the value at the given row/col is not of type int, tries to convert it using wstringToA conversion function.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL
ConversionException if the retrieved value cannot be converted to a float

int64_t CarobNS::DriverResultSet::getInt64 ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the 64bits integer value of a column in the current row only if the given column is of int type, throws an exception otherwise.

To get the value as an int64 anyway, use getAsInt64(int)

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

int64_t CarobNS::DriverResultSet::getAsInt64 ( int  columnIndex  )  throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as an int64.

If the value at the given row/col is not of type long, tries to convert it using wstringToA conversion function.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL
ConversionException if the retrieved value cannot be converted to an int64

uint64_t CarobNS::DriverResultSet::getAsUInt64 ( int  columnIndex  )  throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as an uint64.

If the value at the given row/col is not of type long, tries to convert it using wstringToA conversion function.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL
ConversionException if the retrieved value cannot be converted to an unsigned int64

float CarobNS::DriverResultSet::getFloat ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the float value of a column in the current row only if the given column is of float type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

float CarobNS::DriverResultSet::getAsFloat ( int  columnIndex  )  throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as a float.

If the value at the given row/col is not of type float or double, miserably fails TODO.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL
ConversionException if the retrieved value cannot be converted to a float

double CarobNS::DriverResultSet::getDouble ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the double value of a column in the current row only if the given column is of double type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

double CarobNS::DriverResultSet::getAsDouble ( int  columnIndex  )  throw (DriverException, NullValueException, ConversionException, NotImplementedException, UnexpectedException)

Tries to get the value of a column in the current row as a double.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value converted into a double
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
NullValueException if the retrieved value is NULL
ConversionException if the retrieved value cannot be converted to a double

SQLTimeStamp CarobNS::DriverResultSet::getTimeStamp ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the timestamp value of a column in the current row only if the given column is of timestamp type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

LargeData& CarobNS::DriverResultSet::getBlob ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException) [inline]

Gets the blob data value of a column in the current row only if the given column is of blob type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

LargeData& CarobNS::DriverResultSet::getClob ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException) [inline]

Gets the clob data value of a column in the current row only if the given column is of blob type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

LargeData& CarobNS::DriverResultSet::getByteArray ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException) [inline]

Gets the byte array value of a column in the current row only if the given column is of byte array type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

const BigDecimal& CarobNS::DriverResultSet::getBigDecimal ( int  columnIndex  )  throw (DriverException, NullValueException, NotImplementedException, UnexpectedException)

Gets the bigdecimal value of a column in the current row only if the given column is of bigdecimal type, throws an exception otherwise.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
the column value; NULL if SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds
DriverException if the column is not of type string
NullValueException if the retrieved value is NULL

int CarobNS::DriverResultSet::getNumberOfColumns (  )  [inline]

Gets the number of column in this resultSet.

Returns:
number of columns value

int CarobNS::DriverResultSet::getNumberOfRowsInMemory (  )  [inline]

Gets the number of rows that have been fetched yet.

Note: this is not the number of rows of the ResultSet, but the current number of rows in memory !

Returns:
number of rows fetched until now

bool CarobNS::DriverResultSet::wasNull (  )  const [inline]

A column may have the value of SQL NULL; wasNull() reports whether the last column read had this special value.

Note that you must first call getXXX on a column to try to read its value and then call wasNull() to find if the value was SQL NULL If you need to know if a value is NULL beforehand, use isNull(int)

Returns:
true if the last column read was SQL NULL
See also:
isNull(int) const

bool CarobNS::DriverResultSet::isNull ( int  columnIndex  )  const throw (DriverException, UnexpectedException)

A column may have the value of SQL NULL; isNull(int) reports whether the value at the given column and current row is NULL.

Parameters:
columnIndex the first column is 1, the second is 2,...
Returns:
true if the current row's value for the given column is SQL NULL
Exceptions:
DriverException if the ResultSet is closed or the cursor is out of bounds

SQLWarning* CarobNS::DriverResultSet::getWarnings (  )  throw (DriverException, UnexpectedException)

Gets the SQL warnings associated to this ResultSet.

Returns:
a SQL warning chain
Exceptions:
DriverException if the ResultSet is closed

void CarobNS::DriverResultSet::setStatementWarnings ( SQLWarning stWarns  )  [inline]

Sets the owning statement warnings.

Only fills statementWarnings field, does *not* set the owningStatement->warnings

Parameters:
stWarns the statement warnings to set

SQLWarning* CarobNS::DriverResultSet::getStatementWarnings (  )  [inline]

Retrieves the warnings linked to the owning statement.

Returns:
warnings on owning statement

void CarobNS::DriverResultSet::receiveRows ( const DriverSocket socket  )  throw (SocketIOException, ProtocolException, UnexpectedException) [protected]

De-serialize only data rows, not any metadata.

Parameters:
socket opened socket to controller
Exceptions:
SocketIOException stream error
ProtocolException protocol corruption

void CarobNS::DriverResultSet::setStatement ( Statement stmtPtr  )  [protected]

Sets the statement.

Parameters:
stmtPtr pointer to the statement to set


The documentation for this class was generated from the following file:
Generated on Tue Oct 24 09:05:38 2006 for Carob by  doxygen 1.5.0