kexi

KexiDB::Driver Class Reference

#include <driver.h>

Inheritance diagram for KexiDB::Driver:

KexiDB::Object KexiDB::MySqlDriver KexiDB::pqxxSqlDriver KexiDB::SQLiteDriver

List of all members.


Detailed Description

Generic database abstraction.

This class is a prototype of the database driver for implementations. Driver allows new connections to be created, and groups these as a parent. Before destruction, all connections are destructed.

Notes:

  • driver must be provided within KDE module file named with "kexidb_" prefix
  • following line should be placed in driver's implementation:
        KEXIDB_DRIVER_INFO( CLASS_NAME, INTERNAL_NAME );
    
    where:
    • CLASS_NAME is actual driver's class name, e.g. MySqlDriver
    • INTERNAL_NAME is driver name's most significant part (without quotation marks), e.g. mysql Above information uses K_EXPORT_COMPONENT_FACTORY macro for KTrader to find the module's entry point. For example, this line declares kexidb_mysqldriver.so module's entry point:
          KEXIDB_DRIVER_INFO( MySqlDriver, mysql );
      

See also:
SQLiteDriver MySqlDriver, pqxxSqlDriver

Definition at line 66 of file driver.h.


Public Types

enum  Features {
  NoFeatures = 0, SingleTransactions = 1, MultipleTransactions = 2, NestedTransactions = 4,
  CursorForward = 8, CursorBackward = (CursorForward+16), CompactingDatabaseSupported = 32, IgnoreTransactions = 1024
}
enum  CreateConnectionOptions { ReadOnlyConnection = 1 }
enum  EscapeType { EscapeDriver = 0x01, EscapeKexi = 0x02 }
enum  EscapePolicy { EscapeAsNecessary = 0x04, EscapeAlways = 0x08 }
typedef QMap< QString, InfoInfoMap

Public Member Functions

ConnectioncreateConnection (ConnectionData &conn_data, int options=0)
const QPtrList< ConnectionconnectionsList () const
QString fileDBDriverMimeType () const
const KService * service () const
bool isFileDriver () const
virtual bool isSystemObjectName (const QString &n) const
virtual bool isSystemDatabaseName (const QString &n) const =0
bool isSystemFieldName (const QString &n) const
int features () const
bool transactionsSupported () const
AdminToolsadminTools () const
virtual QString sqlTypeName (int id_t, int p=0) const
virtual bool isValid ()
virtual DatabaseVersionInfo version () const =0
virtual QString valueToSQL (uint ftype, const QVariant &v) const
QString valueToSQL (const QString &ftype, const QVariant &v) const
QString valueToSQL (const Field *field, const QVariant &v) const
virtual QString dateTimeToSQL (const QDateTime &v) const
virtual QString escapeString (const QString &str) const =0
virtual QCString escapeString (const QCString &str) const =0
virtual QString escapeBLOB (const QByteArray &array) const =0
QString escapeIdentifier (const QString &str, int options=EscapeDriver|EscapeAsNecessary) const
QCString escapeIdentifier (const QCString &str, int options=EscapeDriver|EscapeAsNecessary) const
QVariant propertyValue (const QCString &propName) const
QString propertyCaption (const QCString &propName) const
QValueList< QCString > propertyNames () const

Static Public Member Functions

static QString defaultFileBasedDriverMimeType ()
static QString defaultFileBasedDriverName ()
static bool isKexiDBSystemObjectName (const QString &n)
static QString defaultSQLTypeName (int id_t)

Protected Member Functions

 Driver (QObject *parent, const char *name, const QStringList &args=QStringList())
virtual Connectiondrv_createConnection (ConnectionData &conn_data)=0
virtual QString drv_escapeIdentifier (const QString &str) const =0
virtual QCString drv_escapeIdentifier (const QCString &str) const =0
virtual bool drv_isSystemFieldName (const QString &n) const =0
virtual AdminToolsdrv_createAdminTools () const
ConnectionremoveConnection (Connection *conn)
void initSQLKeywords (int hashSize=17)

Protected Attributes

DriverBehaviour * beh
DriverPrivate * d

Friends

class Connection
class Cursor
class DriverManagerInternal

Classes

class  Info

Member Enumeration Documentation

Features supported by driver (sum of few Features enum items).

Enumerator:
SingleTransactions  single trasactions are only supported
MultipleTransactions  multiple concurrent trasactions are supported (this implies !SingleTransactions)
NestedTransactions  nested trasactions are supported (this should imply !SingleTransactions and MultipleTransactions)
CursorForward  forward moving is supported for cursors (if not available, no cursors available at all)
CursorBackward  backward moving is supported for cursors (this implies CursorForward)
CompactingDatabaseSupported  compacting database supported (aka VACUUM)
IgnoreTransactions  If set, actions related to transactions will be silently bypassed with success. Set this if your driver does not support transactions at all Currently, this is only way to get it working with KexiDB. Keep in mind that this hack do not provide data integrity! This flag is currently used for MySQL driver.

Definition at line 86 of file driver.h.

Options used for createConnection().

Enumerator:
ReadOnlyConnection  set to perform read only connection

Definition at line 114 of file driver.h.


Constructor & Destructor Documentation

Driver::Driver ( QObject *  parent,
const char *  name,
const QStringList &  args = QStringList() 
) [protected]

Used by DriverManager. Note for driver developers: Reimplement this. In your reimplementation you should initialize:

  • d->typeNames - to types accepted by your engine
  • d->isFileDriver - to true or false depending if your driver is file-based
  • d->features - to combination of selected values from Features enum

You may also want to change options in DriverBehaviour *beh member. See drivers/mySQL/mysqldriver.cpp for usage example.

Definition at line 72 of file driver.cpp.


Member Function Documentation

Connection * Driver::createConnection ( ConnectionData conn_data,
int  options = 0 
)

Creates connection using conn_data as parameters.

Returns:
0 and sets error message on error. driverName member of conn_data will be updated with this driver name. options can be a combination of CreateConnectionOptions enum values.

Definition at line 178 of file driver.cpp.

const QPtrList< Connection > Driver::connectionsList (  )  const

Returns:
List of created connections.

Definition at line 125 of file driver.cpp.

QString Driver::fileDBDriverMimeType (  )  const

Returns:
a name equal to the service name (X-Kexi-DriverName) stored in given service .desktop file.

a name of MIME type of files handled by this driver if it is a file-based database's driver (equal X-Kexi-FileDBDriverMime service property) otherwise returns null string.

See also:
isFileDriver()

Definition at line 134 of file driver.cpp.

QString Driver::defaultFileBasedDriverMimeType (  )  [static]

Returns:
default file-based driver mime type (typically something like "application/x-kexiproject-sqlite")

Definition at line 137 of file driver.cpp.

QString Driver::defaultFileBasedDriverName (  )  [static]

Returns:
default file-based driver name (currently, "sqlite3").

Definition at line 140 of file driver.cpp.

const KService * Driver::service (  )  const

Info about the driver as a service.

Definition at line 146 of file driver.cpp.

bool Driver::isFileDriver (  )  const

Returns:
true if this driver is file-based

Definition at line 149 of file driver.cpp.

bool Driver::isSystemObjectName ( const QString &  n  )  const [virtual]

Returns:
true if n is a system object's name, eg. name of build-in system table that cannot be used or created by a user, and in most cases user even shouldn't see this. The list is specific for a given driver implementation. By default calls Driver::isKexiDBSystemObjectName() static method. Note for driver developers: Also call Driver::isSystemObjectName() from your reimplementation.
See also:
isSystemFieldName().

Reimplemented in KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

Definition at line 230 of file driver.cpp.

bool Driver::isKexiDBSystemObjectName ( const QString &  n  )  [static]

Returns:
true if n is a kexibd-related 'system' object's name, i.e. when n starts with "kexi__" prefix.

Definition at line 235 of file driver.cpp.

virtual bool KexiDB::Driver::isSystemDatabaseName ( const QString &  n  )  const [pure virtual]

Returns:
true if n is a system database's name, eg. name of build-in, system database that cannot be used or created by a user, and in most cases user even shouldn't see this. The list is specific for a given driver implementation. For implementation.
See also:
isSystemObjectName().

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

bool Driver::isSystemFieldName ( const QString &  n  )  const

Returns:
true if n is a system field's name, build-in system field that cannot be used or created by a user, and in most cases user even shouldn't see this. The list is specific for a given driver implementation.
See also:
isSystemObjectName().

Definition at line 243 of file driver.cpp.

int Driver::features (  )  const

Returns:
Driver's features that are combination of Driver::Features enum.

Definition at line 152 of file driver.cpp.

bool Driver::transactionsSupported (  )  const

Returns:
true if transaction are supported (single or multiple).

Definition at line 155 of file driver.cpp.

AdminTools & Driver::adminTools (  )  const

Returns:
admin tools object providing a number of database administration tools for the driver. Tools availablility varies from driver to driver. You can check it using features().

Definition at line 158 of file driver.cpp.

QString Driver::sqlTypeName ( int  id_t,
int  p = 0 
) const [virtual]

SQL-implementation-dependent name of given type

Reimplemented in KexiDB::pqxxSqlDriver.

Definition at line 170 of file driver.cpp.

QString Driver::defaultSQLTypeName ( int  id_t  )  [static]

used when we do not have Driver instance yet

Definition at line 206 of file driver.cpp.

bool Driver::isValid (  )  [virtual]

Returns:
true if this driver's implementation is valid. Just few constriants are checked to ensure that driver developer didn't forget about something. This method is called automatically on createConnection(), and proper error message is set properly on any error.

Definition at line 101 of file driver.cpp.

virtual DatabaseVersionInfo KexiDB::Driver::version (  )  const [pure virtual]

Driver's static version information (major part), it is automatically defined in implementation by KEXIDB_DRIVER macro (see driver_p.h) It's usually compared to drivers' and KexiDB library version.

QString Driver::valueToSQL ( uint  ftype,
const QVariant &  v 
) const [virtual]

Escapes and converts value v (for type ftype) to string representation required by SQL commands. Reimplement this if you need other behaviour (eg. for 'date' type handling) This implementation return date, datetime and time values in ISO format, what seems to be accepted by SQL servers.

See also:
Qt::DateFormat

Reimplemented in KexiDB::pqxxSqlDriver.

Definition at line 250 of file driver.cpp.

QString KexiDB::Driver::valueToSQL ( const QString &  ftype,
const QVariant &  v 
) const [inline]

Like above but with the fildtype as string.

Definition at line 226 of file driver.h.

QString KexiDB::Driver::valueToSQL ( const Field field,
const QVariant &  v 
) const [inline]

Like above method, for field.

Definition at line 231 of file driver.h.

virtual QString KexiDB::Driver::dateTimeToSQL ( const QDateTime &  v  )  const [inline, virtual]

not compatible with all drivers - reimplement

(was compatible with SQLite: http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions) Now it's ISO 8601 DateTime format - with "T" delimiter: http://www.w3.org/TR/NOTE-datetime (e.g. "1994-11-05T13:15:30" not "1994-11-05 13:15:30")

Todo:
add support for time zones?

Definition at line 236 of file driver.h.

virtual QString KexiDB::Driver::escapeString ( const QString &  str  )  const [pure virtual]

Driver-specific SQL string escaping. Implement escaping for any character like " or ' as your database engine requires. Prepend and append quotation marks.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

virtual QCString KexiDB::Driver::escapeString ( const QCString &  str  )  const [pure virtual]

This is overloaded version of escapeString( const QString& str ) to be implemented in the same way.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

virtual QString KexiDB::Driver::escapeBLOB ( const QByteArray &  array  )  const [pure virtual]

Driver-specific SQL BLOB value escaping. Implement escaping for any character like " or ' and \0 as your database engine requires. Prepend and append quotation marks.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

QString Driver::escapeIdentifier ( const QString &  str,
int  options = EscapeDriver|EscapeAsNecessary 
) const

Driver-specific identifier escaping (e.g. for a table name, db name, etc.).

Escape database identifier (str) in order that keywords can be used as table names, column names, etc. options is the union of the EscapeType and EscapePolicy types. If no escaping options are given, defaults to driver escaping as necessary.

Definition at line 316 of file driver.cpp.

QVariant Driver::propertyValue ( const QCString &  propName  )  const

Returns:
property value for propeName available for this driver. If there's no such property defined for driver, Null QVariant value is returned.

Definition at line 299 of file driver.cpp.

QString Driver::propertyCaption ( const QCString &  propName  )  const

Returns:
translated property caption for propeName. If there's no such property defined for driver, empty string value is returned.

Definition at line 304 of file driver.cpp.

QValueList< QCString > Driver::propertyNames (  )  const

Returns:
a list of property names available for this driver.

Definition at line 309 of file driver.cpp.

virtual Connection* KexiDB::Driver::drv_createConnection ( ConnectionData conn_data  )  [protected, pure virtual]

For reimplemenation: creates and returns connection object with additional structures specific for a given driver. Connection object should inherit Connection and have a destructor that descructs all allocated driver-dependent connection structures.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

virtual QString KexiDB::Driver::drv_escapeIdentifier ( const QString &  str  )  const [protected, pure virtual]

Driver-specific SQL string escaping. This method is used by escapeIdentifier(). Implement escaping for any character like " or ' as your database engine requires. Do not append or prepend any quotation marks characters - it is automatically done by escapeIdentifier() using DriverBehaviour::QUOTATION_MARKS_FOR_IDENTIFIER.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

virtual QCString KexiDB::Driver::drv_escapeIdentifier ( const QCString &  str  )  const [protected, pure virtual]

This is overloaded version of drv_escapeIdentifier( const QString& str ) to be implemented in the same way.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

virtual bool KexiDB::Driver::drv_isSystemFieldName ( const QString &  n  )  const [protected, pure virtual]

Returns:
true if n is a system field's name, build-in system field that cannot be used or created by a user, and in most cases user even shouldn't see this. The list is specific for a given driver implementation. For implementation.

Implemented in KexiDB::MySqlDriver, KexiDB::pqxxSqlDriver, and KexiDB::SQLiteDriver.

Connection * Driver::removeConnection ( Connection conn  )  [protected]

Returns:
connection conn , do not deletes it nor affect. Returns 0 if conn is not owned by this driver. After this, you are owner of conn object, so you should eventually delete it. Better use Connection destructor.

Definition at line 200 of file driver.cpp.

void Driver::initSQLKeywords ( int  hashSize = 17  )  [protected]

Used to initialise the dictionary of driver-specific keywords. Should be called by the Driver's constructor. hashSize is the number of buckets to use in the dictionary.

See also:
DriverPrivate::SQL_KEYWORDS.

Definition at line 360 of file driver.cpp.


Member Data Documentation

DriverPrivate* KexiDB::Driver::d [protected]

for future extensions

Reimplemented from KexiDB::Object.

Definition at line 363 of file driver.h.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys