GNOME.org
 

[tracker] libtracker-sparql: Document further new API

commit cc2987b39fca9d9ae352826f59319dc38d7ef5f8
Author: Carlos Garnacho <carlosg gnome org>
Date:   Mon Aug 7 14:38:32 2017 +0200

    libtracker-sparql: Document further new API

 .../libtracker-sparql/libtracker-sparql-docs.sgml  |    1 +
 .../libtracker-sparql-sections.txt                 |    1 +
 docs/reference/libtracker-sparql/meson.build       |    2 +-
 docs/reference/libtracker-sparql/private-store.xml |  109 ++++++++++++++++++++
 src/libtracker-sparql/tracker-connection.vala      |   81 ++++++++++++++-
 5 files changed, 191 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml 
b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index 0c6b28c..fb0e517 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -48,6 +48,7 @@
   </part>
 
   <xi:include href="ontologies.sgml"/>
+  <xi:include href="private-store.xml"/>
   <xi:include href="examples.sgml"/>
   <xi:include href="migrating-1to2.xml"/>
 
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt 
b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 27c8331..faf73b3 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -132,6 +132,7 @@ tracker_sparql_builder_construct_update
 <TITLE>TrackerSparqlConnection</TITLE>
 TrackerSparqlError
 TrackerSparqlConnection
+TrackerSparqlConnectionFlags
 tracker_sparql_connection_get
 tracker_sparql_connection_get_async
 tracker_sparql_connection_get_finish
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index 173a107..6af2b46 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -5,5 +5,5 @@ version_xml = configure_file(input: 'version.xml.in',
 gnome.gtkdoc('libtracker-sparql',
     src_dir: 'src/libtracker-sparql',
     main_sgml: 'libtracker-sparql-docs.sgml',
-    content_files: ['overview.sgml', 'examples.sgml', 'migrating-1to2.xml'],
+    content_files: ['overview.sgml', 'examples.sgml', 'ontologies.sgml', 'private-store.xml' 
'migrating-1to2.xml'],
     install: true)
diff --git a/docs/reference/libtracker-sparql/private-store.xml 
b/docs/reference/libtracker-sparql/private-store.xml
new file mode 100644
index 0000000..6fe5872
--- /dev/null
+++ b/docs/reference/libtracker-sparql/private-store.xml
@@ -0,0 +1,109 @@
+<?xml version='1.0' encoding="UTF-8"?>
+
+<part id="tracker-private-store" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <title>Isolating tracker-store clients</title>
+  <partintro>
+    <para>
+      Every user of tracker_sparql_connection_get() or tracker_sparql_connection_get_async()
+      relies on an external tracker-store instance to maintain the database, and possibly
+      on additional tracker miners to write the data consumed by the application.
+    </para>
+    <para>
+      Traditionally there has been only a single instance of tracker-store and miners,
+      shared by all consumers of Tracker data. With Tracker 2.0 it became possible to let
+      clients spawn their own sets of these services.
+    </para>
+  </partintro>
+
+  <chapter id="private-daemons">
+    <title>Defining a private domain ontology</title>
+    <para>
+      In order to make Tracker aware of this private setup, a domain ontology rule
+      must be dropped by the application on $(datadir)/tracker/domain-ontologies/,
+      the file name will be usually the DBus name or application ID of the client
+      prepended by ".rule", eg. org.example.App.rule
+    </para>
+    <para>
+      The following example would allow org.example.App to set up a private set
+      of services to index the filesystem.
+    </para>
+    <programlisting>
+[DomainOntology]
+# All locations accept
+# 1) Paths relative from a variable, the variables
+#    may be: HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR,
+#    XDG_DESKTOP_DIR, XDG_DOCUMENTS_DIR, XDG_DOWNLOAD_DIR,
+#    XDG_MUSIC_DIR, XDG_PICTURES_DIR, XDG_PUBLICSHARE_DIR,
+#    XDG_VIDEOS_DIR.
+#
+#    eg. $XDG_CACHE_HOME/...
+#
+# 2) URIs
+#
+#    eg. file:///var/...
+#
+
+# Location for the Tracker database (not optional)
+CacheLocation=$XDG_CACHE_HOME/example-app
+
+# Location for the data journal, used in data recovery
+# situations (optional)
+JournalLocation=$XDG_DATA_HOME/example-app/journal
+
+# Name of the ontology to use, must be one located in
+# $(sharedir)/tracker/ontologies
+OntologyName=nepomuk
+
+# DBus name for the owner (not optional). Tracker will use
+# the domain as the prefix of the DBus name for all the
+# services related to this domain ontology.
+#
+# eg. org.gnome.Photos
+Domain=org.example.App
+
+# Miners that the domain ontology will require. This is
+# purely a hint (mainly for libtracker-control), and not
+# any sort of white list. Anything else knowing about this
+# domain ontology may still perform updates, miners and
+# non-miners.
+Miners=Miner.Files;Miner.Extract;
+    </programlisting>
+    <para>
+      The client could then instruct Tracker libraries to use
+      this private set up through the following call:
+    </para>
+    <programlisting>
+tracker_sparql_connection_set_domain ("org.example.App");
+    </programlisting>
+  </chapter>
+  <chapter id="recommendations">
+    <title>Additional precautions and recommendations</title>
+    <para>
+      In order to work flawlessly with the created services, the
+      client must adopt some precautions that were optional in the
+      past, but now have become mandatory.
+    </para>
+    <formalpara>
+      <title>Use TrackerNotifier to receive notifications</title>
+      <para>
+       Listening directly to the GraphUpdated DBus signal will yield
+       the wrong results, since it relies on the DBus name adopted by
+       the default tracker-store service.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Use TrackerMinerManager to ensure services are started</title>
+      <para>
+       The miner lifetime has been traditionally unclear, being those
+       usually deemed a system service that would usually be there.
+       When using private services that assumption can't hold true,
+       so the client is responsible for ensuring those services are
+       started.
+      </para>
+      <para>
+       Note that this is the recommended behavior anyway even if the
+       client were not to use private services.
+      </para>
+    </formalpara>
+  </chapter>
+</part>
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index 9123329..4f99ebc 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -158,6 +158,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 
        /**
         * tracker_sparql_connection_remote_new:
+        * @uri_base: Base URI of the remote connection
         *
         * Returns: a new remote #TrackerSparqlConnection. Call g_object_unref() on the
         * object when no longer used.
@@ -168,23 +169,71 @@ public abstract class Tracker.Sparql.Connection : Object {
 
        /**
         * tracker_sparql_connection_local_new:
+        * @flags: Flags to define connection behavior
+        * @store: Location for the database
+        * @journal: Location for the operation journal, or %NULL
+        * @ontology: Location of the ontology used for this connection, or %NULL
+        * @cancellable: A #GCancellable
+        * @error: The error which occurred or %NULL
         *
         * Returns: a new local #TrackerSparqlConnection using the specified
         * @cache/@journal locations, and the ontology specified in the @ontology
         * directory. Call g_object_unref() on the object when no longer used.
         *
-        * Since: 1.12
+        * This database connection is considered entirely private to the calling
+        * process, if multiple processes use the same journal/cache locations,
+        * the results are unpredictable.
+        *
+        * The @journal is used to rebuild the database in case of data corruption,
+        * if %NULL is provided, the same location than @store will be assumed.
+        *
+        * The caller is entirely free to define an ontology or reuse Nepomuk for
+        * its purposes. For the former see the "Defining ontologies" section in
+        * this library docs. For the latter pass a %NULL @ontology.
+        *
+        * The @ontology argument may be a resource:/// URI, a directory location
+        * must be provided, all children .ontology and .description files will
+        * be read.
+        *
+        * The @store and @journal arguments expect directories, and those are
+        * assumed to be entirely private to Tracker.
+        *
+        * Since: 2.0
         */
        public extern static new Connection local_new (Tracker.Sparql.ConnectionFlags flags, File store, 
File? journal, File? ontology, Cancellable? cancellable = null) throws Sparql.Error, IOError;
 
        /**
         * tracker_sparql_connection_local_new_async:
+        * @flags: Flags to define connection behavior
+        * @store: Location for the database
+        * @journal: Location for the operation journal, or %NULL
+        * @ontology: Location of the ontology used for this connection, or %NULL
+        * @cancellable: A #GCancellable
+        * @_callback_: user-defined #GAsyncReadyCallback to be called when
+        *              asynchronous operation is finished.
+        * @_user_data_: user-defined data to be passed to @_callback_
         *
         * Returns: a new local #TrackerSparqlConnection using the specified
         * @cache/@journal locations, and the ontology specified in the @ontology
         * directory. Call g_object_unref() on the object when no longer used.
         *
-        * Since: 1.12
+        * See tracker_sparql_connection_local_new() for more details.
+        *
+        * Since: 2.0
+        */
+
+       /**
+        * tracker_sparql_connection_local_new_finish:
+        * @_res_: a #GAsyncResult with the result of the operation
+        * @error: #GError for error reporting.
+        *
+        * Finishes the asynchronous local database creation/loading.
+        *
+        * Returns: The #TrackerSparqlConnection for the local endpoint.
+        * On error, #NULL is returned and the @error is set accordingly.
+        * Call g_object_unref() on the returned connection when no longer needed.
+        *
+        * Since: 2.0
         */
        public extern async static new Connection local_new_async (Tracker.Sparql.ConnectionFlags flags, File 
store, File? journal, File? ontology, Cancellable? cancellable = null) throws Sparql.Error, IOError;
 
@@ -528,6 +577,34 @@ public abstract class Tracker.Sparql.Connection : Object {
                return null;
        }
 
+       /**
+        * tracker_sparql_connection_set_domain:
+        * @domain: The domain name for the default connection
+        *
+        * Sets the domain (usually a DBus name or application ID) that
+        * will be used on on the connection obtained by
+        * tracker_sparql_connection_get(). See the "Isolating tracker-store
+        * clients" section in this library docs.
+        *
+        * This function must be called
+        * before any of these such tracker_sparql_connection_get() calls
+        * could happen.
+        *
+        * Since: 2.0
+        */
        public extern static void set_domain (string? domain);
+
+       /**
+        * tracker_sparql_connection_get_domain:
+        *
+        * Gets the domain (usually a DBus name or application ID) that
+        * will be used on on the connection obtained by
+        * tracker_sparql_connection_get().
+        * See tracker_sparql_connection_set_domain() for more information.
+        *
+        * Returns: (transfer full): The domain string, or %NULL if none is set
+        *
+        * Since: 2.0
+        */
        public extern static string? get_domain ();
 }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]