[tracker/libtracker-sparql: 36/43] libtracker-sparql: Added examples in documentation
- From: Jürg Billeter <juergbi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tracker/libtracker-sparql: 36/43] libtracker-sparql: Added examples in documentation
- Date: Mon, 9 Aug 2010 15:55:14 +0000 (UTC)
commit 7406065e9e9df7ddeecc66adc3b13a3007dde3f3
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 <tracker-sparql.h>
+
+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, &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 <urn:example:0001>
+ INSERT INTO <urn:example:0001> {
+ <urn:example:0001> 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 <tracker-sparql.h>
+
+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> (&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->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,
+ &error);
+ if (error) {
+ /* Some error happened performing the query, not good */
+ g_error ("Couldn't query the Tracker Store: '%s'",
+ error ? error->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, &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]