GNOME.org
 

[libgda: 1/2] Doc: Updating documentation

commit 6689896d473da0749493e214c510e72378c132b5
Author: Pavlo Solntsev <p sun fun gmail com>
Date:   Tue Feb 18 13:52:50 2020 -0600

    Doc: Updating documentation

 doc/C/libgda/introduction.xml    | 262 +++++++++++++++++++++++++++++++++++++++
 doc/C/libgda/libgda-6.0-docs.xml |  44 ++++++-
 2 files changed, 302 insertions(+), 4 deletions(-)
---
diff --git a/doc/C/libgda/introduction.xml b/doc/C/libgda/introduction.xml
new file mode 100644
index 000000000..e9d79afd4
--- /dev/null
+++ b/doc/C/libgda/introduction.xml
@@ -0,0 +1,262 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";[
+<!ENTITY LIBGDA          "<application>Libgda</application>">
+<!ENTITY GNOMEDB         "<acronym>Gnome-Db</acronym>">
+<!ENTITY RPM             "<acronym>RPM</acronym>">
+<!ENTITY ODBC            "<acronym>ODBC</acronym>">
+<!ENTITY SQL             "<acronym>SQL</acronym>">
+<!ENTITY LDAP            "<acronym>LDAP</acronym>">
+<!ENTITY JDBC            "<acronym>JDBC</acronym>">
+<!ENTITY GDA             "<acronym>GDA</acronym>">
+<!ENTITY RDBMS           "<acronym>RDBMS</acronym>">
+<!ENTITY API             "<acronym>API</acronym>">
+]>
+
+<chapter id="introduction">
+  <title>Introduction</title>
+  <sect1 id="introduction-overview">
+    <title>Overview</title>
+    <para>
+        &ODBC; and &SQL; are established standards. However &ODBC; is mostly limited to
+      the Microsoft Windows environment (even though the UnixODBC project exists and links
+      to some drivers), and the API is quite old and not well integrated into the GNOME ecosystem.
+    </para>
+    <para>
+        &SQL; itself is standardized but up to some point only, so that &SQL; source
+      compatibility can not be assured for all database servers. And for some
+      sort of servers, &SQL; is not even feasible (think about &LDAP;).
+    </para>
+    <para>
+        &JDBC; is a more recent standard which replaces &ODBC; in the Java world, but it's limited
+      to the Java programming world, and is difficult to integrate in C (or other languages
+      different from Java). There are however a lot of JDBC drivers out there for many database
+      engines.
+    </para>
+    <para>
+        &GDA; (GNOME Data Access) tries to tackle the &ODBC; and &JDBC; "limitations" and help you with the 
&SQL;
+      problem. It's a sort of middleware 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.
+    </para>
+    <para>
+      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
+      knowing much about it. It comes as a set of libraries, a core one and some extensions (the GTK+ UI
+      extension for example) and some drivers for the most common OpenSource or proprietary database engines.
+    </para>
+    <para>
+      Some of these drivers are a bit special: the LDAP provider allows one to adress an LDAP directory as
+      if it were composed of tables (provided some configuration), and the &JDBC; provider "wraps" any 
&JDBC; driver.
+    </para>
+    <para>
+      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.
+    </para>
+    <para>
+        &LIBGDA; is implemented for
+      <systemitem class="osname">UNIX</systemitem>
+        -like operating systems
+        (including
+      <systemitem class="osname">Linux</systemitem>
+        ), and
+      <systemitem class="osname">Windows</systemitem>
+        .
+    </para>
+  </sect1>
+
+  <sect1 id="features">
+    <title>Features</title>
+    <para>
+      This section presents the main features of the 5.2 version of Libgda.
+    </para>
+    <para>
+      Libgda is a low-level database abstraction layer built on top of each database C API. In terms of 
abstraction,
+      Libgda offers the following top features:
+      <itemizedlist>
+        <listitem>
+          <para>
+            Open a connection to any database which type is supported using either a defined data source 
(defined per
+            user or system wide) or directly providing connection parameters. Several connections can be 
opened at the
+            same time.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Run any SQL query against an opened connection; furthermore any SQL query can be extended to 
define query parameters
+            using an easy to understand notation. If the SQL query was a SELECT statement, then an array of 
data is
+            returned (as a <classname>GdaDataModel</classname> object), and otherwise the number of rows 
affected
+              by the query is returned. For very large data sets, it is possible to specify that the 
returned array
+              of data should be based on a cursor to avoid loading it into memory.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Perform most of the data definition queries (including database creation) for the database types 
which support
+            it using a key/value mechanism.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Create, maintain and extend a view of the database's structure and meta data including the 
definitions of
+            the tables, constraints, data types, .... It is defined as closely as possible to the 
information schema SQL
+            standard (ISO/IEC 9075); see the <link linkend="gda-dict">Dictionary - metadata</link> section 
+              for more information.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Easy to extend data models for custom requirements
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+              Support for binary data and for BLOBs in a transparent way, see the <link 
linkend="libgda-Gda-Value">Gda value section</link>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Support for detailed parameters in SQL queries, see the <link 
linkend="GdaSqlParser">GdaSqlParser</link> object
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+              Support for virtual connections, see the <link linkend="virtual_connection">Virtual 
connections chapter</link>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Partially thread-safe, see <link linkend="threads">the threads limitation</link> for
+              more details
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      The database types which can be accessed at the time of writing are the following ones:
+      <itemizedlist>
+        <listitem>
+          <para>
+            MySQL: fully functional;
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            PostgreSQL: fully functional;
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            SQLite: fully functional;
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            SQLCipher: fully functional;
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+  </sect1>
+  <sect1 id="architecture">
+    <title>Architecture</title>
+    <para>
+      A &LIBGDA; application is composed of three layers. The lower level layer are
+      the &GDA; providers: plug-ins whose task is to map the &RDBMS;-specific &API;
+      to the &GDA; model.
+    </para>
+    <para>
+      Then, in a middle layer, are the libraries provided by &LIBGDA; and used by
+      the programmer: an easy-to-use and
+      full featured set of libraries.
+    </para>
+    <para>
+      Finally, at the upper layer is the application part itself, as writen by the
+      developer.
+    </para>
+    <mediaobject>
+      <imageobject role="html">
+        <imagedata fileref="architecture.png" format="PNG"/>
+      </imageobject>
+      <textobject>
+        <phrase>Typical &LIBGDA; application's architecture</phrase>
+      </textobject>
+      <caption>
+        <para>
+          Architecture of an application connected to 4 databases of 3 different types.
+        </para>
+      </caption>
+    </mediaobject>
+    <para>
+        &LIBGDA; also includes:
+      <itemizedlist>
+        <listitem>
+          <para>
+            some example code which can be "cloned" to create new database providers for
+              database engines not yet supported by &LIBGDA;
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            a graphical configuration manager
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            an <link linkend="libgda-sql">SQL console</link> to connect to dabatase serveurs and perform some
+              &LIBGDA; related administrative tasks
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+              some other more <link linkend="part_tools">specific tools</link>
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
+  </sect1>
+  <sect1 id="data-source">
+    <title>Data sources</title>
+    <para>
+      To open a connection, the programmer needs to specify the database provider to use, and some
+      connection parameters, some of them specific to the database engine to be used, some of them
+      more generic (such as the "DB_NAME" parameter to specify a database name).
+    </para>
+    <para>
+      All the parameters are combined together to give &LIBGDA; enough information to open a connection; 
refer
+      to <link linkend="gda-connection-new-from-string">gda_connection_new_from_string()</link> for more
+        information.
+    </para>
+    <para>
+      However, remembering the complete string to open a connection can be tedious, and so &LIBGDA; supports
+      named data sources (DSN) whereby a connection is specified and named once and opened refering to
+      its name rather than to the actual parameters used. Refer to
+      the <link linkend="defining_dsn">Define a data source (DSN)</link> section, and the
+      <link linkend="gda-config-define-dsn">gda_config_define_dsn()</link> and
+      <link linkend="gda-connection-new-from-dsn">gda_connection_new_from_dsn()</link> functions.
+    </para>
+    <para>
+      DSN can have a scope limited to the user, or be system wide. User scope DSN definitions are stored
+      in $XDG_DIR/libgda where $XDG_DIR is determined by the XDG Base Directory Specification (using
+      <link linkend="g-get-user-data-dir">g_get_user_data_dir()</link>). System wide definitions are stored
+        in $ETC/$VERSION where $ETC is the configuration directory where &LIBGDA; is installed and $VERSION
+        is &LIBGDA;'s major version.
+    </para>
+    <para>
+      Note that these locations can be changes using some properties of the global
+      <link linkend="GdaConfig">GdaConfig</link> object.
+    </para>
+  </sect1>
+  <sect1>
+    <title>Authentication information management</title>
+    <para>
+      When named data sources are used, &LIBGDA; can also store authentication information (username and
+      password). This is accomplished using
+      <ulink url="https://wiki.gnome.org/Projects/Libsecret";>libsecret</ulink>, or
+      <ulink url="https://wiki.gnome.org/Projects/GnomeKeyring";>libgnome-keyring</ulink> if available,
+        or stored in an insecure way (along the DSN definition) if none of these libraries are available.
+    </para>
+  </sect1>
+</chapter>
diff --git a/doc/C/libgda/libgda-6.0-docs.xml b/doc/C/libgda/libgda-6.0-docs.xml
index 3592ccbac..55a1bd315 100644
--- a/doc/C/libgda/libgda-6.0-docs.xml
+++ b/doc/C/libgda/libgda-6.0-docs.xml
@@ -6,21 +6,57 @@
   <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
   %gtkdocentities;
   <!ENTITY LIBGDA "libgda-6.0">
+  <!ENTITY GDA             "<acronym>GDA</acronym>">
 ]>
 <book id="index">
   <bookinfo>
     <title>&package_name; Reference Manual</title>
     <releaseinfo>
-      for &package_string;.
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" 
url="https://gitlab.gnome.org/GNOME/libgda/pipelines";>https://gitlab.gnome.org/GNOME/libgda/pipelines</ulink>,
-      from latest successful pipeline build.
+      The latest version of this documentation can be found on-line at the home
+      <ulink role="online-location" url="https://gnome.pages.gitlab.gnome.org/libgda/C/libgda/";>wiki</ulink> 
page.
     </releaseinfo>
     <xi:include href="author-list.xml"/>
+    <date>&builddate;</date>
+    <copyright>
+      <year>1999 - 2020</year>
+      <holder>&copy;</holder>
+    </copyright>
+    <abstract>
+      <para>
+        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...
+      </para>
+      <para>
+        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.
+      </para>
+    </abstract>
+    <legalnotice id="legalnotice">
+      <para>
+        Permission is granted to copy, distribute and/or modify this document
+        under the terms of the <link linkend="fdl"><citetitle>GNU
+        Free Documentation License</citetitle></link>, 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 <link linkend="fdl">the appendix</link>.
+      </para>
+      <para>
+        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.
+      </para>
+    </legalnotice>
   </bookinfo>
 
   <part id="Getting Started">
     <title>Getting Started</title>
+    <xi:include href="introduction.xml"/>
     <xi:include href="xml/libgda.xml"/>
     <xi:include href="installation.xml"/>
   </part>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]