libtracker-sparql: Deprecate tracker_sparql_connection_update_blank*()

Per the spec (https://www.w3.org/TR/sparql11-query/#BGPsparqlBNodes):

    Since SPARQL treats blank node identifiers in a results format document
    as scoped to the document, they cannot be understood as identifying
    nodes in the active graph of the dataset.

This is precisely what tracker_sparql_connection_update_blank() (and async
variant) are doing. While that works given the interpretation of blank
nodes in a TrackerSparqlConnection with default flags, this is precisely
what TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES implements, and at
best it is not great to advise this inconsistency as public API.

It is best to deprecate this set of functions, any user should devise
their own IRI generation scheme, instead of relying on blank nodes being
sort of one.

2 files changed, 17 insertions, 3 deletions

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);