lsup_rdf/include/graph.h

#ifndef _LSUP_GRAPH_H
#define _LSUP_GRAPH_H

#include "store.h"
#include "environment.h"
#include "term.h"


/** @brief Graph object.
 */
typedef struct graph_t LSUP_Graph;

/** @brief Graph iterator.
 *
 * This opaque handle is generated by #LSUP_graph_lookup and is used to iterate
 * over lookup results with #LSUP_graph_iter_next. It must be freed with
 * #LSUP_graph_iter_free when done.
 */
typedef struct graph_iter_t LSUP_GraphIterator;


/** @brief Create an empty graph.
 *
 * @param[in] uri URI of the new graph. If NULL, a UUID4 URN is generated.
 *
 * @param store_type[in] Type of store backing the graph. One of the values of
 *  #LSUP_StoreType.
 *
 * @param[in] store_id Identifier for the back end store. This may be
 *  interpreted differently by each store implementation. For the MDB store,
 *  this is the file path where the store is located. It is ignored by volatile
 *  stores (with LSUP_STORE_PERM feature flag set to false). If a store
 *  does not exist for the given identifier, a new one is initialized. If this
 *  parameter is NULL, the default store for the selected type is used.
 *
 * @param[in] nsm Namespace map to use for an in-memory graph. This is ignored
 *  by graphs backed by permanent stores, which handle their own namespace map.
 *  If this is NULL, the graph is assigned a global namespace map that lives
 *  until #LSUP_done() is called.
 *
 * @return New graph, or NULL on error. Must be freed with #LSUP_graph_free().
 */
LSUP_Graph *
LSUP_graph_new (
        LSUP_Term *uri, const LSUP_StoreType store_type, const char *store_id,
        LSUP_NSMap *nsm, size_t size);


/** @brief Copy triples from a source graph into a destination one.
 *
 * The destination graph is not initialized here, so the copy is cumulative.
 *
 * @param src[in] Source graph.
 *
 * @param dest[in] Destination graph.
 *
 * @param[in] txn Transaction handle.
 */
LSUP_rc
LSUP_graph_copy_contents (const LSUP_Graph *src, LSUP_Graph *dest, void *txn);


/** Perform a boolean operation between two graphs.
 *
 * This method populates an initialized graph with the result of the operation
 * between two other graphs. The resulting graph may be of any store type and
 * may be the result of graphs of different store types.
 *
 * @param op[in] Operation to perform. One of #LSUP_bool_op.
 *
 * @param gr1[in] First operand.
 *
 * @param gr2[in] Second operand.
 *
 * @param[in] txn Transaction handle.
 *
 * @param res[out] Result graph. The handle should be initialized via
 *  #LSUP_graph_new() or equivalent. Any preexisting contents are not removed.
 *  If an unrecoverable error occurs, this graph is freed.
 *
 * @return LSUP_OK on success; <0 on error.
 */
LSUP_rc
LSUP_graph_bool_op(
        const LSUP_bool_op op, const LSUP_Graph *gr1, const LSUP_Graph *gr2,
        void *txn, LSUP_Graph *res);


/** @brief Free a graph.
 */
void
LSUP_graph_free (LSUP_Graph *gr);


/** @brief Compare two graphs.
 *
 * @param[in] gr1 First operand.
 *
 * @param[in] gr2 Second operand.
 *
 * @param[in] txn Transaction handle.
 *
 * @return True if the graphs are topologically equal, false otherwise.
 */
bool
LSUP_graph_equals (const LSUP_Graph *gr1, const LSUP_Graph *gr2, void *txn);


/** @brief Read-only graph URI.
 *
 * To change the graph URI, use #LSUP_graph_set_uri.
 */
LSUP_Term *
LSUP_graph_uri (const LSUP_Graph *gr);


/** Set the URI of a graph.
 *
 * Note that by changing the URI of a graph backed by a context-sensitive store
 * (i.e. LSUP_STORE_MDB*) effectively changes the underlying data set that the
 * graph points to. Triples are looked up in, and added to, the context that
 * the graph URI represents. A non-context graph retains the same triple set
 * when graph URI changes.
 *
 * @param gr[in] Graph handle.
 *
 * @param uri[in] IRI handle. The graph takes ownership of the handle.
 *
 * @return LSUP_OK on success; <0 on error.
 */
LSUP_rc
LSUP_graph_set_uri (LSUP_Graph *gr, LSUP_Term *uri);


/** @brief Get the namespace map for an in-memory graph.
 *
 * @return Namespace handler for in-memory graphs, NULL for MDB graphs.
 */
LSUP_NSMap *
LSUP_graph_namespace (const LSUP_Graph *gr);


/** @brief Set the namespace map for an in-memory graph.
 *
 * This has no effect on graph stores with LSUP_STORE_PERM.
 *
 * @param[in] gr Graph to set the namespace map for.
 *
 * @param[in] nsm Namespace handle.
 */
void
LSUP_graph_set_namespace (LSUP_Graph *gr, LSUP_NSMap *nsm);


/** @brief Number of triples in a graph.
 */
size_t
LSUP_graph_size (const LSUP_Graph *gr);


/** @brief Whether a graph contains a triple.
 *
 * @param[in] gr Graph to look up into.
 *
 * @param[in] spo Triple to look up.
 *
 * @return 1 if the triple is found, 0 if not found.
 */
bool
LSUP_graph_contains (const LSUP_Graph *gr, const LSUP_Triple *spo, void *txn);


/** @brief Begin a transaction.
 *
 * If the underlying store supports it, begin a transaction and return
 * an opaque handle.
 *
 * The transaction must be either committed with #LSUP_graph_commit() or
 * rolled back with #LSUP_graph_abort().
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] flags Unused for now, use 0. TODO
 *
 * @param[out] txn Transaction handle. This may be passed to all subsequent
 * operations that one wants to perform within that transaction.
 *
 * @return LSUP_OK on success; LSUP_VALUE_ERR if the graph store does not
 *  support transactions; <0 on other errors from the underlying store.
 */
LSUP_rc
LSUP_graph_begin (const LSUP_Graph *gr, int flags, void **txn);


/** @brief Commit a transaction.
 *
 * If the underlying store supports it, commit an open transaction. In case of
 * error, the transaction is left open and it is advisable to roll it back with
 * #LSUP_graph_abort().
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] txn Transaction handle.
 *
 * @return LSUP_OK if the transaction was committed successfully; LSUP_NOACTION
 *  if NULL was passed; LSUP_TXN_ERR on error.
 */
LSUP_rc LSUP_graph_commit (const LSUP_Graph *gr, void *txn);


/** @brief Abort (roll back) a transaction.
 *
 * If the underlying store supports it, abort an open transaction and abandon
 * all changes.
 *
 * @param[in] gr Graph handle.
 *
 * @param[in] txn Transaction handle.
 */
void LSUP_graph_abort (const LSUP_Graph *gr, void *txn);


/** @brief Initialize an iterator to add triples.
 *
 * @param[in] gr Graph to add to. It is added to the iterator state.
 *
 * @param[in] txn Transaction handle.
 *
 * @return Iterator handle. This should be passed to #LSUP_graph_add_iter() and
 * must be freed with #LSUP_graph_add_done().
 */
LSUP_GraphIterator *
LSUP_graph_add_init (LSUP_Graph *gr, void *txn);



/** @brief Add a single triple to the store.
 *
 * @param[in] it Iterator obtained with #LSUP_graph_add_init().
 *
 * @param[in] spo Triple to add. Caller retains ownership.
 */
LSUP_rc
LSUP_graph_add_iter (LSUP_GraphIterator *it, const LSUP_Triple *spo);


/** @brief Finalize an add iteration loop and free the iterator.
 *
 * DO NOT USE with iterators obtained with other than #LSUP_graph_add_init().
 *
 * @param[in] it Iterator to finalize.
 */
void
LSUP_graph_add_done (LSUP_GraphIterator *it);


/** @brief Add triples to a graph.
 *
 * @param[in] gr Graph to add triples to.
 *
 * @param[in] trp Array of triples to add. The last triple must be NULL.
 *
 * @param[in] strp Array of buffer triples to add. The last one must be NULL.
 *
 * @param[in] txn Transaction handle.
 *
 * @param[out] ct This will be filled with the total number of triples
 *  inserted.
 */
LSUP_rc
LSUP_graph_add (
        LSUP_Graph *gr, const LSUP_Triple trp[], void *txn, size_t *ct);


/** @brief Delete triples by a matching pattern.
 *
 * @param gr[in] Graph to delete triples from.
 *
 * @param ptn[in] Matching pattern. Any and all of s, p, o can be NULL.
 *
 * @param[in] txn Transaction handle.
 *
 * @param ct[out] If not NULL it is populated with the number of triples
 *  deleted.
 */
LSUP_rc
LSUP_graph_remove (
        LSUP_Graph *gr, const LSUP_Term *s, const LSUP_Term *p,
        const LSUP_Term *o, void *txn, size_t *ct);


/** Look up triples by a matching pattern and yield an iterator.
 *
 * @param gr[in] Graph to look up.
 *
 * @param spo[in] Triple to look for. Any and all terms can be NULL, which
 *  indicate unbound terms.
 *
 * @param[in] txn Transaction handle.
 *
 * @param it[out] Pointer to a #LSUP_GraphIterator to be generated. It must be
 *  freed with #LSUP_graph_iter_free after use.
 */
LSUP_GraphIterator *
LSUP_graph_lookup (const LSUP_Graph *gr, const LSUP_Term *s,
        const LSUP_Term *p, const LSUP_Term *o, void *txn, size_t *ct);


/** @brief Advance a cursor obtained by a lookup and return a matching triple.
 *
 * @param it[in] Iterator handle obtained through #LSUP_graph_lookup.
 *
 * @param spo[out] Triple to be populated with the next result. May be NULL
 *  (e.g. for counters).
 *
 * @return LSUP_OK if a result was found; LSUP_END if the end of the match list
 *  was reached.
 */
LSUP_rc
LSUP_graph_iter_next (LSUP_GraphIterator *it, LSUP_Triple *spo);


/** @brief Free a graph iterator.
 *
 * DO NOT USE with iterators obtained with #LSUP_graph_add_init(). Use
 * #LSUP_graph_add_done() with those.
 *
 * @param[in] it Iterator to finalize.
 */
void
LSUP_graph_iter_free (LSUP_GraphIterator *it);

#endif