CarobNS::Statement Class Reference

A Statement object is used for executing a static SQL statement and obtaining the results produced by it. More...

#include <Statement.hpp>

Inheritance diagram for CarobNS::Statement:

CarobNS::ParameterStatement List of all members.

Public Member Functions

bool execute (const std::wstring &sql) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException)
 Execute a SQL statement that may return multiple results.
DriverResultSetexecuteQuery (const std::wstring &sql) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException)
 Executes a SQL statement that returns a single ResultSet.
int executeUpdate (std::wstring sql) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Execute a SQL INSERT, UPDATE or DELETE statement.
bool moreResults () const
 Returns true if there are results available for retrieval with getMoreResults(), but does NOT move to the next result in the list.
bool getMoreResults () throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Return the true if next available result is a ResultSet or false it this is an update count.
bool getMoreResults (int current) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Moves to this Statement object's next result, deals with any current ResultSet object(s) according to the instructions specified by the given flag, and returns true if the next result is a ResultSet object.
int getUpdateCount () const
 Returns the current result as an update count, if the result is a ResultSet or there are no more results, -1 is returned.
int getQueryTimeout () const
 The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
void setQueryTimeout (int seconds) throw (DriverException, UnexpectedException)
 Sets the number of seconds the driver will wait for a Statement object to execute.
int getFetchSize () const
 Gets the fetch size.
void setFetchSize (int rows) throw (DriverException, UnexpectedException)
 Sets the default fetch size for the produced ResultSet.
void setCursorName (std::wstring name)
 Defines the SQL cursor name that will be used by subsequent execute methods.
int getResultSetType () const
 Retrieves the type of the generated ResultSet.
void setResultSetType (int value) throw (DriverException, UnexpectedException)
 
Parameters:
value an int value

DriverResultSetgetResultSet () const
 Returns the current result as a DriverResultSet pointer.
int getResultSetConcurrency () const
 Retrieves the concurrency mode for the ResultSet.
void setResultSetConcurrency (int value) throw (DriverException, UnexpectedException)
 Sets the concurrency mode for the ResultSet.
int getMaxRows () const
 The maxRows limit is set to limit the number of rows that any ResultSet can contain.
void setMaxRows (int max) throw (DriverException, UnexpectedException)
 Sets the maximum number of rows that any ResultSet can contain.
void setEscapeProcessing (bool enable)
 If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
virtual void close ()
 Remotely closes the current ResultSet if applicable and frees result memory.
ResultSetMetaDatagetMetaData () throw (SocketIOException, BackendException, ProtocolException, NotImplementedException, UnexpectedException)
 Returns the metadata of the current or future ResultSet.
void setRequest (const std::wstring &sql)
 Sets the sql request string.
SQLWarninggetWarnings () throw (DriverException, UnexpectedException)
 Gets the SQL warnings associated to this statement.

Protected Member Functions

 Statement (Connection *c)
 Constructs a Statement with the given connection.
void setReadRequestParameters (RequestWithResultSetParameters &request)
 Sets the maxRows, fetchSize and cursorName values of this Statement in the given request.
void removeResultSetFromList (DriverResultSet *drsPtr)
 Nulls the given resultSet in the resultList.
ConnectiongetConnectionPtr ()
 Returns the pointer to the connection that created us.
bool execute (const std::wstring &skeleton, const std::wstring &parameters) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException)
 Convenience method for derived class ParameterStatement.
DriverResultSetexecuteQuery (const std::wstring &skeleton, const std::wstring &parameters) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException)
 Convenience method for derived class ParameterStatement.
int executeUpdate (const std::wstring &skeleton, const std::wstring &serializedParameters) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)
 Convenience method for derived class ParameterStatement.
virtual ~Statement ()
 Forbid destruction to the rest of the world.

Protected Attributes

std::wstring sql_request
 Original, untouched request (only trimmed).
std::list< ResultSetOrUpdateCountresultList
 List of updateCount/ResultSet.
std::list< ResultSetOrUpdateCount
>::const_iterator 
resultListIterator
 Iterator on the list of results.

Friends

class Connection
 Connection class must have access to at least constructor and destructor because only Connection can create statements.
class DriverResultSet
 DriverResultSet must inform us when it is destroyed.

Detailed Description

A Statement object is used for executing a static SQL statement and obtaining the results produced by it.

Only one ResultSet per Statement can be open at any point in time. Therefore, if the reading of one ResultSet is interleaved with the reading of another, each must have been generated by different Statements. All Statements execute methods implicitly close a statement's current ResultSet if an open one exists.


Constructor & Destructor Documentation

CarobNS::Statement::Statement ( Connection c  )  [protected]

Constructs a Statement with the given connection.

Protected access so that only Connection class can create a statement

Parameters:
c pointer to connection that created us

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

Forbid destruction to the rest of the world.

Statements must be deleted by connection.

See also:
Connection::deleteStatement(Statement* stPtr)


Member Function Documentation

bool CarobNS::Statement::execute ( const std::wstring &  sql  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) [inline]

Execute a SQL statement that may return multiple results.

Parameters:
sql SQL statement to set before executing
Returns:
true if the result is a ResultSet or false if it is an integer
Exceptions:
DriverException if the statement is closed

DriverResultSet* CarobNS::Statement::executeQuery ( const std::wstring &  sql  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) [inline]

Executes a SQL statement that returns a single ResultSet.

Parameters:
sql SQL statement to set before executing. Typically a static SQL SELECT statement
Returns:
a ResulSet pointer that contains the data produced by the query
Exceptions:
DriverException if the statement is closed

int CarobNS::Statement::executeUpdate ( std::wstring  sql  )  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

Parameters:
sql SQL statement to set before executing
Returns:
either a row count, or 0 for SQL commands

bool CarobNS::Statement::moreResults (  )  const

Returns true if there are results available for retrieval with getMoreResults(), but does NOT move to the next result in the list.

Returns:
true if there are more results pending for retrieval.

bool CarobNS::Statement::getMoreResults (  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)

Return the true if next available result is a ResultSet or false it this is an update count.

If the result is false and getUpdateCount() returns -1 then there is no more result.

Move to the next result. Any open ResultSet is implicitly closed.

Returns:
true for a ResultSet, false for an updateCount or no more results

bool CarobNS::Statement::getMoreResults ( int  current  )  throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)

Moves to this Statement object's next result, deals with any current ResultSet object(s) according to the instructions specified by the given flag, and returns true if the next result is a ResultSet object.

There are no more results when the following is true:

(!getMoreResults() && (getUpdateCount() == -1)

Parameters:
current one of the following Statement constants indicating what should happen to current ResultSet objects obtained using the method getResultSet: CLOSE_CURRENT_RESULT, KEEP_CURRENT_RESULT, or CLOSE_ALL_RESULTS
Returns:
true if the next result is a ResultSet object; false if it is an update count or there are no more results
See also:
execute(const std::wstring &)

int CarobNS::Statement::getUpdateCount (  )  const [inline]

Returns the current result as an update count, if the result is a ResultSet or there are no more results, -1 is returned.

Returns:
the current result as an update count.

int CarobNS::Statement::getQueryTimeout (  )  const [inline]

The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.

Returns:
the current query timeout limit in seconds; 0 = unlimited

void CarobNS::Statement::setQueryTimeout ( int  seconds  )  throw (DriverException, UnexpectedException)

Sets the number of seconds the driver will wait for a Statement object to execute.

Parameters:
seconds the new query timeout limit in seconds; 0 means no timeout
Exceptions:
DriverException if the condition seconds >= 0 is not satisfied

void CarobNS::Statement::setFetchSize ( int  rows  )  throw (DriverException, UnexpectedException)

Sets the default fetch size for the produced ResultSet.

Parameters:
rows number of rows that should be fetched from the database
Exceptions:
DriverException if the condition 0 <= size <= getMaxRows() is not satisfied

void CarobNS::Statement::setCursorName ( std::wstring  name  )  [inline]

Defines the SQL cursor name that will be used by subsequent execute methods.

This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet generated by this statement. If a database doesn't support positioned update/delete, this method is a no-op.

Parameters:
name the new cursor name

int CarobNS::Statement::getResultSetType (  )  const [inline]

Retrieves the type of the generated ResultSet.

Returns:
one of TYPE_FORWARD_ONLY or TYPE_SCROLL_INSENSITIVE

DriverResultSet* CarobNS::Statement::getResultSet (  )  const [inline]

Returns the current result as a DriverResultSet pointer.

Returns:
pointer to the current result set; null if it is an update count or there are no more.

int CarobNS::Statement::getResultSetConcurrency (  )  const [inline]

Retrieves the concurrency mode for the ResultSet.

Returns:
CONCUR_READ_ONLY or CONCUR_UPDATABLE

void CarobNS::Statement::setResultSetConcurrency ( int  value  )  throw (DriverException, UnexpectedException)

Sets the concurrency mode for the ResultSet.

Parameters:
value an int value CONCUR_READ_ONLY or CONCUR_UPDATABLE
Exceptions:
DriverException if the input value is not valid

int CarobNS::Statement::getMaxRows (  )  const [inline]

The maxRows limit is set to limit the number of rows that any ResultSet can contain.

If the limit is exceeded, the excess rows are silently dropped.

Returns:
the current maximum row limit; zero means unlimited

void CarobNS::Statement::setMaxRows ( int  max  )  throw (DriverException, UnexpectedException)

Sets the maximum number of rows that any ResultSet can contain.

Parameters:
max the new max rows limit; 0 means unlimited
Exceptions:
DriverException if the condition max >= 0 is not satisfied

void CarobNS::Statement::setEscapeProcessing ( bool  enable  )  [inline]

If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.

Parameters:
enable true to enable; false to disable

virtual void CarobNS::Statement::close (  )  [virtual]

Remotely closes the current ResultSet if applicable and frees result memory.

In many cases, it is desirable to immediately release a Statement's database and JDBC resources instead of waiting for this to happen when it is automatically closed. The close method provides this immediate release.

Reimplemented in CarobNS::ParameterStatement.

ResultSetMetaData* CarobNS::Statement::getMetaData (  )  throw (SocketIOException, BackendException, ProtocolException, NotImplementedException, UnexpectedException)

Returns the metadata of the current or future ResultSet.

Note that if there is no ResultSet available yet (before execution), then this method will generate some network communication to the controller. No caching is performed here: before execution this network communication will happen at every call. Also consider bug SEQUOIA-262 (empty returned instead of null).

Returns:
a pointer to the metadata of this statement or of its resultset

void CarobNS::Statement::setRequest ( const std::wstring &  sql  )  [inline]

Sets the sql request string.

This is in total opposition with the JDBC API where request strings are not mutable, see CAROB-81.

Parameters:
sql string containing the sql statement

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

Gets the SQL warnings associated to this statement.

Returns:
a SQL warning chain

void CarobNS::Statement::setReadRequestParameters ( RequestWithResultSetParameters request  )  [protected]

Sets the maxRows, fetchSize and cursorName values of this Statement in the given request.

Parameters:
request on which to set parameters (unrelated to user parameters)

void CarobNS::Statement::removeResultSetFromList ( DriverResultSet drsPtr  )  [protected]

Nulls the given resultSet in the resultList.

This function is called by the driverResultSet destructor to inform that the give resultSet is beeing destroyed, so that any reference to it is not valid anymore

Parameters:
drsPtr pointer to the ResultSet that must be invalidated

bool CarobNS::Statement::execute ( const std::wstring &  skeleton,
const std::wstring &  parameters 
) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) [protected]

Convenience method for derived class ParameterStatement.

Parameters:
skeleton SQL skeleton statement
parameters SQL parameters serialized into a string
Returns:
true if the result is a ResultSet or false if it is an integer

DriverResultSet* CarobNS::Statement::executeQuery ( const std::wstring &  skeleton,
const std::wstring &  parameters 
) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) [protected]

Convenience method for derived class ParameterStatement.

Parameters:
skeleton SQL skeleton statement
parameters SQL parameters serialized into a string
Returns:
a ResulSet pointer that contains the data produced by the query

int CarobNS::Statement::executeUpdate ( const std::wstring &  skeleton,
const std::wstring &  serializedParameters 
) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException) [protected]

Convenience method for derived class ParameterStatement.

Parameters:
skeleton SQL skeleton statement
serializedParameters SQL parameters serialized into a string
Returns:
either a row count, or 0 for SQL commands


Friends And Related Function Documentation

friend class DriverResultSet [friend]

DriverResultSet must inform us when it is destroyed.

Let's allow it to reset the resultPtr


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