#include <Connection.hpp>
Public Member Functions | |
Connection (ConnectionParameters &prms) throw (DriverException, ConnectionException, AuthenticationException, 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, ControllerException, ProtocolException, NotImplementedException, ConnectionException, UnexpectedException) |
Performs a read request and returns the reply. | |
ResultAndWarnings | statementExecuteUpdate (Request &r) throw (SocketIOException, BackendException, ControllerException, ProtocolException, ConnectionException, UnexpectedException) |
Performs a write request and return the number of rows affected. | |
ResultAndWarnings | statementExecute (RequestWithResultSetParameters &request) throw (SocketIOException, BackendException, ControllerException, ProtocolException, ConnectionException, UnexpectedException) |
Calls a request that returns a list of results and the optionnal warnings. | |
ResultAndWarnings | statementExecuteUpdateWithKeys (Request &request) throw (SocketIOException, BackendException,ControllerException, 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, 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. | |
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 | initConnection () throw (DriverException, ConnectionException, AuthenticationException, UnexpectedException) |
Starts a connection by sending all connection/authentication informations. | |
void | finalizeConnect () throw (ConnectionException, AuthenticationException, 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. | |
bool | 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 (DriverException, ConnectionException, AuthenticationException, 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 parameters is unknown | |
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) |
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::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::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 |
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 ParameterStatement* CarobNS::Connection::createParameterStatement | ( | const std::wstring & | query | ) | throw (SocketIOException, UnexpectedException) |
Creates a parameter statement.
query | a sql skeleton query |
ParameterStatement
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 |
DriverResultSet* CarobNS::Connection::statementExecuteQuery | ( | RequestWithResultSetParameters & | request | ) | throw (SocketIOException, BackendException, 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, 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::statementExecute | ( | RequestWithResultSetParameters & | request | ) | throw (SocketIOException, BackendException, ControllerException, 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 |
ResultAndWarnings CarobNS::Connection::statementExecuteUpdateWithKeys | ( | Request & | request | ) | throw (SocketIOException, BackendException,ControllerException, 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::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 |
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 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 |
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 |
DriverResultSet* CarobNS::Connection::preparedStatementGetMetaData | ( | const std::wstring & | sqlTemplate | ) | throw (SocketIOException, BackendException, 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 |
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 |
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 |
void CarobNS::Connection::initConnection | ( | ) | throw (DriverException, ConnectionException, AuthenticationException, UnexpectedException) [protected] |
Starts a connection by sending all connection/authentication informations.
Warning: this function only sends the connection infos, but there is no guaranty that we are connected afterwards. finalizeConnect() will do the job of checking and finishing connection establishment.
DriverException | if the connect policy is NULL | |
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) |
void CarobNS::Connection::finalizeConnect | ( | ) | throw (ConnectionException, AuthenticationException, UnexpectedException) [protected] |
Reads the controller acknowledgements and misc parameters that finish connection.
initConnection() must be called before this
ConnectionException | if the virtual database is not available on the controller | |
AuthenticationException | if the controller did not acknowledge or in case of i/o exception during finalization (premature close of connection)s |
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.
bool 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::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 |
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 |
const DriverSocket& CarobNS::Connection::getDriverSocket | ( | ) | [inline, protected] |
Gets the driver socket for i/o operations.