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 (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.
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, 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.
DriverResultSetpreparedStatementGetMetaData (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).
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.

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 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 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 (DriverException, ConnectionException, AuthenticationException, 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 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)


Member Function Documentation

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::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::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()

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

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

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

DriverResultSet* CarobNS::Connection::statementExecuteQuery ( RequestWithResultSetParameters request  )  throw (SocketIOException, BackendException, 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, 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::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.

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

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

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

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

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

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

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

Returns:
the first SQLWarning or null
Exceptions:
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.

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

Returns:
true if the connection initialization succeeds
Exceptions:
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

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

Returns:
true if the connection has been closed without errors

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.

Returns:
true if the connection has been closed without errors

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

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 

const DriverSocket& CarobNS::Connection::getDriverSocket (  )  [inline, protected]

Gets the driver socket for i/o operations.

Returns:
reference to this connection socket


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