# Structure overview

This library is divided in two parts: a database access library and a set of widgets and dialogs useful for the development of database enabled apps in KDE.

# KDBCORE

The database access library, kdbcore, uses a plugin system to access different RDBMS Actually, there is only a plugin for MySQL, but porting from existent KSql plugin should be easy.

The class hierarchy of Data access objects is contained in the namespace KDB. All objects are QObjects, and event notification will be performed through QT signal/slot mechanism.

## Functionality provided

The kdbcore library provides primitives for accessing databases, and it represent an 'abstraction layer' over the different database systems. The implementation of the abstraction layer is done in DBMS specific 'plugins', that are dynamically loadable libraries, loaded at runtime by the engine itself.

Through a plugin is possible to open connections to different database servers. Each Connection in turn provide access to the different databases present in the server.

A Database is a collection of Tables and stored Queries, and can be used to open recordset based on entered queries (not stored ones).

A Table object can be used to obtain table informations, modifying table structure and open updatable recordsets on the content.

A Query is a saved SQL statement that can be executed to retrieve the corresponding recordset. One-table queries produce updatable recordsets. A Query object can also be used to build SQL statement giving a list of fields, tables and filter conditions.

## The KDB type system

Each DBMS implements its own type system. Most (but not all) of these type systems are a superset of the SQL92 specification. The goal of the KDB core library is to give the programmer a unified way to handle all that diversity transparently.

KDB defines a set of supported C++/QT types that are mapped at plugin level with the native types of the DBMS.

Those types that does not fit naturally with the native C++ types are converted either to QString or to QByteArray . Thys way, all the power of underlying DBMS can be used by the expert programmer, but the novice (and all those people that don't need or don't want to use esoteric types) has the ability of working with well known C++ objects and have a transparent support for these.

In details, the Field object implements all the conversion operators for the standard types. The implementation for a specific field type will throw an exception if an incorrect conversion is attempted.

## Dynamic capability system

Not each DBMS implements the same set of features. Some don't use transactions, or stored procedures, or other specific feature. Being a general purpose library, KDB provides a dynamic access to those features through the capability system.

Each Plugin object can be queried to know it a specific capability is implemented or to obtain a list of implemented capabilities. A list of currently supported capabilities is available in the enum KDB::capability.

There are two kinds of capability: the ones that can be used/requested through a method of some base object (like transactions, that apply to a Database) and those that can be represented by a separate object in the hierarchy (like stored procedures).

The first kind of capability is implemented within the interface of the base object that can implement it ( like KDB::Database::beginTransaction ). this implementation will throw an exception if the plugin does not support such a capability

The second type of capability is implemented by the Plugin object, through the KDB::Plugin::createObject method. With this method the programmer can obtain a KDB::Capability subclass that can be casted to the specific type

## Class hierarchy

- KDB::Object
  - KDB::Capability
  - KDB::Connection
  - KDB::DBEngine
  - KDB::DataObject
    - KDB::Query
    - KDB::Recordset
    - KDB::Table
  - KDB::Database
  - KDB::Field
  - KDB::Index
  - KDB::Plugin

- KDB::Exception
  - KDB::ConnectionException
    - KDB::HostNotFound
    - KDB::InvalidLogin
  - KDB::DataException
    - KDB::ConversionException
    - KDB::ObjectNotFound
    - KDB::SQLError
    - KDB::ServerError
  - KDB::PluginException
    - KDB::LibraryError
    - KDB::PluginNotFound
    - KDB::UnsupportedCapability

## The Plugn architecture

To keep it really simple, and to speed up the development of a plugin, the plugin library must provide only two classes: a subclass of KDB::Plugin ( that provides informations about the plugin and is responsible of creating the connector) and a subclass of connector, that is responsible for all I/O of the plugin. Plugins will be loaded through KLibLoader and will provide KDB/Plugin servicetypes.

# KDBUI

The KDB UI library will provide apps with standard dialogs and widgets for the development of database apps. Examples of what this library will provided are the setup dialog for connections, data aware grids, line edit, comboboxes and such.

This library will depend only on the kdbcore library and on the KDE base libraries.