[tracker/wip/carlosg/sparql-parser-ng: 304/306] libtracker-sparql: Add TrackerSparqlStatement

[Carlos Garnacho <carlosg src gnome org>]

commit 265cb7185cd7cea4d39910e8e4c24da3d3a2d81f
Author: Carlos Garnacho <carlosg gnome org>
Date:   Mon Oct 15 23:08:18 2018 +0200

    libtracker-sparql: Add TrackerSparqlStatement
    
    This object can hold a long lived query, in which parameters may be changed
    prior to execution.

 src/libtracker-sparql-backend/tracker-sparql-2.map |   1 +
 src/libtracker-sparql/meson.build                  |   1 +
 src/libtracker-sparql/tracker-connection.vala      |  12 ++
 src/libtracker-sparql/tracker-statement.vala       | 121 +++++++++++++++++++++
 4 files changed, 135 insertions(+)
---
diff --git a/src/libtracker-sparql-backend/tracker-sparql-2.map 
b/src/libtracker-sparql-backend/tracker-sparql-2.map
index 38cba0046..3dee56514 100644
--- a/src/libtracker-sparql-backend/tracker-sparql-2.map
+++ b/src/libtracker-sparql-backend/tracker-sparql-2.map
@@ -6,6 +6,7 @@ global:
   tracker_sparql_escape_*;
   tracker_sparql_error_*;
   tracker_sparql_value_*;
+  tracker_sparql_statement_*;
   tracker_sparql_get_*;
   tracker_namespace_manager_*;
   tracker_resource_*;
diff --git a/src/libtracker-sparql/meson.build b/src/libtracker-sparql/meson.build
index 17026034b..550c08ce3 100644
--- a/src/libtracker-sparql/meson.build
+++ b/src/libtracker-sparql/meson.build
@@ -18,6 +18,7 @@ libtracker_sparql_intermediate_vala = static_library('tracker-sparql-intermediat
     'tracker-builder.vala',
     'tracker-connection.vala',
     'tracker-cursor.vala',
+    'tracker-statement.vala',
     'tracker-utils.vala',
     vala_header: 'tracker-generated-no-checks.h',
     c_args: tracker_c_args,
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index a949ea26a..d12ead222 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -635,4 +635,16 @@ public abstract class Tracker.Sparql.Connection : Object {
         * Since: 2.0
         */
        public extern static DBusConnection? get_dbus_connection ();
+
+       /**
+        * tracker_sparql_connection_query_statement:
+        *
+        * Prepares the given @sparql as a #TrackerSparqlStatement.
+        *
+        * Since: 2.2
+        */
+       public virtual Statement query_statement (string sparql, Cancellable? cancellable = null) throws 
Sparql.Error {
+               warning ("Interface 'query_statement' not implemented");
+               return null;
+       }
 }
diff --git a/src/libtracker-sparql/tracker-statement.vala b/src/libtracker-sparql/tracker-statement.vala
new file mode 100644
index 000000000..3328eb57a
--- /dev/null
+++ b/src/libtracker-sparql/tracker-statement.vala
@@ -0,0 +1,121 @@
+/*
+ * Copyright (C) 2018, Red Hat Ltd.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA  02110-1301, USA.
+ */
+
+/**
+ * TrackerSparqlStatement:
+ *
+ * The <structname>TrackerSparqlStatement</structname> object represents
+ * a SPARQL query. This query may contain parameterized variables
+ * (expressed as ~var in the syntax), which may be mapped to arbitrary
+ * values prior to execution. This statement may be reused for future
+ * queries with different values.
+ *
+ * The argument bindings may be changed through tracker_sparql_statement_bind_int(),
+ * tracker_sparql_statement_bind_boolean(), tracker_sparql_statement_bind_double()
+ * and tracker_sparql_statement_bind_string(). Those functions receive
+ * a @name argument corresponding for the variable name in the SPARQL query
+ * (eg. "var" for ~var) and a @value to map the variable to.
+ *
+ * Once all arguments have a value, the query may be executed through
+ * tracker_direct_statement_execute() or tracker_direct_statement_execute_async().
+ *
+ * This object was added in Tracker 2.2.
+ */
+public abstract class Tracker.Sparql.Statement : Object {
+       public string sparql { get; construct set; }
+       public Connection connection { get; construct set; }
+
+       /**
+        * tracker_sparql_statement_bind_int:
+        * @self: a #TrackerSparqlStatement
+        * @name: variable name
+        * @value: value
+        *
+        * Binds the integer @value to variable @name.
+        */
+       public abstract void bind_int (string name, int64 value);
+
+       /**
+        * tracker_sparql_statement_bind_boolean:
+        * @self: a #TrackerSparqlStatement
+        * @name: variable name
+        * @value: value
+        *
+        * Binds the boolean @value to variable @name.
+        */
+       public abstract void bind_boolean (string name, bool value);
+
+       /**
+        * tracker_sparql_statement_bind_string:
+        * @self: a #TrackerSparqlStatement
+        * @name: variable name
+        * @value: value
+        *
+        * Binds the string @value to variable @name.
+        */
+       public abstract void bind_string (string name, string value);
+
+       /**
+        * tracker_sparql_statement_bind_double:
+        * @self: a #TrackerSparqlStatement
+        * @name: variable name
+        * @value: value
+        *
+        * Binds the double @value to variable @name.
+        */
+       public abstract void bind_double (string name, double value);
+
+       /**
+        * tracker_sparql_statement_execute:
+        * @cancellable: a #GCancellable used to cancel the operation
+        * @error: #GError for error reporting.
+        *
+        * Executes the SPARQL query with the currently bound values.
+        *
+        * Returns: (transfer full): A #TrackerSparqlCursor
+        */
+       public abstract Cursor execute (Cancellable? cancellable) throws Sparql.Error, GLib.Error, 
GLib.IOError, DBusError;
+
+       /**
+        * tracker_sparql_statement_execute_finish:
+        * @self: a #TrackerSparqlStatement
+        * @_res_: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor
+        * @error: The error which occurred or %NULL
+        *
+        * Finishes the asynchronous operation started through
+        * tracker_sparql_statement_execute_async().
+        *
+        * Returns: (transfer full): A #TrackerSparqlCursor
+        */
+
+       /**
+        * tracker_sparql_statement_execute_async:
+        * @self: a #TrackerSparqlStatement
+        * @cancellable: a #GCancellable used to cancel the operation
+        * @_callback_: user-defined #GAsyncReadyCallback to be called when
+        *              asynchronous operation is finished.
+        * @_user_data_: user-defined data to be passed to @_callback_
+        *
+        * Asynchronously executes the SPARQL query with the currently bound values.
+        * It is a programming error to change the #TrackerSparqlStatement bindings
+        * between this function and tracker_sparql_statement_execute_finish(),
+        * the results are undefined if that happens.
+        */
+       public async abstract Cursor execute_async (Cancellable? cancellable) throws Sparql.Error, 
GLib.Error, GLib.IOError, DBusError;
+}