GNOME.org
 

[libgda] Doc. updates

commit 24e8daecdb42bd08a808937043f4128743ddba52
Author: Vivien Malerba <malerba gnome-db org>
Date:   Sun Nov 23 17:04:56 2014 +0100

    Doc. updates

 doc/C/howto.xml            |    2 +-
 doc/C/installation.xml     |    5 ++
 doc/C/libgda-6.0-docs.sgml |  119 +++++++++++++++++++++++++++++++------------
 doc/C/limitations.xml      |   47 +++--------------
 doc/C/prov-notes.xml       |    4 ++
 5 files changed, 105 insertions(+), 72 deletions(-)
---
diff --git a/doc/C/howto.xml b/doc/C/howto.xml
index 04fd841..26b2e82 100644
--- a/doc/C/howto.xml
+++ b/doc/C/howto.xml
@@ -38,7 +38,7 @@ else {
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="defining_dsn">
     <title>Define a data source (DSN)</title>
     <para>
       The <link linkend="libgda-6.0-Configuration">Configuration section</link> details how to manage data 
sources
diff --git a/doc/C/installation.xml b/doc/C/installation.xml
index 5f796f8..95631c2 100644
--- a/doc/C/installation.xml
+++ b/doc/C/installation.xml
@@ -236,6 +236,11 @@
          named "SalesTest". 
        </para>
       </sect3>
+      <sect3 id="installation-provider-default">
+       <title>JDBC based providers</title>
+       <para>Refer to the <link linkend="provider_notes_jdbc">JDBC notes</link> section for more information.
+       </para>
+      </sect3>
       <sect3 id="installation-provider-all">
        <title>Connection information for each database provider</title>
        <para>
diff --git a/doc/C/libgda-6.0-docs.sgml b/doc/C/libgda-6.0-docs.sgml
index 3b2fc9f..923f51a 100644
--- a/doc/C/libgda-6.0-docs.sgml
+++ b/doc/C/libgda-6.0-docs.sgml
@@ -269,40 +269,93 @@
       </para>
     </chapter>
     
-    <chapter id="architecture">
+    <chapter>
       <title>Architecture</title>
-      <para>
-       &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 <acronym>RDBMS</acronym>-specific &API; to the &GDA; model.
-       That is, they are objects implementing the &GDA; interfaces.
-      </para>
-      <para>
-       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.
-      </para>
-      <para>
-       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.
-      </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>
+      <section>
+       <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 <acronym>RDBMS</acronym>-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>
+      </section>
+
+
+      <section>
+       <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 osing some properties of the global
+         <link linkend="GdaConfig">GdaConfig</link> object.
+       </para>
+      </section>
+
+      <section>
+       <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>
+      </section>
     </chapter>
 
     <xi:include href="abstraction.xml"/>
diff --git a/doc/C/limitations.xml b/doc/C/limitations.xml
index 76270f0..1b1b4df 100644
--- a/doc/C/limitations.xml
+++ b/doc/C/limitations.xml
@@ -10,7 +10,7 @@
     <para>
       &LIBGDA;'s global limitations are:
       <sect2 id="threads"><title>Multi threaded environment</title>
-       <para>&LIBGDA; is not thread safe. However it supports working with threads as long as any object 
+       <para>&LIBGDA; is not thread safe, however it supports working with threads as long as any object 
          (except otherwise stated) created by the API is used by one single thread (that is there is no
          situation when two threads try to access the same object at the same time). Exceptions are:
          <itemizedlist>
@@ -21,29 +21,17 @@
                lock an object's usage (especially when getting and
                setting properties before or after calling methods).</para></listitem>
            <listitem><para>Any <link linkend="GdaConnection">GdaConnection</link> object can be accessed 
from any thread 
-               (that object implements the <link linkend="GdaLockable">GdaLockable</link> interface). Also
-               some database providers may impose other limitations (inherited from the database's specific 
client APIs)
-               such as only one thread can use the connection object, or even that only one thread can use 
the database
-               provider.</para></listitem>
+               (that object implements the <link linkend="GdaLockable">GdaLockable</link> interface). 
Specifically
+               &LIBGDA; removes the limits imposed by some database provider's API regarding 
threads.</para></listitem>
            <listitem><para>Any <link linkend="GdaAttributesManager">GdaAttributesManager</link> can safely 
be accessed from
                any thread.</para></listitem>
          </itemizedlist>
        </para>
-       
-       <para>Note that multi threading support is still at an early stage and may contain bugs</para>
       </sect2>
     </para>
   </sect1>
 
   <sect1 id="limitations_mysql"><title>For MySQL</title>
-    <sect2><title>Multi threaded environment</title>
-      <para>
-       If MySQL client was not compiled with the <option>--enable-thread-safe-client</option> flag, 
-       then the database provider will only allow
-       connections to be opened from the thread which initializes &LIBGDA;. Otherwise there is no limitation.
-      </para>
-    </sect2>
-
     <sect2><title>Statements execution</title>
       <para>
        <itemizedlist>
@@ -64,7 +52,6 @@
        time but GMT.
       </para>
     </sect2>
-
   </sect1>
 
   <sect1 id="limitations_oracle"><title>For Oracle</title>
@@ -107,14 +94,6 @@
       </para>
     </sect2>
 
-    <sect2><title>Multi threaded environment</title>
-      <para>
-       If PostgreSQL was not compiled with the <option>--enable-thread-safety</option> flag, 
-       then the database provider will only allow
-       connections to be opened from the thread which initializes &LIBGDA;. Otherwise there is no limitation.
-      </para>
-    </sect2>
-
     <sect2><title>Statements execution</title>
       <para>
        <itemizedlist>
@@ -167,14 +146,6 @@
       </para>
     </sect2>
 
-    <sect2><title>Multi threaded environment</title>
-      <para>
-       No limitation if sqlite has been compiled with the SQLITE_THREADSAFE=1 flag (which is the case for the
-       embedded version of SQLite). If the system installed SQLite is used and if it was not compiled using 
that
-       flag, then &LIBGDA; sets the SQLite library in a state where multi threading is fully supported.
-      </para>
-    </sect2>
-
     <sect2><title>Error reporting</title>
       <para>
        If there is not enough free space on the disk which stores an SQLite database, you may have some
@@ -236,17 +207,17 @@
       needs to load the Java Virtual Machine (JVM) runtime first).
     </para>
 
+    <para>
+      The JDBC provider is a bit specific since it needs to be installed to be used, but it also requires 
external
+      JDBC drivers (usually published by the database's editor). As a result, actual JDBC drivers will be 
useable
+      only when the two conditions are met.
+    </para>
+
     <sect2><title>Last inserted row's values</title>
       <para>
        Not yet supported.
       </para>
     </sect2>
-
-    <sect2><title>Multi threaded environment</title>
-      <para>
-       No specific limitation.
-      </para>
-    </sect2>
   </sect1>
   
 </chapter>
diff --git a/doc/C/prov-notes.xml b/doc/C/prov-notes.xml
index a9ceefe..e54a7f9 100644
--- a/doc/C/prov-notes.xml
+++ b/doc/C/prov-notes.xml
@@ -408,6 +408,10 @@ DETACH DATABASE plaintext; </programlisting>
        or provide the URL parameter (like for any JDBC provider) to specify a connection to open.
       </para>
     </sect2>
+
+    <para>
+      Also refer to the <link linkend="limitations_jdbc">JDBC provider's limitations</link>.
+    </para>
   </sect1>
   
 </chapter>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]