From 3822a5502099874c1b52243da7d324fe71595d45 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Mon, 15 Oct 2018 23:08:18 +0200 Subject: 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 | 122 +++++++++++++++++++++ 4 files changed, 136 insertions(+) create mode 100644 src/libtracker-sparql/tracker-statement.vala 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 94ada9aaf..65985baad 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..cdb6c36eb 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..fa965cacf --- /dev/null +++ b/src/libtracker-sparql/tracker-statement.vala @@ -0,0 +1,122 @@ +/* + * 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. + */ + +/** + * SECTION: tracker-sparql-statement + * @short_description: Prepared statements + * @title: TrackerSparqlStatement + * @stability: Stable + * @include: tracker-sparql.h + * + * The TrackerSparqlStatement 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_sparql_statement_execute() or tracker_sparql_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. + */ + public async abstract Cursor execute_async (Cancellable? cancellable) throws Sparql.Error, GLib.Error, GLib.IOError, DBusError; +} -- cgit v1.2.1