org.objectweb.cjdbc.driver.protocol
Class Commands

java.lang.Object
  org.objectweb.cjdbc.driver.protocol.Commands

public class Commands

extends java.lang.Object

Protocol commands between C-JDBC driver (client) and controller (server). All communications follow a classic RPC scheme: the driver sends a Command code, followed by argument(s) for some of the commands, and expects some answer(s), at the very least an error code or an exception. The server is event-driven; communications are inited by the client which is the one sending Protocol commands, so the verbs send and receive must be understood as from driver point of view. Almost all these commands are put on the wire by client class Connection and read (and answered) by class VirtualDatabaseWorkerThread.run(). The only exceptions are the following commands:
- ProtocolVersion
read only by ControllerWorkerThread.run(), which then constructs the connection and pass it to VirtualDatabaseWorkerThread for the rest of the execution of this command.
- Close
in addition to Connection, also sent by ConnectionClosingThread.closeConnection(Connection)
- Ping
sent on a dedicated connection only by ControllerPingThread.run() and silently received only by (again) ControllerWorkerThread.run()

Protocol Data Types

optUTF is a custom type defined like this:

 (boolean false) | (boolean true; UTF somestring)
 

Sent types

Several commands send a SQL query. All SQL queries sent on the wire use the same starting pattern, a requestStub defined below and in AbstractRequest.AbstractRequest(CJDBCInputStream, int)
requestStub

 UTF     request           : SQL query
 boolean EscapeProcessing
 UTF     LINE_SEPARATOR
 Int     timeout
 boolean autoCommit
 boolean isDriverProcessed
 

Queries that expect a result set (read commands mostly) send immediately after the requestStub a subsetLengths parameter, of type:
subsetLengths. See AbstractRequest.receiveResultSetParams(CJDBCInputStream)

 Int    maxRows
 Int    fetchSize
 

Depending on some configuration flag/state (shared by driver and controller), most query commands add an optional skeleton parameter of type optUTF.

Received types

Several commands receive a ResultSet of type:
ResultSet org.objectweb.cjdbc.driver.DriverResultSet#DriverResultSet(CJDBCInputStream)

  Field[]   fields
  TypeTag[] java column types
  ArrayList   data
  optUTF      hasMoreData: cursor name
 

- fields is the description of the ResultSet columns.
- data is the actual data of the ResultSet. Each element of this list is an Object array holding one row of the ResultSet. The whole arraylist is serialized using standard Java serialization/readUnshared().

Exceptions

For almost every command sent, the driver checks if the reply is an exception serialized by the controller instead of the regular reply type. Most exceptions are put on the wire by VirtualDatabaseWorkerThread.run() TODO: finish the classification below.
Exception reply recognized by the driver in:
FetchNextResultSetRows, closeRemoteResultSet, RestoreConnectionState, setAutoCommit, getCatalog, getCatalogs, setCatalog, getControllerVersionNumber, DatabaseMetaDataGetTables, DatabaseMetaDataGetColumns, DatabaseMetaDataGetPrimaryKeys, DatabaseMetaDataGetProcedureColumns, DatabaseMetaDataGetTableTypes, DatabaseMetaDataGetTablePrivileges, DatabaseMetaDataGetSchemas, DatabaseMetaDataGetDatabaseProductName, DatabaseStaticMetadata
Exception reply ignored by the driver in: Close, Reset
Exceptions catched by instanceof(catch-all) default clause in:
setAutoCommit,
Commands not implemented at all by the driver:
GetVirtualDatabaseName,
TODO:
- exceptions and the server side (VirtualDatabaseWorkerThread)
- double-check arguments and replies
- better topic ordering

Version:

1.0

Author:

Emmanuel Cecchet , Nicolas Modrzyk , Marc Herbert , Jean-Bernard van Zuylen

Field Summary

static int	Begin Begins a new transaction and returns the corresponding transaction identifier.
static int	Close Close the connection.
static int	CloseRemoteResultSet Closes a remote ResultSet that was opened for streaming.
static int	Commit Commits the current transaction.
static int	ConnectionGetCatalog Retrieve the catalog (database) we are connected to.
static int	ConnectionGetCatalogs Retrieve the list of available catalogs (databases).
static int	ConnectionSetCatalog Connect to another catalog/database (as the same user).
static int	DatabaseMetaDataGetAttributes
static int	DatabaseMetaDataGetBestRowIdentifier
static int	DatabaseMetaDataGetColumnPrivileges
static int	DatabaseMetaDataGetColumns Used to get the schema columns by calling DatabaseMetaData.getColumns().
static int	DatabaseMetaDataGetCrossReference
static int	DatabaseMetaDataGetDatabaseProductName Retrieve the database product name.
static int	DatabaseMetaDataGetExportedKeys
static int	DatabaseMetaDataGetImportedKeys
static int	DatabaseMetaDataGetIndexInfo
static int	DatabaseMetaDataGetPrimaryKeys Used to get the schema primary keys by calling DatabaseMetaData.getColumns().
static int	DatabaseMetaDataGetProcedureColumns Used to get the schema procedure columns by calling DatabaseMetaData.getProcedureColumns().
static int	DatabaseMetaDataGetProcedures Used to get the schema procedures by calling DatabaseMetaData.getProcedures().
static int	DatabaseMetaDataGetSchemas Retrieve the schemas.
static int	DatabaseMetaDataGetSuperTables
static int	DatabaseMetaDataGetSuperTypes
static int	DatabaseMetaDataGetTablePrivileges Retrieve the table privileges.
static int	DatabaseMetaDataGetTables Used to get the schema tables by calling DatabaseMetaData.getTables().
static int	DatabaseMetaDataGetTableTypes Retrieve the database table types.
static int	DatabaseMetaDataGetTypeInfo
static int	DatabaseMetaDataGetUDTs
static int	DatabaseMetaDataGetVersionColumns
static int	DatabaseStaticMetadata Retrieve one value from the virtual database metadata.
static int	ExecReadRequest Performs a read request and returns the reply.
static int	ExecReadStoredProcedure Calls a stored procedure and returns the reply (ResultSet).
static int	ExecWriteRequest Performs a write request and returns the number of rows affected.
static int	ExecWriteRequestWithKeys Performs a write request and returns the auto generated keys.
static int	ExecWriteStoredProcedure Calls a stored procedure and returns the number of rows affected (write query).
static int	FetchNextResultSetRows Fetch next rows of data for ResultSet streaming.
static int	GetControllerVersionNumber Gets the controller version number.
static int	GetVirtualDatabaseName Gets the virtual database name to be used by the client (C-JDBC driver).
static int	Ping Ping is used by the ControllerPingThread to check if a controller is back online after a failure.
static int	ProtocolVersion Command used to create a new connection, while checking that driver and controller are compatible with each other.
static int	ReleaseSavepoint Releases a savepoint from a transaction given its id
static int	Reset Reset the connection.
static int	RestoreConnectionState Restore a connection state after an automatic reconnection.
static int	Rollback Rollbacks the current transaction.
static int	RollbackToSavepoint Rollbacks the current transaction back to the given savepoint
static int	SetAutoCommit Command to change the autocommit value from false to true.
static int	SetNamedSavepoint Sets a named savepoint to a transaction given its id
static int	SetTransactionIsolation Set the new transaction isolation level to use for this connection.
static int	SetUnnamedSavepoint Sets a unnamed savepoint to a transaction given its id

Constructor Summary

Commands()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ProtocolVersion

public static final int ProtocolVersion

Command used to create a new connection, while checking that driver and controller are compatible with each other. This constant is not a Command and should be moved out of this file.

~commandcode 20

~argument UTF dataBaseName
~argument UTF user
~argument UTF password

~reply boolean needSkeleton: Does the controller require the SQL skeleton? This is only a boolean here, not the full optUTF skeleton often used elsewhere.
~reply UTF sfilter: the kind of blob encoding the server wants the driver to use

See Also:

ControllerWorkerThread.run(), ConnectionClosingThread.closeConnection(Connection), Constant Field Values

Ping

public static final int Ping

Ping is used by the ControllerPingThread to check if a controller is back online after a failure. This command is quite special because it is sent on a new, dedicated socket. There is neither any argument nor any answer: the controller immediately closes the connection after receiving it. This constant is not a Command and should be moved out of this file.

See Also:

ControllerWorkerThread.run(), ControllerPingThread.run(), Constant Field Values

ExecReadRequest

public static final int ExecReadRequest

Performs a read request and returns the reply.

~commandcode 0

~argument requestStub
~argument subsetLengths
~argument optUTF cursorname
~argument optUTF skeleton

~reply ResultSet

See Also:

VirtualDatabaseWorkerThread.execReadRequest(), Constant Field Values

ExecWriteRequest

public static final int ExecWriteRequest

Performs a write request and returns the number of rows affected.

~commandcode 1

~argument Int RequestType
~argument requestStub
~argument optUTF skeleton

~reply nbRows

See Also:

VirtualDatabaseWorkerThread.execWriteRequest(), Constant Field Values

ExecWriteRequestWithKeys

public static final int ExecWriteRequestWithKeys

Performs a write request and returns the auto generated keys.

~commandcode 2

~argument Int RequestType
~argument requestStub
~argument subsetLengths
~argument optUTF skeleton

~reply ResultSet

See Also:

VirtualDatabaseWorkerThread.execWriteRequestWithKeys(), Constant Field Values

ExecReadStoredProcedure

public static final int ExecReadStoredProcedure

Calls a stored procedure and returns the reply (ResultSet).

~commandcode 3

~argument requestStub
~argument subsetLengths
~argument optUTF skeleton

~reply ResultSet

See Also:

VirtualDatabase.execReadStoredProcedure(org.objectweb.cjdbc.common.sql.StoredProcedure), Constant Field Values

ExecWriteStoredProcedure

public static final int ExecWriteStoredProcedure

Calls a stored procedure and returns the number of rows affected (write query).

~commandcode 4

~argument requestStub
~argument optUTF skeleton

~reply Int nbRows

See Also:

VirtualDatabase.execReadStoredProcedure(org.objectweb.cjdbc.common.sql.StoredProcedure), Constant Field Values

Begin

public static final int Begin

Begins a new transaction and returns the corresponding transaction identifier. This method is called from the driver when Connection.setAutoCommit(boolean)is called with false argument.

~commandcode 20

~reply Long transactionId

See Also:

VirtualDatabase.begin(String), Constant Field Values

Commit

public static final int Commit

Commits the current transaction.

~commandcode 21

~reply Long transactionId: id of next transaction

See Also:

VirtualDatabase.commit(long, boolean), Constant Field Values

Rollback

public static final int Rollback

Rollbacks the current transaction.

~commandcode 22

~reply Long transactionId: id of next transaction

See Also:

VirtualDatabase.rollback(long, boolean), Constant Field Values

SetNamedSavepoint

public static final int SetNamedSavepoint

Sets a named savepoint to a transaction given its id

See Also:

VirtualDatabase.setSavepoint(long, String), Constant Field Values

SetUnnamedSavepoint

public static final int SetUnnamedSavepoint

Sets a unnamed savepoint to a transaction given its id

See Also:

VirtualDatabase.setSavepoint(long), Constant Field Values

ReleaseSavepoint

public static final int ReleaseSavepoint

Releases a savepoint from a transaction given its id

See Also:

VirtualDatabase.releaseSavepoint(long, String), Constant Field Values

RollbackToSavepoint

public static final int RollbackToSavepoint

Rollbacks the current transaction back to the given savepoint

See Also:

VirtualDatabaseWorkerThread.rollbackToSavepoint(), Constant Field Values

Close

public static final int Close

Close the connection. The controller replies a CommandCompleted CJDBCException, ignored by the driver.

~commandcode 30

~reply <anything>

See Also:

Constant Field Values

Reset

public static final int Reset

Reset the connection.

~commandcode 31

See Also:

Constant Field Values

FetchNextResultSetRows

public static final int FetchNextResultSetRows

Fetch next rows of data for ResultSet streaming.

~commandcode 32

~argument UTF cursorName
~argument Int fetchSize

~reply ArrayList data
~reply boolean hasMoreData

See Also:

Constant Field Values

CloseRemoteResultSet

public static final int CloseRemoteResultSet

Closes a remote ResultSet that was opened for streaming.

~commandcode 33

~argument UTF cursorName

~reply CJDBCException CommandCompleted

See Also:

Constant Field Values

RestoreConnectionState

public static final int RestoreConnectionState

Restore a connection state after an automatic reconnection. Tell the controller if we were in autoCommit mode (i.e.: a transaction was not started), and if we were not then give the current transactionId. Warning: this is not an optUTF type at all.

~commandcode 34

~argument (boolean true) | (boolean false; Long transactionId)

See Also:

Constant Field Values

SetAutoCommit

public static final int SetAutoCommit

Command to change the autocommit value from false to true. We want to commit the current transaction but we don't want to start a new one.

~commandcode 35

~reply boolean true (meaning: not an exception)

See Also:

Constant Field Values

ConnectionGetCatalog

public static final int ConnectionGetCatalog

Retrieve the catalog (database) we are connected to.

~commandcode 36

~reply String vdbName

See Also:

Connection.getCatalog(), Constant Field Values

ConnectionGetCatalogs

public static final int ConnectionGetCatalogs

Retrieve the list of available catalogs (databases).

~commandcode 37

~reply ResultSet virtualDatabasesList

See Also:

Connection.getCatalogs(), Constant Field Values

ConnectionSetCatalog

public static final int ConnectionSetCatalog

Connect to another catalog/database (as the same user).

~commandcode 38

~argument UTF catalog

~reply boolean isValidCatalog

See Also:

Connection.setCatalog(String), Constant Field Values

SetTransactionIsolation

public static final int SetTransactionIsolation

Set the new transaction isolation level to use for this connection.

~commandcode 39

~argument int transaction isolation level

~reply boolean true (meaning: not an exception)

See Also:

Connection.setTransactionIsolation(int), Constant Field Values

GetVirtualDatabaseName

public static final int GetVirtualDatabaseName

Gets the virtual database name to be used by the client (C-JDBC driver). It currently returns the same result as ConnectionGetCatalog(). It is currently never used by the driver.

~commandcode 50

~reply String dbName

See Also:

VirtualDatabase.getVirtualDatabaseName(), Constant Field Values

GetControllerVersionNumber

public static final int GetControllerVersionNumber

Gets the controller version number.

~commandcode 51

~reply String controllerVersion

See Also:

Controller.getVersionNumber(), Constant Field Values

DatabaseMetaDataGetTables

public static final int DatabaseMetaDataGetTables

Used to get the schema tables by calling DatabaseMetaData.getTables().

~commandcode 52

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF tableNamePattern
~argument String[] types

~reply ResultSet tables

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetTables(), Constant Field Values

DatabaseMetaDataGetColumns

public static final int DatabaseMetaDataGetColumns

Used to get the schema columns by calling DatabaseMetaData.getColumns().

~commandcode 53

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF tableNamePattern
~argument UTF columnNamePattern

~reply ResultSet schemaColumns

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetColumns(), Constant Field Values

DatabaseMetaDataGetPrimaryKeys

public static final int DatabaseMetaDataGetPrimaryKeys

Used to get the schema primary keys by calling DatabaseMetaData.getColumns().

~commandcode 54

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF tableNamePattern

~reply ResultSet pKeys

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetPrimaryKeys(), Constant Field Values

DatabaseMetaDataGetProcedures

public static final int DatabaseMetaDataGetProcedures

Used to get the schema procedures by calling DatabaseMetaData.getProcedures().

~commandcode 55

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF procedureNamePattern

~reply ResultSet procedures

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetProcedures(), Constant Field Values

DatabaseMetaDataGetProcedureColumns

public static final int DatabaseMetaDataGetProcedureColumns

Used to get the schema procedure columns by calling DatabaseMetaData.getProcedureColumns().

~commandcode 56

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF procedureNamePattern
~argument UTF columnNamePattern

~reply ResultSet procColumns

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetProcedureColumns(), Constant Field Values

DatabaseMetaDataGetTableTypes

public static final int DatabaseMetaDataGetTableTypes

Retrieve the database table types.

~commandcode 58

~reply ResultSet tableTypes

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetTableTypes(), Constant Field Values

DatabaseMetaDataGetTablePrivileges

public static final int DatabaseMetaDataGetTablePrivileges

Retrieve the table privileges.

~commandcode 59

~argument UTF catalog
~argument UTF schemaPattern
~argument UTF tableNamePattern

~reply ResultSet accessRights

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetTablePrivileges(), Constant Field Values

DatabaseMetaDataGetSchemas

public static final int DatabaseMetaDataGetSchemas

Retrieve the schemas.

~commandcode 60

~reply ResultSet schemas

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetSchemas(), Constant Field Values

DatabaseMetaDataGetDatabaseProductName

public static final int DatabaseMetaDataGetDatabaseProductName

Retrieve the database product name.

~commandcode 61

~reply String productName

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetDatabaseProductName(), Constant Field Values

DatabaseMetaDataGetAttributes

public static final int DatabaseMetaDataGetAttributes

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetAttributes(), Constant Field Values

DatabaseMetaDataGetBestRowIdentifier

public static final int DatabaseMetaDataGetBestRowIdentifier

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetBestRowIdentifier(), Constant Field Values

DatabaseMetaDataGetColumnPrivileges

public static final int DatabaseMetaDataGetColumnPrivileges

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetColumnPrivileges(), Constant Field Values

DatabaseMetaDataGetCrossReference

public static final int DatabaseMetaDataGetCrossReference

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetCrossReference(), Constant Field Values

DatabaseMetaDataGetExportedKeys

public static final int DatabaseMetaDataGetExportedKeys

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetExportedKeys(), Constant Field Values

DatabaseMetaDataGetImportedKeys

public static final int DatabaseMetaDataGetImportedKeys

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetImportedKeys(), Constant Field Values

DatabaseMetaDataGetIndexInfo

public static final int DatabaseMetaDataGetIndexInfo

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetIndexInfo(), Constant Field Values

DatabaseMetaDataGetSuperTables

public static final int DatabaseMetaDataGetSuperTables

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetSuperTables(), Constant Field Values

DatabaseMetaDataGetSuperTypes

public static final int DatabaseMetaDataGetSuperTypes

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetSuperTypes(), Constant Field Values

DatabaseMetaDataGetTypeInfo

public static final int DatabaseMetaDataGetTypeInfo

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetTypeInfo(), Constant Field Values

DatabaseMetaDataGetUDTs

public static final int DatabaseMetaDataGetUDTs

See Also:

VirtualDatabaseWorkerThread.databaseMetaDataGetUDTs(), Constant Field Values

DatabaseMetaDataGetVersionColumns

public static final int DatabaseMetaDataGetVersionColumns

See Also:

DatabaseMetaData.getVersionColumns(java.lang.String, java.lang.String, java.lang.String), Constant Field Values

DatabaseStaticMetadata

public static final int DatabaseStaticMetadata

Retrieve one value from the virtual database metadata.

~commandcode 80

~argument UTF: serialized DatabaseMetaData method call.

~reply Integer|Boolean|String|other ? value

See Also:

VirtualDatabaseWorkerThread.databaseStaticMetadata(), Constant Field Values

Constructor Detail

Commands

public Commands()