#include <Connection.hpp>
Public Member Functions | |
Connection (ConnectionParameters &prms) throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) | |
Creates a new connection and connects to a controller with the given parameters. | |
virtual | ~Connection () |
Closes the connection and destroys its socket. | |
void | setAutoCommit (bool autoCommit) throw (SocketIOException, BackendException, ControllerException, ProtocolException, ConnectionException, UnexpectedException) |
If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. | |
void | commit () throw (SocketIOException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection . | |
void | rollback () throw (SocketIOException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Drops all changes made since the previous commit/rollback and releases any database locks currently held by this connection. | |
Statement * | createStatement () throw (SocketIOException, UnexpectedException) |
SQL statements without parameters are normally executed using Statement objects. | |
ParameterStatement * | createParameterStatement (const std::wstring &query) throw (SocketIOException, UnexpectedException) |
Creates a parameter statement. | |
void | deleteStatement (Statement *stPtr) throw (DriverException, UnexpectedException) |
Deletes given statement. | |
DriverResultSet * | statementExecuteQuery (RequestWithResultSetParameters &request) throw (SocketIOException, BackendException, DriverException, ControllerException, ProtocolException, NotImplementedException, ConnectionException, UnexpectedException) |
Performs a read request and returns the reply. | |
ResultAndWarnings | statementExecuteUpdate (Request &r) throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Performs a write request and return the number of rows affected. | |
ResultAndWarnings | statementExecute (RequestWithResultSetParameters &request) throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Calls a request that returns a list of results and the optionnal warnings. | |
ResultAndWarnings | statementExecuteUpdateWithKeys (Request &request) throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Performs a write request and returns the auto-generated keys. | |
void | closeRemoteResultSet (std::wstring cursorName) throw (SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException) |
Closes the remote ResultSet given its cursor name. | |
bool | isReadOnly () |
Tests to see if the connection is in read only Mode. | |
void | setReadOnly (bool readOnlyPrm) throw (SocketIOException, DriverException, UnexpectedException) |
A connection can be put in read-only mode as a hint to enable database optimizations. | |
void | tryFetchNext (const std::wstring &cursorName, int fetchSize) throw (ControllerException, SocketIOException, ProtocolException, BackendException, UnexpectedException) |
Sends "FetchNextResultSetRows" command to controller. | |
DriverResultSet * | preparedStatementGetMetaData (const std::wstring &sqlTemplate) throw (SocketIOException, BackendException, DriverException, ProtocolException, ControllerException, NotImplementedException, ConnectionException, UnexpectedException) |
Returns the metadata of the sql template as a resultset (which will contain the metadata). | |
SQLWarning * | getWarnings () throw (DriverException, UnexpectedException) |
Returns the first warning reported by calls on this connection. | |
void | clearWarnings () throw (DriverException, UnexpectedException) |
After this call, getWarnings() returns null until a new call to getWarnings() on this connection. | |
void | setAutoDeleteStatements (bool autoDelete) |
Avoids or forces deletion of statements in destructor Warning: Setting this option to false will make destructor leave all statements this instance created, which can lead to huge memory leaks. | |
bool | isClosed () const throw (UnexpectedException) |
Static Public Member Functions | |
static void | sendCommand (const DriverSocket &socket, int command) throw (SocketIOException, ProtocolException, UnexpectedException) |
Before sending a command code, checks that the controller is synchronized/ready to accept it. | |
static SQLWarning * | convertToSQLWarnings (BackendException *bde) |
Utility function to convert the given chain of backendException to a chain of SQLWarnings. | |
Protected Member Functions | |
void | getConnectionToNewController () throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) |
This function should be used to establish a new connection to another controller in the list. | |
void | connectToNextController () throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) |
Connects to the next controller (next according to the current controller pool). | |
void | finalizeConnect () throw (AuthenticationException, SocketIOException, VirtualDatabaseUnavailableException, UnexpectedException) |
Reads the controller acknowledgements and misc parameters that finish connection. | |
bool | close () |
Deletes all statements created by this connection and closes the socket to the connected controller. | |
void | closeSocket () |
Closes the socket by sending appropriate commands to the controller. | |
void | writeRequestOnStream (const Request &request) throw (SocketIOException, UnexpectedException) |
Serializes a write request on the output stream by sending only the needed parameters to reconstruct it on the controller. | |
void | checkIfConnected () const throw (SocketIOException, UnexpectedException) |
Handy method to call before any send/receive operation: throws and exception if the socket is not valid. | |
const DriverSocket & | getDriverSocket () |
Gets the driver socket for i/o operations. | |
Friends | |
bool | DriverResultSet::next () throw (SocketIOException, ControllerException, ProtocolException, BackendException, UnexpectedException) |
CarobNS::Connection::Connection | ( | ConnectionParameters & | prms | ) | throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) |
Creates a new connection and connects to a controller with the given parameters.
prms | controller, base, user, etc. to use for connecting |
DriverException | if the ConnectPolicy given in connection parameters is unknown or if the ConnectPolicy could not be created | |
ConnectionException | if the requested controller could not be reached | |
AuthenticationException | if a login error occured, or if an IO exception occured during authentication (premature close of connection) | |
VirtualDatabaseUnavailableException | if none of the remaining controllers has the desired vdb |
void CarobNS::Connection::checkIfConnected | ( | ) | const throw (SocketIOException, UnexpectedException) [protected] |
Handy method to call before any send/receive operation: throws and exception if the socket is not valid.
SocketIOException |
bool CarobNS::Connection::close | ( | ) | [protected] |
Deletes all statements created by this connection and closes the socket to the connected controller.
If an error occurs while closing, just logs the error and returns false, but does not throw any exception.
void CarobNS::Connection::closeRemoteResultSet | ( | std::wstring | cursorName | ) | throw (SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException) |
Closes the remote ResultSet given its cursor name.
cursorName | cursor name of the ResultSet to close |
SocketIOException | if an error occurs on the socket |
void CarobNS::Connection::closeSocket | ( | ) | [protected] |
Closes the socket by sending appropriate commands to the controller.
If an error occurs while closing, just logs the error and returns false, but does not throw any exception.
void CarobNS::Connection::commit | ( | ) | throw (SocketIOException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection
.
This method should only be used when auto-commit has been disabled. (If autoCommit
== true
, then we throw a DriverException).
DriverException | if connection is in autocommit mode |
void CarobNS::Connection::connectToNextController | ( | ) | throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) [protected] |
Connects to the next controller (next according to the current controller pool).
Retrieves a new controller by asking the controller pool, creates and connects a socket to this new controller, and registers the new socket to the policy. Then, tries to authenticate to the controller. Finally, creates the connection with the given parameters.
Upon IOException during connection, this function will mark the new controller as failing and try the next controller until NoMoreControllerException (which will be forwarded to caller)
If a VirtualDatabaseUnavailableException is thrown, the controller's vdb will be considered as down and the exception will be forwarded to caller.
AuthenticationException | if the authentication has failed | |
ConnectionException | if the requested controller could not be reached | |
NoMoreControllerException | if all controllers in the list are down | |
VirtualDatabaseUnavailableException | if the given vdb is not available on the new controller we are trying to connect to |
static SQLWarning* CarobNS::Connection::convertToSQLWarnings | ( | BackendException * | bde | ) | [static] |
Utility function to convert the given chain of backendException to a chain of SQLWarnings.
bde | exception chain to convert |
ParameterStatement* CarobNS::Connection::createParameterStatement | ( | const std::wstring & | query | ) | throw (SocketIOException, UnexpectedException) |
Creates a parameter statement.
query | a sql skeleton query |
ParameterStatement
object Statement* CarobNS::Connection::createStatement | ( | ) | throw (SocketIOException, UnexpectedException) |
SQL statements without parameters are normally executed using Statement
objects.
If the same SQL statement is executed many times, it is more efficient to use a ParameterStatement
. The ResultSet
will be TYPE_FORWARD_ONLY
/CONCUR_READ_ONLY
.
Statement
object void CarobNS::Connection::deleteStatement | ( | Statement * | stPtr | ) | throw (DriverException, UnexpectedException) |
Deletes given statement.
Only way to delete a statement (private dtor) so connection will keep the control of its statement and can remove it from its statement list. If the given statement pointer is NULL, don't do anything
stPtr | pointer to the statement to destroy |
DriverException | if the given statement is not in our list |
void CarobNS::Connection::finalizeConnect | ( | ) | throw (AuthenticationException, SocketIOException, VirtualDatabaseUnavailableException, UnexpectedException) [protected] |
Reads the controller acknowledgements and misc parameters that finish connection.
To be called only by connectToNextController()
AuthenticationException | if the controller did not acknowledge | |
SocketIOException | in case of i/o error during finalization | |
VirtualDatabaseUnavailableException | if the virtual database is not available on the controller |
void CarobNS::Connection::getConnectionToNewController | ( | ) | throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException) [protected] |
This function should be used to establish a new connection to another controller in the list.
It monitors "virtualdatabase not available" failures by calling connectToNextController() only a limited number of times (number = number of available controllers).
AuthenticationException | if the authentication has failed | |
DriverSQLException | if the connection cannot be established with the controller | |
VirtualDatabaseUnavailableException | if none of the remaining controllers has the desired vdb |
const DriverSocket& CarobNS::Connection::getDriverSocket | ( | ) | [inline, protected] |
Gets the driver socket for i/o operations.
SQLWarning* CarobNS::Connection::getWarnings | ( | ) | throw (DriverException, UnexpectedException) |
Returns the first warning reported by calls on this connection.
Subsequent warnings will be chained to this SQLWarning
Note: If the 'persistent connections' option is set to false, this function will always return null.
DriverException | if a database access error occurs or this method is called on a closed connection |
bool CarobNS::Connection::isClosed | ( | ) | const throw (UnexpectedException) |
bool CarobNS::Connection::isReadOnly | ( | ) | [inline] |
Tests to see if the connection is in read only Mode.
Note that we cannot really put the database in read only mode, but we pretend we can by returning the value of the readOnly
flag.
true
if the connection is read only DriverResultSet* CarobNS::Connection::preparedStatementGetMetaData | ( | const std::wstring & | sqlTemplate | ) | throw (SocketIOException, BackendException, DriverException, ProtocolException, ControllerException, NotImplementedException, ConnectionException, UnexpectedException) |
Returns the metadata of the sql template as a resultset (which will contain the metadata).
sqlTemplate | sql template of the PreparedStatement |
void CarobNS::Connection::rollback | ( | ) | throw (SocketIOException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Drops all changes made since the previous commit/rollback and releases any database locks currently held by this connection.
If the connection was in autocommit mode, we throw a DriverException.
DriverException | if the connection is in autocommit mode |
static void CarobNS::Connection::sendCommand | ( | const DriverSocket & | socket, | |
int | command | |||
) | throw (SocketIOException, ProtocolException, UnexpectedException) [static] |
Before sending a command code, checks that the controller is synchronized/ready to accept it.
Then sends it.
socket | on which to read and write | |
command | to send |
IOException | on socket error | |
ProtocolException | on protocol corruption |
void CarobNS::Connection::setAutoCommit | ( | bool | autoCommit | ) | throw (SocketIOException, BackendException, ControllerException, ProtocolException, ConnectionException, UnexpectedException) |
If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions.
Otherwise, its SQL statements are grouped into transactions that are terminated by either commit()or rollback(). By default, new connections are in auto-commit mode. The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet
, the statement completes when the last row of the ResultSet
has been retrieved or the ResultSet
has been closed.
autoCommit | true enables auto-commit; false disables it |
SocketIOException | if a database access error occurs |
void CarobNS::Connection::setAutoDeleteStatements | ( | bool | autoDelete | ) | [inline] |
Avoids or forces deletion of statements in destructor
Warning: Setting this option to false will make destructor leave all statements this instance created, which can lead to huge memory leaks.
.. use only if you know what you are doing!
NOT auto-deleting statements while using "setFetchSize()" streaming feature results in undefined behaviour.
Note: created statements can still be deleted using deleteStatement(Statement*)
autoDelete | if true (default), the destructor will clean-up all statements and associated ResultSets if false, the destructor will leave all statements open, leaving ownership to caller |
void CarobNS::Connection::setReadOnly | ( | bool | readOnlyPrm | ) | throw (SocketIOException, DriverException, UnexpectedException) |
A connection can be put in read-only mode as a hint to enable database optimizations.
readOnlyPrm | true enables read-only mode; false disables it |
DriverException | if transaction executes write requests |
ResultAndWarnings CarobNS::Connection::statementExecute | ( | RequestWithResultSetParameters & | request | ) | throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Calls a request that returns a list of results and the optionnal warnings.
This list is returned as a copy (ie. not a pointer) because it contains only lightweight elements (pointers or ints), so there is no heavy ResultSet copy.
request | the request to execute |
list
of ResultSetOrUpdateCount
elements SocketIOException | if an error occurs |
DriverResultSet* CarobNS::Connection::statementExecuteQuery | ( | RequestWithResultSetParameters & | request | ) | throw (SocketIOException, BackendException, DriverException, ControllerException, ProtocolException, NotImplementedException, ConnectionException, UnexpectedException) |
Performs a read request and returns the reply.
request | the read request with result set parameters to execute |
DriverResultSet
SocketIOException | if an error occurs on the socket |
ResultAndWarnings CarobNS::Connection::statementExecuteUpdate | ( | Request & | r | ) | throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Performs a write request and return the number of rows affected.
r | the write request to execute |
SocketIOException | if an error occurs |
ResultAndWarnings CarobNS::Connection::statementExecuteUpdateWithKeys | ( | Request & | request | ) | throw (SocketIOException, BackendException, ControllerException, DriverException, ProtocolException, ConnectionException, UnexpectedException) |
Performs a write request and returns the auto-generated keys.
request | the write request to execute |
list
of 2 ResultSetOrUpdateCount
elements in which the first element is the update count returned by the executeUpdate execution, the second element being a DriverResultSet containing the autogenerated keys SocketIOException | if an error occurs |
void CarobNS::Connection::tryFetchNext | ( | const std::wstring & | cursorName, | |
int | fetchSize | |||
) | throw (ControllerException, SocketIOException, ProtocolException, BackendException, UnexpectedException) |
Sends "FetchNextResultSetRows" command to controller.
Throws a ControllerException if controller returns an error; else returns void and lets the caller receive its new rows by itself.
cursorName | name of the ResultSet cursor | |
fetchSize | number of rows to fetch |
ControllerException | if an error occurs |
void CarobNS::Connection::writeRequestOnStream | ( | const Request & | request | ) | throw (SocketIOException, UnexpectedException) [protected] |
Serializes a write request on the output stream by sending only the needed parameters to reconstruct it on the controller.
request | the write request to send |
SocketIOException | when an error occured on the stream |