GNOME.org
 

[tracker/libtracker-sparql: 49/56] libtracker-sparql: Added examples in documentation

commit 795b8b4cfd2bceb397823eee6e9643146b042475
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Wed Aug 4 12:31:54 2010 +0200

    libtracker-sparql: Added examples in documentation

 docs/reference/libtracker-sparql/examples.xml      |  184 ++++++++++++++++++++
 .../libtracker-sparql/libtracker-sparql-docs.sgml  |    8 +-
 .../libtracker-sparql-sections.txt                 |    2 +-
 src/libtracker-sparql/tracker-connection.vala      |   20 ++-
 src/libtracker-sparql/tracker-cursor.vala          |    5 +-
 src/libtracker-sparql/tracker-uri.c                |    4 -
 6 files changed, 206 insertions(+), 17 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
new file mode 100644
index 0000000..9975c53
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -0,0 +1,184 @@
+<?xml version='1.0' encoding="ISO-8859-1"?>
+
+<part id="tracker-examples">
+  <title>Examples</title>
+  <partintro>
+    <para>
+      This chapters shows some real examples of usage of the Tracker SPARQL Library.
+    </para>
+  </partintro>
+
+
+  <chapter id="tracker-examples-builder">
+    <title>Generating proper SPARQL queries with the Builder</title>
+
+    <para>
+      The Tracker SPARQL library provides an easy and secure way of creating
+      SPARQL queries with the proper syntax. This is achieved using the
+      <type><link linkend="TrackerSparqlBuilder-struct">TrackerSparqlBuilder</link></type>
+      object.
+    </para>
+
+    <para>
+<programlisting>
+#include &lt;tracker-sparql.h&gt;
+
+int main (int argc, char **argv)
+{
+  <type><link linkend="TrackerSparqlBuilder-struct">TrackerSparqlBuilder</link></type> *builder;
+  const gchar *iri = "urn:example:0001";
+  const gchar *query_str;
+  time_t now = time (NULL);
+
+
+  /* Initialize GLib type system */
+  g_type_init ();
+
+  /* Create builder */
+  builder = <function><link linkend="tracker-sparql-builder-new-update">tracker_sparql_builder_new_update</link></function> ();
+
+  /* Drop previous data */
+  <function><link linkend="tracker-sparql-builder-drop-graph">tracker_sparql_builder_drop_graph</link></function> (builder, iri);
+
+  /* Insert new data */
+  <function><link linkend="tracker-sparql-builder-insert-open">tracker_sparql_builder_insert_open</link></function> (builder, iri);
+
+  <function><link linkend="tracker-sparql-builder-subject-iri">tracker_sparql_builder_subject_iri</link></function> (builder, iri);
+
+  <function><link linkend="tracker-sparql-builder-predicate">tracker_sparql_builder_predicate</link></function> (builder, "a");
+  <function><link linkend="tracker-sparql-builder-object">tracker_sparql_builder_object</link></function> (builder, "nie:DataObject");
+  <function><link linkend="tracker-sparql-builder-object">tracker_sparql_builder_object</link></function> (builder, "nfo:FileDataObject");
+
+  <function><link linkend="tracker-sparql-builder-predicate">tracker_sparql_builder_predicate</link></function> (builder, "nfo:fileLastModified");
+  <function><link linkend="tracker-sparql-builder-object-date">tracker_sparql_builder_object_date</link></function> (builder, &amp;now);
+
+  <function><link linkend="tracker-sparql-builder-insert-close">tracker_sparql_builder_insert_close</link></function> (builder);
+
+  /* Get query as string. Do NOT g_free() the resulting string! */
+  query_str = <function><link linkend="tracker-sparql-builder-get-result">tracker_sparql_builder_get_result</link></function> (builder);
+
+  /* Print it */
+  g_print ("Generated SPARQL query: \n"
+	   "%s", query_str);
+
+  /* Once builder no longer needed, unref it. Note that after
+   * this operation, you must not use the returned query result
+   * any more */
+  g_object_unref (builder)
+
+  return 0;
+}
+</programlisting>
+
+      The previous code will generate the following SPARQL query:
+<programlisting>
+  DROP GRAPH &lt;urn:example:0001&gt;
+  INSERT INTO &lt;urn:example:0001&gt; {
+    &lt;urn:example:0001&gt; a nie:DataObject , nfo:FileDataObject ;
+                       nfo:fileLastModified "2010-08-04T13:09:26Z" .
+}
+</programlisting>
+    </para>
+  </chapter>
+
+  <chapter id="tracker-examples-readonly">
+    <title>Read-Only queries to the store</title>
+
+    <para>
+      In order to perform read-only queries to the store, a new
+      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+      object must be acquired. In this case, as there is no intention of updating any
+      value in the store, both the general connection (with
+      <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>)
+      or a specific direct-access connection (with
+      <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function>)
+      may be acquired. Note that in the latter case, every non read-only operation will result
+      in an error being thrown by the TrackerSparqlConnection.
+    </para>
+
+    <para>
+      Once a proper connection object has been acquired, the read-only query can be launched either
+      synchronously (<function><link linkend="tracker-sparql-connection-query">tracker_sparql_connection_query</link></function>)
+      or asynchronously (<function><link linkend="tracker-sparql-connection-query-async">tracker_sparql_connection_query_async</link></function>).
+      If launched asynchronously, the results of the query can be obtained with
+      <function><link linkend="tracker-sparql-connection-query-finish">tracker_sparql_connection_query_finish</link></function>.
+    </para>
+
+    <para>
+      If the query was successful, a <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>
+      will be available. You can now iterate the results of the query both synchronously (with
+      <function><link linkend="tracker-sparql-cursor-next">tracker_sparql_cursor_next</link></function>) or
+      asynchronously (with
+      <function><link linkend="tracker-sparql-cursor-next-async">tracker_sparql_cursor_next_async</link></function> and
+      <function><link linkend="tracker-sparql-cursor-next-finish">tracker_sparql_cursor_next_finish</link></function>)
+    </para>
+
+    <para>
+      Once you end up with the query, remember to call <function><link linkend="g-object-unref">g_object_unref</link></function>
+      for the <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>. And the same applies to the
+      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> when no longer needed.
+    </para>
+
+    <para>
+      The following program shows how Read-Only queries can be done to the store in a
+      synchronous way:
+
+<programlisting>
+#include &lt;tracker-sparql.h&gt;
+
+int main (int argc, const char **argv)
+{
+  GError *error = NULL;
+  <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> *connection;
+  <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type> *cursor;
+  const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
+
+  /* Initialize GLib type system */
+  g_type_init ();
+
+  /* As we know only read-only queries will be done, it's enough
+   * to use a connection with only direct-access setup. */
+  connection = <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function> (&amp;error);
+  if (!connection) {
+    /* Some error happened getting the connection, not good */
+    g_error ("Couldn't obtain a direct-access connection to the "
+             "Tracker Store: '%s'",
+             error ? error-&gt;message : "unknown error");
+  }
+
+  /* Make a synchronous query to the store */
+  cursor = <function><link linkend="tracker-sparql-connection-query">tracker_sparql_connection_query</link></function> (connection,
+  					    query,
+  					    NULL,
+  					    &amp;error);
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_error ("Couldn't query the Tracker Store: '%s'",
+             error ? error-&gt;message : "unknown error");
+  }
+
+  /* Check results... */
+  if (!cursor) {
+    g_print ("No results found :-/\n");
+  } else {
+    gint i = 0;
+    /* Iterate, synchronously, the results... */
+    while (<function><link linkend="tracker-sparql-cursor-next">tracker_sparql_cursor_next</link></function> (cursor, NULL, &amp;error)) {
+      g_print ("Result [%d]: %s\n",
+	       i++,
+	       <function><link linkend="tracker-sparql-cursor-get-string">tracker_sparql_cursor_get_string</link></function> (cursor, 0, NULL));
+    }
+    g_print ("A total of '%d' results were found\n", i);
+
+    g_object_unref (cursor);
+  }
+
+  g_object_unref (connection);
+
+  return 0;
+}
+</programlisting>
+    </para>
+  </chapter>
+</part>
+
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index 0978b6e..c1fbbb7 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -1,11 +1,12 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY version SYSTEM "version.xml">
 <!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
 <!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
 <!ENTITY tracker-sparql-cursor SYSTEM "xml/tracker-sparql-cursor.xml">
 <!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
-<!ENTITY version SYSTEM "version.xml">
+<!ENTITY tracker-examples SYSTEM "examples.xml">
 ]>
 <book id="index">
   <bookinfo>
@@ -13,6 +14,7 @@
     <releaseinfo>for libtracker-sparql &version;</releaseinfo>
   </bookinfo>
 
+  <!-- The Library Overview -->
   <part id="libtracker-sparql-overview">
     <title>Overview</title>
     <partintro>
@@ -25,6 +27,7 @@
     </partintro>
   </part>
 
+  <!-- The API Reference -->
   <part id="libtracker-sparql-reference">
     <title>Reference</title>
     <partintro>
@@ -39,4 +42,7 @@
     &tracker-misc;
   </part>
 
+  <!-- The Examples -->
+  &tracker-examples;
+
 </book>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 5d5d554..49d1b5e 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -119,7 +119,6 @@ TrackerSparqlCursor
 tracker_sparql_cursor_get_connection
 tracker_sparql_cursor_get_n_columns
 tracker_sparql_cursor_get_string
-tracker_sparql_cursor_get_type
 tracker_sparql_cursor_next
 tracker_sparql_cursor_next_async
 tracker_sparql_cursor_next_finish
@@ -134,6 +133,7 @@ TRACKER_SPARQL_ERROR
 TRACKER_SPARQL_IS_CURSOR
 TRACKER_SPARQL_IS_CURSOR_CLASS
 TRACKER_SPARQL_TYPE_CURSOR
+tracker_sparql_cursor_get_type
 <SUBSECTION Private>
 TrackerSparqlCursorPrivate
 tracker_sparql_cursor_construct
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index 04ec7b1..dddffba 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -71,7 +71,7 @@ public errordomain Tracker.Sparql.Error {
 /**
  * TrackerSparqlConnection:
  *
- * The <structname>TrackerSparqlConnection</structname> object represents an
+ * The <structname>TrackerSparqlConnection</structname> object represents a
  * connection with the Tracker Store.
  */
 public abstract class Tracker.Sparql.Connection : Object {
@@ -84,7 +84,8 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @error: #GError for error reporting.
 	 *
 	 * Returns a new #TrackerSparqlConnection, which will use the best method
-	 * available to connect to the Tracker Store.
+	 * available to connect to the Tracker Store (direct-access for Read-Only
+	 * queries, and D-Bus otherwise).
 	 *
 	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
 	 * object when no longer used.
@@ -108,7 +109,8 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @error: #GError for error reporting.
 	 *
 	 * Returns a new #TrackerSparqlConnection, which uses direct-access method
-	 * to connect to the Tracker Store.
+	 * to connect to the Tracker Store. Note that this connection will only be
+	 * able to perform Read-Only queries in the store.
 	 *
 	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
 	 * object when no longer used.
@@ -200,9 +202,9 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * Executes a SPARQL query on the store. The API call is completely
 	 * synchronous, so it may block.
 	 *
-	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
-	 * on error. Call g_object_unref() on the returned cursor when no longer
-	 * needed.
+	 * Returns: a #TrackerSparqlCursor if results were found, #NULL otherwise.
+	 * On error, #NULL is returned and the @error is set accordingly.
+	 * Call g_object_unref() on the returned cursor when no longer needed.
 	 */
 	public abstract Cursor? query (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
 
@@ -226,9 +228,9 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 *
 	 * Finishes the asynchronous SPARQL query operation.
 	 *
-	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
-	 * on error. Call g_object_unref() on the returned cursor when no longer
-	 * needed.
+	 * Returns: a #TrackerSparqlCursor if results were found, #NULL otherwise.
+	 * On error, #NULL is returned and the @error is set accordingly.
+	 * Call g_object_unref() on the returned cursor when no longer needed.
 	 */
 	public async abstract Cursor? query_async (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
 
diff --git a/src/libtracker-sparql/tracker-cursor.vala b/src/libtracker-sparql/tracker-cursor.vala
index a1f6402..5aaa0d8 100644
--- a/src/libtracker-sparql/tracker-cursor.vala
+++ b/src/libtracker-sparql/tracker-cursor.vala
@@ -80,12 +80,13 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	/**
 	 * tracker_sparql_cursor_get_string:
 	 * @self: a #TrackerSparqlCursor
-	 * @column: column number to retrieve
+	 * @column: column number to retrieve (first one is 0)
 	 * @length: length of the returned string
 	 *
 	 * Returns the string at @column in the current row being iterated.
 	 *
-	 * Returns: a string, which should not be freed by the caller.
+	 * Returns: a string, which should not be freed by the caller. #NULL
+	 * is returned if the column number is in the [0,#n_columns] range.
 	 */
 	public abstract unowned string? get_string (int column, out long length = null);
 
diff --git a/src/libtracker-sparql/tracker-uri.c b/src/libtracker-sparql/tracker-uri.c
index 1a8294c..ac84dc6 100644
--- a/src/libtracker-sparql/tracker-uri.c
+++ b/src/libtracker-sparql/tracker-uri.c
@@ -139,8 +139,6 @@ find_conversion (const char  *format,
  *
  * Returns: a newly-allocated string holding the result.
  *  The returned string should be freed with g_free() when no longer needed.
- *
- * Since: 0.9
  */
 gchar *
 tracker_sparql_escape_uri_vprintf (const gchar *format,
@@ -243,8 +241,6 @@ cleanup:
  *
  * Returns: a newly-allocated string holding the result.
  *  The returned string should be freed with g_free() when no longer needed.
- *
- * Since: 0.9
  */
 gchar *
 tracker_sparql_escape_uri_printf (const gchar *format, ...)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]