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:
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. | ||||
DriverResultSet * | executeQuery (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) | |||
| ||||
DriverResultSet * | getResultSet () 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. | ||||
ResultSetMetaData * | getMetaData () 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. | ||||
SQLWarning * | getWarnings () 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. | ||||
Connection * | getConnectionPtr () | |||
Returns the pointer to the connection that created us. | ||||
bool | execute (const std::wstring &skeleton, const std::wstring ¶meters) throw (DriverException, SocketIOException, BackendException, ControllerException, ProtocolException, NotImplementedException, UnexpectedException) | |||
Convenience method for derived class ParameterStatement. | ||||
DriverResultSet * | executeQuery (const std::wstring &skeleton, const std::wstring ¶meters) 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< ResultSetOrUpdateCount > | resultList | |||
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. |
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.
CarobNS::Statement::Statement | ( | Connection * | c | ) | [protected] |
Constructs a Statement with the given connection.
Protected access so that only Connection class can create a statement
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.
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.
sql | SQL statement to set before executing |
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.
sql | SQL statement to set before executing. Typically a static SQL SELECT statement |
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
sql | SQL statement to set before executing |
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.
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.
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)
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 |
true
if the next result is a ResultSet
object; false
if it is an update count or there are no more results 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.
int CarobNS::Statement::getQueryTimeout | ( | ) | const [inline] |
The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
void CarobNS::Statement::setQueryTimeout | ( | int | seconds | ) | throw (DriverException, UnexpectedException) |
Sets the number of seconds the driver will wait for a Statement
object to execute.
seconds | the new query timeout limit in seconds; 0 means no timeout |
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.
rows | number of rows that should be fetched from the database |
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.
name | the new cursor name |
int CarobNS::Statement::getResultSetType | ( | ) | const [inline] |
Retrieves the type of the generated ResultSet
.
TYPE_FORWARD_ONLY
or TYPE_SCROLL_INSENSITIVE
DriverResultSet* CarobNS::Statement::getResultSet | ( | ) | const [inline] |
Returns the current result as a DriverResultSet
pointer.
int CarobNS::Statement::getResultSetConcurrency | ( | ) | const [inline] |
Retrieves the concurrency mode for the ResultSet
.
CONCUR_READ_ONLY
or CONCUR_UPDATABLE
void CarobNS::Statement::setResultSetConcurrency | ( | int | value | ) | throw (DriverException, UnexpectedException) |
Sets the concurrency mode for the ResultSet
.
value | an int value CONCUR_READ_ONLY or CONCUR_UPDATABLE |
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.
void CarobNS::Statement::setMaxRows | ( | int | max | ) | throw (DriverException, UnexpectedException) |
Sets the maximum number of rows that any ResultSet
can contain.
max | the new max rows limit; 0 means unlimited |
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.
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).
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.
sql | string containing the sql statement |
SQLWarning* CarobNS::Statement::getWarnings | ( | ) | throw (DriverException, UnexpectedException) |
Gets the SQL warnings associated to this statement.
void CarobNS::Statement::setReadRequestParameters | ( | RequestWithResultSetParameters & | request | ) | [protected] |
Sets the maxRows, fetchSize and cursorName values of this Statement in the given request.
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
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.
skeleton | SQL skeleton statement | |
parameters | SQL parameters serialized into a string |
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.
skeleton | SQL skeleton statement | |
parameters | SQL parameters serialized into a string |
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.
skeleton | SQL skeleton statement | |
serializedParameters | SQL parameters serialized into a string |
friend class DriverResultSet [friend] |
DriverResultSet must inform us when it is destroyed.
Let's allow it to reset the resultPtr