CarobNS::ParameterStatement Class Reference

A SQL Statement template is stored in a ParameterStatement object. More...

#include <ParameterStatement.hpp>

Inheritance diagram for CarobNS::ParameterStatement:

CarobNS::Statement List of all members.

Public Member Functions

virtual void close ()
 Release objects and call Statement.close().
virtual void closeStatement ()
 Call Statement.close().
bool execute () throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException)
 Execute a SQL statement that may return multiple results.
DriverResultSetexecuteQuery () throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Executes a SQL statement that returns a single ResultSet.
int executeUpdate () throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Execute a SQL INSERT, UPDATE or DELETE statement.
void setNull (const int parameterIndex, const int sqlType) throw (DriverException, UnexpectedException)
 Sets a parameter to SQL NULL.
template<typename CParamType>
void setBoolean (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.
template<typename CParamType>
void setByte (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setShort (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setInt (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setLong (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setFloat (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setDouble (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setBigDecimal (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 
See also:
setBoolean()

template<typename CParamType>
void setString (int parameterIndex, const CParamType &x) throw (DriverException, UnexpectedException)
 Warning: setString (i, L"foo");.
void setByteArray (int parameterIndex, const void *buffer, size_t len) throw (DriverException, UnexpectedException)
 This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.
void setBlob (int parameterIndex, const void *buffer, size_t len) throw (DriverException, UnexpectedException)
 This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.
void clearParameters ()
 In general, parameter values remain in force for repeated used of a Statement.
 operator std::wstring ()
 Returns the SQL statement with the current template values substituted.
int getParameterCount ()
 Returns the parameter count.

Protected Member Functions

 ParameterStatement (Connection *c, const std::wstring &sqlStatement)
 Forbid construction to the rest of the world.
template<class T>
void set (const int paramIndex, const std::wstring &typeTag, const T &value) throw (DriverException, UnexpectedException)
 Actually stores the IN parameter into parameters String array.
virtual ~ParameterStatement ()
 Forbid destruction to the rest of the world.

Friends

class Connection
 Connection class must have access to at least constructor and destructor because only Connection can create statements.

Detailed Description

A SQL Statement template is stored in a ParameterStatement object.

This object can then be used to efficiently execute this statement multiple times with different parameters.

Note: The setXXX methods for setting IN parameter values must specify types that are compatible with the defined SQL type of the input parameter. For instance, if the IN parameter has SQL type Integer, then setInt should be used. open one exists.


Constructor & Destructor Documentation

CarobNS::ParameterStatement::ParameterStatement ( Connection c,
const std::wstring &  sqlStatement 
) [protected]

Forbid construction to the rest of the world.

ParameterStatements must be created by connection.

Parameters:
c the instantiating connection
sqlStatement the SQL statement with ? for IN markers

virtual CarobNS::ParameterStatement::~ParameterStatement (  )  [protected, virtual]

Forbid destruction to the rest of the world.

ParameterStatements must be deleted by connection.


Member Function Documentation

virtual void CarobNS::ParameterStatement::closeStatement (  )  [virtual]

Call Statement.close().

Will not release the objects. Call this member function only if you know what are you doing.

bool CarobNS::ParameterStatement::execute (  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) [inline]

Execute a SQL statement that may return multiple results.

Returns:
true if the result is a ResultSet or false if it is an integer
Exceptions:
DriverException if the statement is closed

DriverResultSet* CarobNS::ParameterStatement::executeQuery (  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException) [inline]

Executes a SQL statement that returns a single ResultSet.

Returns:
a ResulSet pointer that contains the data produced by the query
Exceptions:
DriverException if the statement is closed

int CarobNS::ParameterStatement::executeUpdate (  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException) [inline]

Execute a SQL INSERT, UPDATE or DELETE statement.

In addition SQL statements that return nothing such as SQL DDL statements can be executed

Returns:
either a row count, or 0 for SQL commands

void CarobNS::ParameterStatement::setNull ( const int  parameterIndex,
const int  sqlType 
) throw (DriverException, UnexpectedException)

Sets a parameter to SQL NULL.

Parameters:
parameterIndex the first parameter is 1, etc...
sqlType the SQL type code defined in TypeConstants. Note: For some databases this sqlType can be a dummy one (eg. you can always give type "SQLT_SMALLINT")

template<typename CParamType>
void CarobNS::ParameterStatement::setBoolean ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.

Some type conversions of the value may happen on the way (at different places) when called with a argument of a type different from the corresponding java type.

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setByte ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setShort ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setInt ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setLong ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setFloat ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setDouble ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setBigDecimal ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

See also:
setBoolean()

Parameters:
parameterIndex the first parameter is 1...
x the parameter value

template<typename CParamType>
void CarobNS::ParameterStatement::setString ( int  parameterIndex,
const CParamType &  x 
) throw (DriverException, UnexpectedException)

Warning: setString (i, L"foo");.

does not compile with gcc 4.0.2 because it searches the following instantiation: setString < wchar_t *> (int parameterIndex, const wchar_t * const& x);

which cannot exist. So you have to invoke the pointed-to-const instance: setString <const wchar_t *> (int parameterIndex, const wchar_t * const& x);

using a explicit instantiation like this: setString <const wchar_t *> (i, L"foo");

Or you can use this std::wstring alternative: setString (i, std::wstring(L"foo");

See also:
setBoolean()
Parameters:
parameterIndex the first parameter is 1...
x the parameter value

void CarobNS::ParameterStatement::setByteArray ( int  parameterIndex,
const void *  buffer,
size_t  len 
) throw (DriverException, UnexpectedException)

This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.

It will encode the buffer to Base64 after that will set the parameter as a string.

Parameters:
parameterIndex the first parameter is 1...
buffer the parameter value
len length of the buffer

void CarobNS::ParameterStatement::setBlob ( int  parameterIndex,
const void *  buffer,
size_t  len 
) throw (DriverException, UnexpectedException)

This JDBC call will be forwarded to the JDBC driver of the backend(s) of a sequoia controller.

It will encode the buffer to Base64 after that will set the parameter as a string.

Parameters:
parameterIndex the first parameter is 1...
buffer the parameter value
len length of the buffer

void CarobNS::ParameterStatement::clearParameters (  ) 

In general, parameter values remain in force for repeated used of a Statement.

Setting a parameter value automatically clears its previous value. However, in coms cases, it is useful to immediately release the resources used by the current parameter values; this can be done by calling clearParameters().

CarobNS::ParameterStatement::operator std::wstring (  )  [inline]

Returns the SQL statement with the current template values substituted.

Note: : This is identical to compileQuery() except instead of throwing SQLException if a parameter is null, it places ? instead.

Returns:
the SQL statement

int CarobNS::ParameterStatement::getParameterCount (  )  [inline]

Returns the parameter count.

Returns:
the number of ? in the statement

template<class T>
void CarobNS::ParameterStatement::set ( const int  paramIndex,
const std::wstring &  typeTag,
const T &  value 
) throw (DriverException, UnexpectedException) [protected]

Actually stores the IN parameter into parameters String array.

Called by most setXXX() methods.

Parameters:
paramIndex the index into the inString
typeTag the JDBC call that will be used by the controller
value the parameter
Exceptions:
DriverException if something goes wrong


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