CarobNS::Connection Class Reference

This class implements the communication protocol to the Controller. More...

#include <Connection.hpp>

List of all members.

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.
StatementcreateStatement () throw (SocketIOException, UnexpectedException)
 SQL statements without parameters are normally executed using Statement objects.
ParameterStatementcreateParameterStatement (const std::wstring &query) throw (SocketIOException, UnexpectedException)
 Creates a parameter statement.
void deleteStatement (Statement *stPtr) throw (DriverException, UnexpectedException)
 Deletes given statement.
DriverResultSetstatementExecuteQuery (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.
DriverResultSetpreparedStatementGetMetaData (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).
SQLWarninggetWarnings () 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 SQLWarningconvertToSQLWarnings (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 DriverSocketgetDriverSocket ()
 Gets the driver socket for i/o operations.

Friends

bool DriverResultSet::next () throw (SocketIOException, ControllerException, ProtocolException, BackendException, UnexpectedException)


Detailed Description

This class implements the communication protocol to the Controller.


Constructor & Destructor Documentation

CarobNS::Connection::Connection ( ConnectionParameters prms  )  throw (AuthenticationException, NoMoreControllerException, VirtualDatabaseUnavailableException, UnexpectedException)

Creates a new connection and connects to a controller with the given parameters.

Parameters:
prms controller, base, user, etc. to use for connecting
Exceptions:
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


Member Function Documentation

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.

Exceptions:
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.

Returns:
true if the connection has been closed without errors

void CarobNS::Connection::closeRemoteResultSet ( std::wstring  cursorName  )  throw (SocketIOException, BackendException, ControllerException, ProtocolException, UnexpectedException)

Closes the remote ResultSet given its cursor name.

Parameters:
cursorName cursor name of the ResultSet to close
Exceptions:
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.

Returns:
true if the connection has been closed without errors

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).

Exceptions:
DriverException if connection is in autocommit mode
See also:
Connection::setAutoCommit(boolean)

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.

Exceptions:
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.

Parameters:
bde exception chain to convert

ParameterStatement* CarobNS::Connection::createParameterStatement ( const std::wstring &  query  )  throw (SocketIOException, UnexpectedException)

Creates a parameter statement.

Parameters:
query a sql skeleton query
Returns:
a new 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.

Returns:
a new 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

Parameters:
stPtr pointer to the statement to destroy
Exceptions:
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()

Exceptions:
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).

Exceptions:
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.

Returns:
reference to this connection socket

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.

Returns:
the first SQLWarning or null
Exceptions:
DriverException if a database access error occurs or this method is called on a closed connection

bool CarobNS::Connection::isClosed (  )  const throw (UnexpectedException)

Returns:
true if the connection has been closed following some irrecoverable error

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.

Returns:
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).

Parameters:
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.

Exceptions:
DriverException if the connection is in autocommit mode
See also:
Connection::commit()

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.

Parameters:
socket on which to read and write
command to send
Exceptions:
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.

Parameters:
autoCommit true enables auto-commit; false disables it
Exceptions:
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*)

Parameters:
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.

Parameters:
readOnlyPrm true enables read-only mode; false disables it
Exceptions:
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.

Parameters:
request the request to execute
Returns:
a list of ResultSetOrUpdateCount elements
Exceptions:
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.

Parameters:
request the read request with result set parameters to execute
Returns:
a pointer to the resulting DriverResultSet
Exceptions:
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.

Parameters:
r the write request to execute
Returns:
number of rows affected, -1 if an error occured
Exceptions:
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.

Parameters:
request the write request to execute
Returns:
a 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
Exceptions:
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.

Parameters:
cursorName name of the ResultSet cursor
fetchSize number of rows to fetch
Exceptions:
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.

Parameters:
request the write request to send
Exceptions:
SocketIOException when an error occured on the stream


The documentation for this class was generated from the following file:
Generated on Fri Mar 9 17:40:20 2007 for Carob by  doxygen 1.4.7