Merge branch 'wip/carlosg/deprecations' into 'master'

API deprecations for 3.5.x

See merge request https://gitlab.gnome.org/GNOME/tracker/-/merge_requests/558

8 files changed, 47 insertions, 5 deletions

diff --git a/src/libtracker-sparql/bus/tracker-bus.c b/src/libtracker-sparql/bus/tracker-bus.c
index 3c64460c4..46b6c35ba 100644
--- a/src/libtracker-sparql/bus/tracker-bus.c
+++ b/src/libtracker-sparql/bus/tracker-bus.c
@@ -950,9 +950,12 @@ update_blank_sync_cb (GObject      *source,
 {
 	AsyncData *data = user_data;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	data->retval =
 		tracker_sparql_connection_update_blank_finish (TRACKER_SPARQL_CONNECTION (source),
 							       res, &data->error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
+
 	g_main_loop_quit (data->loop);
 }
 
@@ -969,11 +972,13 @@ tracker_bus_connection_update_blank (TrackerSparqlConnection  *self,
 	data.loop = g_main_loop_new (context, FALSE);
 	g_main_context_push_thread_default (context);
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	tracker_sparql_connection_update_blank_async (self,
 						      sparql,
 						      cancellable,
 						      update_blank_sync_cb,
 						      &data);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 	g_main_loop_run (data.loop);
 
 	g_main_context_pop_thread_default (context);
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index dc67e1ec0..869df9743 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -381,6 +381,16 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection  *connect
  *
  * Returns: a #GVariant with the generated URNs, which should be freed with
  * g_variant_unref() when no longer used.
+ *
+ * Deprecated: 3.5: This function makes the expectation that blank nodes have
+ * a durable name that persist. The SPARQL and RDF specs define a much more
+ * reduced scope for blank node labels. This function advises a behavior that
+ * goes against that reduced scope, and will directly make the returned values
+ * meaningless if the %TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag
+ * is defined in the connection.
+ *
+ * Users that want names generated for them, should look for other methods
+ * (e.g. IRIs containing UUIDv4 strings).
  */
 GVariant *
 tracker_sparql_connection_update_blank (TrackerSparqlConnection  *connection,
@@ -411,6 +421,8 @@ tracker_sparql_connection_update_blank (TrackerSparqlConnection  *connection,
  * Executes asynchronously a SPARQL update with blank nodes. See
  * the tracker_sparql_connection_update_blank() documentation to
  * see the differences with tracker_sparql_connection_update().
+ *
+ * Deprecated: 3.5: See tracker_sparql_connection_update_blank().
  */
 void
 tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection,
@@ -443,6 +455,8 @@ tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connectio
  *
  * Returns: a #GVariant with the generated URNs, which should be freed with
  * g_variant_unref() when no longer used.
+ *
+ * Deprecated: 3.5: See tracker_sparql_connection_update_blank().
  */
 GVariant *
 tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection  *connection,
diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h
index b55438726..d0923c9cd 100644
--- a/src/libtracker-sparql/tracker-connection.h
+++ b/src/libtracker-sparql/tracker-connection.h
@@ -189,18 +189,18 @@ gboolean tracker_sparql_connection_update_resource_finish (TrackerSparqlConnecti
 TRACKER_AVAILABLE_IN_3_1
 TrackerBatch * tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection);
 
-TRACKER_AVAILABLE_IN_ALL
+TRACKER_DEPRECATED_IN_3_5
 GVariant * tracker_sparql_connection_update_blank (TrackerSparqlConnection  *connection,
                                                    const gchar              *sparql,
                                                    GCancellable             *cancellable,
                                                    GError                  **error);
-TRACKER_AVAILABLE_IN_ALL
+TRACKER_DEPRECATED_IN_3_5
 void tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection,
                                                    const gchar             *sparql,
                                                    GCancellable            *cancellable,
                                                    GAsyncReadyCallback      callback,
                                                    gpointer                 user_data);
-TRACKER_AVAILABLE_IN_ALL
+TRACKER_DEPRECATED_IN_3_5
 GVariant * tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection  *connection,
                                                           GAsyncResult             *res,
                                                           GError                  **error);
diff --git a/src/libtracker-sparql/tracker-cursor.c b/src/libtracker-sparql/tracker-cursor.c
index ae871b790..d7eb83685 100644
--- a/src/libtracker-sparql/tracker-cursor.c
+++ b/src/libtracker-sparql/tracker-cursor.c
@@ -532,6 +532,11 @@ tracker_sparql_cursor_next_finish (TrackerSparqlCursor  *cursor,
  * @cursor: a #TrackerSparqlCursor
  *
  * Resets the iterator to point back to the first result.
+ *
+ * Deprecated: 3.5: This function only works on cursors
+ * from direct #TrackerSparqlConnection objects and cannot work
+ * reliably across all cursor types. Issue a different query to
+ * obtain a new cursor.
  */
 void
 tracker_sparql_cursor_rewind (TrackerSparqlCursor *cursor)
diff --git a/src/libtracker-sparql/tracker-cursor.h b/src/libtracker-sparql/tracker-cursor.h
index 92e8f5d3c..2316202e4 100644
--- a/src/libtracker-sparql/tracker-cursor.h
+++ b/src/libtracker-sparql/tracker-cursor.h
@@ -116,7 +116,7 @@ gboolean tracker_sparql_cursor_next_finish (TrackerSparqlCursor  *cursor,
                                             GAsyncResult         *res,
                                             GError              **error);
 
-TRACKER_AVAILABLE_IN_ALL
+TRACKER_DEPRECATED_IN_3_5
 void tracker_sparql_cursor_rewind (TrackerSparqlCursor *cursor);
 
 G_END_DECLS
diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c
index aff0c3526..fab046622 100644
--- a/src/libtracker-sparql/tracker-endpoint-dbus.c
+++ b/src/libtracker-sparql/tracker-endpoint-dbus.c
@@ -849,8 +849,11 @@ update_blank_cb (GObject      *object,
 	GError *error = NULL;
 	GVariant *results;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank_finish (TRACKER_SPARQL_CONNECTION (object),
 	                                                         res, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
+
 	if (results) {
 		GVariantBuilder builder;
 
@@ -881,11 +884,13 @@ read_update_blank_cb (GObject      *object,
 	}
 
 	conn = tracker_endpoint_get_sparql_connection (TRACKER_ENDPOINT (request->endpoint));
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	tracker_sparql_connection_update_blank_async (conn,
 	                                              request->query,
 	                                              request->endpoint->cancellable,
 	                                              update_blank_cb,
 	                                              request);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 }
 
 static void
diff --git a/tests/core/tracker-sparql-blank-test.c b/tests/core/tracker-sparql-blank-test.c
index 1a0aae181..43696a4b5 100644
--- a/tests/core/tracker-sparql-blank-test.c
+++ b/tests/core/tracker-sparql-blank-test.c
@@ -59,11 +59,12 @@ test_blank (TestInfo      *info,
 	g_assert_no_error (error);
 
 	/* perform update in transaction */
-
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	updates = tracker_sparql_connection_update_blank (conn,
 	                                                  "INSERT { _:foo a rdfs:Resource } "
 	                                                  "INSERT { _:foo a rdfs:Resource . _:bar a rdfs:Resource } ",
 	                                                  NULL, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 	g_assert_no_error (error);
 	g_assert_true (updates != NULL);
 
diff --git a/tests/libtracker-sparql/tracker-fd-test.c b/tests/libtracker-sparql/tracker-fd-test.c
index 84400e779..7dd9a8290 100644
--- a/tests/libtracker-sparql/tracker-fd-test.c
+++ b/tests/libtracker-sparql/tracker-fd-test.c
@@ -230,7 +230,9 @@ test_tracker_sparql_update_blank_fast_small (gpointer      *fixture,
 	const gchar *query = "INSERT { _:x a nfo:Image }";
 	GVariant *results;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank (connection, query, NULL, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	g_assert_no_error (error);
 	g_assert_true (results);
@@ -253,7 +255,9 @@ test_tracker_sparql_update_blank_fast_large (gpointer      *fixture,
 
 	query = g_strdup_printf ("INSERT { _:x a nfo:Image; nao:identifier \"%s\" }", lots);
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank (connection, query, NULL, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	g_free (lots);
 	g_free (query);
@@ -272,7 +276,9 @@ test_tracker_sparql_update_blank_fast_error (gpointer      *fixture,
 	const gchar *query = "blork blork blork";
 	GVariant *results;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank (connection, query, NULL, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	g_assert_true (error != NULL && error->domain == TRACKER_SPARQL_ERROR);
 	g_assert_true (!results);
@@ -288,7 +294,9 @@ test_tracker_sparql_update_blank_fast_no_blanks (gpointer      *fixture,
 	const gchar *query = "INSERT { <urn:not_blank> a nfo:Image }";
 	GVariant *results;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank (connection, query, NULL, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	/* FIXME: Properly test once we get update_blank implemented */
 
@@ -398,7 +406,9 @@ async_update_blank_callback (GObject      *source_object,
 
 	g_main_loop_quit (data->main_loop);
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	results = tracker_sparql_connection_update_blank_finish (connection, result, &error);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	g_assert_no_error (error);
 	g_assert_true (results != NULL);
@@ -417,11 +427,13 @@ test_tracker_sparql_update_blank_async (gpointer      *fixture,
 	data = g_slice_new (AsyncData);
 	data->main_loop = main_loop;
 
+	G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 	tracker_sparql_connection_update_blank_async (connection,
 	                                              query,
 	                                              NULL,
 	                                              async_update_blank_callback,
 	                                              data);
+	G_GNUC_END_IGNORE_DEPRECATIONS
 
 	g_main_loop_run (main_loop);