koffice/kexi/doc/dev/kexidb_api_changes.txt

--------------------------------------------
 KexiDB Module API Changes
 Doc started: 2003-07-08 by js@iidea.pl
--------------------------------------------

These changes are propsals for further disscussions.


1. *** RENAMING ***

Some classes can be betted described with other names:

class KexiDBInterfaceManager -> KexiDBDriverManager

Motivation: 'Interface' is a more generic term. Thus, the class name is not a description.
'Driver Manager' term is also used in the iODBC package.


2. Now, KexiDB is just another ODBC-like layer. Probably there woudn't be too much drivers 
for KexiDB if KexiDB will be still like it is.

What to change?
KexiDB should be merged with non-visual (but db-related) parts of KexiProject.
KexiProject then should be renamed to KexiDBProject and be moved to KexiDB.
Visual (document-like) project container (formerly KexiProject) that inherits KoDocument
could be then named to something else and still exist since Kexi, as KOffice application,
needs to implement KoDocument. (KexiProjectHandler is also visual-related)

What we got then?
After that move, KexiProject becames a non-visual general-purpose entity. SO it can be instantiated
not only as Kexi Koffice document window, but also:
- for batch (non-visual) data processing (equivalents of given features availabe from gui, e.g. data export)
- for easy use in Kexi plugins and/or other apps that would know about enchanced database properties
provided by Kexi projects' metadata
- to enable linking current Kexi project with external Kexi projects' data, in the future (these external 
projects do not have to be visible as regular projects, but its metadata is loaded)

Other motivation:
It's not necessary for KexiProject to be dependent on KOfficelibs.


3. KexiDBConnection should be moved to KexiDB module and it should be only connection data container.


4. Kexi uses KoStore as medium for storing project's meta data. 

What if we want to store even this data in the database?

We need more generic class KexiDBProjectStore for this of extend KoStore. Note that extending 
KoStore may not be possible (or nice) because of hierarchical (fs-like) structure of this medium,
while db store is relational.

Why to store Kexi projects in the db?

- We can utilize transactional, multiuser features of databases "for free"
- Using sqlite engine we can still store projects in local files. 
So, maybe drop KoStore completely? Oh, maybe not, but we can treat this format as xml-exported,
mainly for external processing, migration and backups.

Note that there can be one database location for storing project's user data and completely other location
for the database that has stored project's meta-data (see example below).


5. Example usage of db engine, to get both project metadata and raw db connection

{
    kdDebug() << "DRIVERS:" << KexiDBEnginesManager::enginesNames() << endl;
  KexiDBEngine *engine = KexiDBEngineManager::engine("mysql");
  if (!engine) {
    kdDebug() << "no engine" << endl;
    return 1;
  }

  //we can also get the manager obj. with: KexiDBEnginesManager *manager = KexiDBEnginesManager::self();

  //connection data that can be later reused
  KexiDBConnectionData conn_data;
  conn_data.host = "myhost";
  conn_data.password = "mypwd";

  KexiDBConnection *conn = engine->createConnection(conn_data);
  if (!conn->connect()) {
    kdDebug() << "err. connect" << endl;
    return 1;
  }
  kdDebug() << "DATABASES:" << conn->dbNames() << endl;

//we want use this connection to load given Kexi Project:

  KexiDBProject *prj = new KexiDBProject( conn, "test" );
  /* connection 'conn' has been opened for project meta-data source:
     KexiDBProjectStore *store = new KexiDBProjectStore( conn )
    Kexi then opens data base with KexiDBConnection::openDatabase( name )
    where 'name' comes from meta-data.
    This new connection is for projects' data.
  */
  /* we could also load project from a file:
    KexiDBProject *prj = new KexiDBProject( "~/myprj.kexi" );
    Then, KexiProject will be loaded from the file:
    KexiDBProjectStore *store = new KexiDBProjectStore( "~/myprj.kexi" );
    ..and data connection will be established as before.
  */
  if (!prj)
    kdDebug() << "err. open db" << endl;
    return 1;
  }
  kdDebug() << "TABLE DEFS:" << prj->tableDefsNames() << endl;
  kdDebug() << "QUERY DEFS:" << prj->queryDefsNames() << endl;

  KexiDBTableDef *tab_def = prj->tableDef("people") << endl;
  if (!tab_def)
    kdDebug() << "no table def" << endl;
    return 1;
  }
  kdDebug() << "TABLE DEF FIELDS:" << tab_def->fieldsNames() << endl;
  
  KexiDBFieldDef *field = tab_def->field("age");
  if (!field)
    kdDebug() << "no such field" << endl;
    return 1;
  }
  kdDebug() << "FIELD TYPE:" << field->typeName() << endl;

  return 0;
}