libgda"> GNOME-DB"> Igalia, S.L.'> Xobas Software'> API"> DBMS"> DSN"> ODBC"> GDA"> LDAP"> CORBA"> IDL"> ORB"> SQL"> RPM"> XML"> PostgreSQL"> MySQL"> Oracle"> Interbase"> Sybase"> MS Access"> Informix"> GdaServerProvider"> GdaDataModel"> GdaDataModelArray"> GdaDataModelHash"> ]> Michael Lausch

michael.lausch@1012surf.net

Rodrigo Moya

rodrigo@gnome-db.org

Vivien Malerba

malerba@gnome-db.org

Sean Allen

zeroone@worldonline.co.za

GDP compliance, FDL, added mark-up, English and syntax Xabier Rodriguez Calvar &igalia;

xrcalvar@igalia.com

How to begin and migration formulae Jose Dapena Paz &igalia;

jdapena@igalia.com

Some examples Bas Driessen &xobas;

bas.driessen@xobas.com

libgda, gda-postgres, gda-mysql 1999 February 1999-2005 The GNOME Foundation GNOME Data Access (&GDA;) is an architecture whose purpose is to provide universal access to many different kinds and types of data sources. This goes from traditional relational database systems, to any imaginable kind of data source such as a mail server, a &LDAP; directory... This universality is obtained through the use of an easily extensible plug-in system as the mechanism for communication between the different components in the architecture. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found in the appendix. Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. &ODBC; and &SQL; are established standards. The problem is, that &ODBC; doesn't specify the wire protocol and for some databases no &ODBC; driver exists. You might use RPC, TCP/IP, or shared memory and signals to pass the request from the client to the server. So you have to use the database specific &ODBC; library. This library might not be available for the CPU or operating system on which the client is running. &SQL; itself is also not standardised enough, so that source compatibility can not be assured for all database servers. And for some sort of servers, &SQL; is not even feasible (think about &LDAP;). &GDA; tries to tackle the &ODBC; problem and help you with the &SQL; problem. It's a sort of middleware (or can be blown up to be a middleware layer) to access different data sources. It offers a high level view of data sources and has some places where you can plug in low level access to the database for special tasks. GNOME Data Access (&GDA;) is defined as a set of plug-in interfaces. The level of abstraction provided by &GDA; makes it possible to access any kind of data source, provided that a plug-in implementing those interfaces and accessing this particular data source is written. It offers a wrapper around the database internals, thus making it easier for programmers to make use of all the power provided by many RDBMS without even knowing about it. It comes along with a library, for both clients and servers, as a C implementation of this architecture. This level of abstraction would make possible to, at a later time, change all the internals without having to modify applications using the libraries. Along with these libraries (and associated header files and language bindings for development), &LIBGDA; includes several tools and utilities to help you with the task of developing applications based on &LIBGDA;, as well as for automating some database-related tasks. &LIBGDA; is implemented for UNIX -like operating systems (including Linux), and does not depend on other libraries apart from libxml2 and Glib, which makes it a very lightweight system also ideal for applications to be run on hardware-limited systems. It was once part of the &GNOMEDB; project, and is still used as the basis for it, but it's been separated from it to remove all GNOME dependencies and thus allow non-GNOME applications to be developed based on it. &LIBGDA; is composed of three independent layers. The lower level is covered by the &GDA; providers, which are plug-ins whose task is to map the RDBMS-specific &API; to the &GDA; model. That is, they are objects implementing the &GDA; interfaces. Then, in a middle layer, are the client libraries: an easy-to-use and full featured library which offers access to all the architecture, also including several utility functions to help you on the development of applications based on &GDA;. This library, although targeted to client applications, also includes a set of helper classes and functions to help in the addition of new providers to the &LIBGDA; architecture. Finally, at the upper level sit all the client applications provided in the suite, as well as any application that may make use of the client libraries. &install; &examples; &migration; The following sections describe the API available for &GDA; applications. &libgda-TreeIndex; &libgda-init; &libgda-config; &libgda-GdaClient; &libgda-GdaConnection; &libgda-GdaConnection-event; &libgda-GdaCommand; &LIBGDA; being a data oriented library, data handling is a central point of the library. Data handling is about: individual values: they are encapsulated within a GdaValue container (which is not much more than a GValue from GLIB) parameters which are each a specification for a value: a type, a name, a description, a default value, etc. Parameters are encapsulated within a GdaParameter container. Note that it is possible to set a hint on parameters to make them have a value which is among the values contained in a column of a GdaDataModel. lists of parameters which are encapsulated within a GdaParameterList container. The GdaParameterList object also makes some computations to group parameters which are constrained by values in the same GdaDataModel to make it easy to use parameters which are not really independant. arrays of values organized in rows and columns. All the data in the same column have the same type, and all the data in each row have the same semantic meaning. &LIBGDA; uses the GdaDataModel objects to actually hold the data (note that this is actually an interface which has sevaral implementations depending on the real data organization in the data model). Note that depending on the real implementation, access to the data can be random or done using an iterator, and that the data model can be read-only or modifiable. The GdaDataModelIter object is used to iterate through the rows of a GdaDataModel. &libgda-GdaValue; &libgda-GdaParameter; &libgda-GdaParameterList; &libgda-GdaDataModel; &libgda-GdaColumn; &libgda-GdaDataModelIter; &libgda-GdaDataModelImport; &libgda-GdaDataAccessWrapper; &libgda-GdaDataModelArray; &libgda-GdaDataModelHash; &libgda-GdaDataModelQuery; &libgda-GdaDataModelFilterSQL; &libgda-GdaDataProxy; &libgda-GdaDataModelIndex; &libgda-GdaColumnIndex; &libgda-GdaDict; &libgda-GdaDictType; &libgda-GdaDictFunction; &libgda-GdaDictAggregate; These objects make the in-memory representation of a database structure (Tables, fields, ...), they are part of the data dictionary (see GdaDict). Related interfaces are: GdaXmlStorage, GdaEntity, GdaEntityField, GdaRenderer and GdaReferer. &libgda-GdaDictDatabase; &libgda-GdaDictTable; &libgda-GdaDictField; &libgda-GdaDictConstraint; &libgda-query-intro; &libgda-query-fields; &libgda-GdaQuery; &libgda-GdaQueryTarget; &libgda-GdaQueryJoin; &libgda-GdaQueryFieldAll; &libgda-GdaQueryFieldField; &libgda-GdaQueryFieldFunc; &libgda-GdaQueryFieldAgg; &libgda-GdaQueryFieldValue; &libgda-GdaQueryCondition; &libgda-util; &libgda-log; &libgda-quark-list; &libgda-transaction; &libgda-GdaBlob; &libgda-GdaObject; &libgda-GdaObjectRef; &libgda-GdaGraphviz; &libgda-GdaDataModelRow; &libgda-GdaQueryField; &libgda-GdaQueryObject; &libgda-GdaThreader; &libgda-GdaGraph; &libgda-GdaGraphQuery; &libgda-GdaGraphItem; &libgda-GdaEntity; &libgda-GdaEntityField; &libgda-GdaXmlStorage; &libgda-GdaRenderer; &libgda-GdaReferer; &LIBGDA; offers several command line tools to help disgnose and resolve problems. All the provided tools can be run with the "--help" command line argument to give an online help and description. The gda-list-config tool simply lists all the declared data sources, and all the installed providers, giving some other usefull information as well for each. The gda-diagnose tool is a quite exhaustive and verbose testing program which output several HTML files in a specified directory (DIAGNOSE_OUTPUT by default). It can either test a single data source or all the data sources if none is specified. Running this tool can be time consuming... The tool tests: Data sources (or one if one is provided): All the installed providers when connection is provided The gda-author-dict-file tool allows to create a XML dictionary file which can be loaded into a #GdaDict object, specifying a data source to use. Specifically it does (depending on command line options): reports errors if the XML file already exists can't be loaded synchronizes the contents of the dictionary with a data source The gda-inspect-dict-file tool tests an existing XML dictionary file and (depending on command line options): reports errors if the file can't be loaded or if saving it back produces a different file lists all the pre-defined queries and creates .dot files for each of them For each different data source supported by &LIBGDA; there must be a GObject that implements the virtual methods defined in &GDASERVERPROVIDER; class. Providers must also create their own object to implement the virtual methods defined in &GDADATAMODEL; or one of its subclasses (currently &GDADATAMODELARRAY; and &GDADATAMODELHASH;) to support recordsets. Since &LIBGDA; itself is developed in the C language, and that most providers are also implemented in that language, the &LIBGDA; library itself contains a set of helper classes and functions to guide you in the addition of a new provider to the GDA framework. The &GDASERVERPROVIDER; is the class you should implement for adding a new provider. This class is just a typical GObject-based class, with a set of virtual methods, that are the ones that you must implement. These virtual methods are declared in the class structure, in the gda-server-provider.h file. They are explained in detail in the following subsections. Sets up the connection to the database back-end using the parameters received as arguments and returns a boolean TRUE if the connection is successfully established, otherwise FALSE. Frees the resources allocated for the connection and returns TRUE if everything is ok Returns the name of the currently open database for a given connection. Change the database being used in the active connection. Returns the parameters which would be required to perform a specific action (such as create a database) Actually perform an action (such as create a database) using parameters for which a list has been obtained using the get_specs() virtual method. Creates a new database whose name is received in a parameter. Drops an existing database whose name is received in a parameter. Executes a command and returns a GList of &GDADATAMODEL; with the results. Initiates a transaction if the DB back-end supports transactions. Commits a transaction if the DB back-end supports transactions. Rollback a transaction if the DB back-end supports transactions. Tests if a given feature is supported by the provider and the DB back-end. You can view the list of features in gda-connection.h, enumeration GdaConnectionFeature. Returns a &GDADATAMODEL; with the schema information requested. You can view the list of features in gda-connection.h, enumeration GdaConnectionSchema. This schema information is what describes the objects in the database, and is the way applications can manage the structure of several database systems without knowing anything about their specific way of retrieving this information. The get_schema virtual method gets a GdaConnectionSchema argument, which describes the kind of schema the client making the call is interested in, along with a GdaParameterList argument, which contains the list of arguments sent by the user to explicitly provide more information for the search. The information to be returned for each schema, along with the supported parameters, is described in the following table. Object type GDA identifier Supported Parameters Returned fields Databases GDA_CONNECTION_SCHEMA_DATABASES name Schemas (also namespaces), a feature supported by Postgres which allows to define multiple domains within a single database GDA_CONNECTION_SCHEMA_NAMESPACES name Tables GDA_CONNECTION_SCHEMA_TABLES "name" (name of table, optional) name, owner, comments, SQL definition Tables' parents GDA_CONNECTION_SCHEMA_PARENT_TABLES "name" (name of table, optional) name, order of inheritance Views GDA_CONNECTION_SCHEMA_VIEWS "name" (name of view, optional) name, owner, comments, SQL definition Table (or view) fields GDA_CONNECTION_SCHEMA_FIELDS "name" (name of table (or view), required) name, type, size, scale, not null?, primary key?, unique index?, references, default value, comma separated extra attributes (AUTO_INCREMENT) Sequences GDA_CONNECTION_SCHEMA_SEQUENCES "name" (name of sequence, optional) name, owner, comments, SQL definition Procedures GDA_CONNECTION_SCHEMA_PROCEDURES "name" (name of procedure, optional) name, unique id, owner, comments, return type, number of arguments, arguments types (arguments types in the order, comma separated) and SQL definition. For the arguments where any type is accepted, '-' is returned as type. Aggregates GDA_CONNECTION_SCHEMA_AGGREGATES "name" (name of aggregate, optional) name, unique id, owner, comments, return type, argument type, SQL definition. If the argument can be of any type, then '-' is returned as type. Types GDA_CONNECTION_SCHEMA_TYPES "name" (name of type, optional) name, owner, comments, GDA type, synonyms (comma separated) Tables' constraints GDA_CONNECTION_SCHEMA_CONSTRAINTS "name" (name of table) constraint name, constraint type (FOREIGN_KEY, PRIMARY_KEY, UNIQUE, CHECK), on fields (comma separated), definition, options (ON_UPDATE_*, ON_DELETE_*, DEFERRABLE, INITIALLY_DEFERRED) You have to extend one of &GDADATAMODEL;, &GDADATAMODELARRAY; or &GDADATAMODELHASH;. The easiest to extend are the last two. They both derive from &GDADATAMODEL;. Here is the list of methods that you have to override. If you use &GDADATAMODELHASH;, you don't need to override append_row. get_n_rows Returns the number of rows in the data model. If the provider can know in advance the number of rows the database server has returned, this function should just return that, and not retrieve any data. On the other hand, if it can't it should either retrieve all data, or move to the last record in the recordset and retrieve the row number, if the underlying data source allows it. get_n_columns Returns the number of columns in the data model. describe_column Returns information about a given column, in the form of a GdaColumn. get_row Retrieves a row from the data model. This function is very important for the implementation of editable data models. What this function returns is a GdaRow, which providers should uniquely identify (via gda_row_set_id). This is needed so that later on, client applications can use the same GdaRow returned by this method in the update_row and remove_row methods. get_value_at Returns the value stored in a given cell of the data model. is_editable Checks whether the data model can be modified or not. If the provider supports the edition of data models, it should return TRUE in this function. If it doesn't (for instance, because it can't uniquely identify rows in the data model), it should return FALSE. Before a data model can be edited, client applications must call the gda_data_model_begin_edit function, which emits the "begin_edit" signal on the GdaDataModel class. So, providers should connect to this signal to be informed when the data model starts being editing. In the callback connected to that signal, it should start a transaction, for instance. In a similar way, there are 2 other signals that provider's data model implementations should pay attention to. Those are "end_edit" and "cancel_edit". In "end_edit", if all went ok, providers should COMMIT the transaction started in "begin_edit". In "cancel_edit", a ROLLBACK should be made. append_row Appends a row to the data model. Usually, this means, in the provider, executing an INSERT SQL command on the table being read by the data model. update_row Updates an existing row in the data model. The row should have been uniquely identified in the provider code, as explained for the get_row method. remove_row Removes a row from the data model. Usually, this means, in the provider, executing a DELETE SQL command on the table being read by the data model. The row should have been uniquely identified in the provider code, as explained for the get_row method. &libgda-GdaServerProvider; FIXME: place here an introduction about reports &LIBGDA; includes a built-in reporting engine which allows applications to easily create, manage and run custom reports. &libgda-report-types; &libgda-report-document; &libgda-report-item; &libgda-report-item-detail; &libgda-report-item-label; &libgda-report-item-pagefooter; &libgda-report-item-pageheader; &libgda-report-item-repfield; &libgda-report-item-report; &libgda-report-item-reportfooter; &libgda-report-item-reportheader; &libgda-report-item-sqlquery; &libgda-report-result; &libgda-report-valid; &fdl-appendix;