lsup_repo/include/dres.h

/** @file dres.h
 *
 * @brief Descriptive (RDF) resource.
 *
 * The Descriptive Resource (D-RES), together with the Data Resource (DATA-R),
 * is the building block of lsup_repo information. Its contents are fully
 * understood by the library.
 */

#ifndef _LSR_DRES_H
#define _LSR_DESC_H

#include "repo_core.h"


/*
 * Typedefs.
 */

/** @brief D-RES structure.
 *
 * A Descriptive Resource (D-RES) is made up of several RDF named graphs.
 * Each graph has a function defined by the framework and may be managed by
 * the framework or by the user.
 *
 * the URI of each graph is derived from the ID of the resource. This is just
 * for readability. Actually, when stored, the resource generates triples that
 * explicitly link these graphs together. These URIs have an URN prefix so that
 * they are portable and, in a Linked Data server, can be easily replaced with
 * absolute URLs based on the server root.
 *
 * The `user_data` handle is a `{NULL}`-terminated array of user-defined
 * graph handles.  Each graph URI is considered relative to the resource URN
 * and may or may not be consistent across resources, depending on how
 * repository managers organize their knowledge.
 *
 * The `admin_data` graph contains exclusively triples managed by the
 * repository.  They may have special functionality attached and may be created
 * as a direct consequence of a user action (e.g. adding a member to a Set or
 * List).
 *
 * Relationships between these graphs are expressed by triples stored in the
 * `main_data` graph.
 */
typedef struct dres_t {
    LSUP_Graph **           user_data;      ///< User-defined data graphs.
    LSUP_Graph *            admin_data;     ///< Managed data (one graph).
    LSUP_Graph *            main_data;      ///< Relationships between graphs.
    uuid_t                  id;             ///< Resource identifier (RFC4122).
    LSR_ResFlags            flags;          ///< Flags.
} LSR_Dres;


/*
 * API functions.
 */

/** @brief Create an in-memory D-RES from multiple graphs.
 *
 * The resource is volatile until it is stored in a persistent back end. It
 * must be stored in a context-capable back end (e.g. `LSUP_STORE_MDB`).
 *
 * The resource is assigned a UUID4. The resource URI, used in
 * relationships, is the ID prefixed with the `LSR_NS_DESC` namespace.
 *
 * @param[in] data NULL-terminated array of graph handles, each with a set of
 *  triples to populate the new resource. Triples and terms are copied and get
 *  freed when #LSR_dres_free() is called. All URIs, including the graph URI,
 *  if not absolute, are intended as relative to the resource URI.  Hence, to
 *  reference the resource itself, an IRIRef with an empty string as data may
 *  be used. The graph URI is maintained within the resource. As a convention,
 *  it is recommended to use a fragment URI with a short label, e.g.
 *  `#changeset37205`, `#~alice`, or `#admin-md`. Fragments beginning with two
 *  underscores are reserved for internal use and are not allowed in the input.
 *
 * @param[out] rsrc Resource handle pointer. The handle should be freed with
 *  #LSR_dres_free(). On a non-success return code, the handle may be garbage.
 *
 * @return LSUP_OK on success; < 0 on error.
 */
LSUP_rc
LSR_dres_new_multi (LSUP_Graph *const *data, LSR_Dres **rsrc);


/** @brief Shortcut to create a resource from a single graph.
 *
 * The graph is automatically assigned the `_main` label. See
 * #LSR_dres_new_multi for other documentation.
 *
 * @param[in] data Single graph to insert.
 *
 * @param[out] rsrc Resource handle pointer. The handle should be freed with
 *  #LSR_dres_free(). On a non-success return code, the handle may be garbage.
 *
 * @return LSUP_OK on success; < 0 on error.
 */
LSUP_rc
LSR_dres_new (const LSUP_Graph *data, LSR_Dres **rsrc);



/** @brief Create an in-memory D-RES from a stored resource.
 *
 * Once created, the resource may be modified independently from its stored
 * counterpart. In order to make changes permanent, it must be stored again
 * using #LSR_dres_store().
 *
 * @param[in] id ID of the resource to be retrieved, without the namespace.
 *
 * @param[out] rsrc Resource handle to be populated with the found resource. It
 *  should be freed with #LSR_dres_free(). If NULL, the resource is only
 *  checked for existence (much faster). On a non-success return code, the
 *  handle may be garbage.
 *
 * @return LSUP_OK if the resource is found; LSUP_NORESULT if not found; <0
 *  on error.
 */
LSUP_rc
LSR_dres_get (const uuid_t id, LSR_Dres **rsrc);



/** @brief Update an existing resource.
 *
 * This operation works by first removing triples by graph and term matching,
 * if provided, then adding triples grouped by graphs. Both steps are optional.
 *
 * Updates to triples containing #LSR_managed_preds and #LSR_managed_types are
 * ignored.
 *
 * @param[in] rsrc Resource handle.
 *
 * @param[in] rm_data `{NULL}`-terminated array of term arrays. Each term array
 * contains, in the following order: s, p, o, graph URI (c). Any and all terms
 * in each array may be NULL, acting as wildcards. This function calls
 * #LSUP_graph_remove_txn() on each matching graph, or on all graphs if the
 * first term in an array is NULL.
 *
 * @important Passing `NULL` (note: not `{NULL}`) as an argument to `rm_data`
 * indicates that the resource is new. Some internal functions use this
 * feature. This should not be done by an API consumer because it may leave the
 * resource an inconsistent state.
 *
 * @param[in] add_data NULL-terminated array of graph handles to add. If the
 * resource has already a matching graph for a graph being added, the triples
 * are added to the existing graph.
 *
 * @return LSUP_OK on successful update; TODO
 */
LSUP_rc LSR_dres_update ( LSR_Dres *rsrc, LSUP_Term *const rm_data[][4],
        LSUP_Graph *const *add_data);


/** @brief Free a D-RES.
 */
void
LSR_dres_free (LSR_Dres *rsrc);


/** @brief Get resource metadata.
 *
 * Return all repository-managed triples about the resource.
 *
 * @param[in] rsrc Resource to be inspected.
 *
 * @return In-memory graph with metadata triples.
 */
LSUP_Graph *
LSR_dres_metadata (const LSR_Dres *rsrc);


/** @brief Get user-defined data.
 *
 * Return all user-defined triples in the resource in a single graph.
 *
 * The resulting graph IRI is the resource IRI with a random fragment string
 * appended.
 *
 * @param[in] rsrc Resource to be inspected.
 *
 * @return NULL-terminated array of in-memory graphs with data triples.
 */
LSUP_Graph **
LSR_dres_user_data (const LSR_Dres *rsrc);


/** @brief All resource triples in a single graph.
 *
 * Return the union of all the user data and the admin metadata in one flat
 * graph.
 *
 * @param[in] rsrc Resource handle.
 *
 * @return New graph with all the resource triples. The graph URI is the
 * resource URN.
 */
LSUP_Graph *
LSR_dres_triples (const LSR_Dres *rsrc);


/** @brief Push an in-memory D-RES into the persistent store.
 *
 * This is a "create or overwrite" function that deletes any existing resource
 * under the given ID before storing the content of the in-memory resource
 * at hand.
 *
 * All data are copied and the resource may be freed after this operation.
 *
 * @param[in] rsrc Resource to be created or overwritten.
 */
LSUP_rc
LSR_dres_store (const LSR_Dres *rsrc);


/** @brief Delete a D-RES.
 *
 * TODO
 *
 * @param[in] id Resource ID.
 *
 * @return LSUP_OK if the resource was found and deleted; LSUP_NOACTION if no
 *  resource was found for the given ID.
 */
LSUP_rc
LSR_dres_delete (LSR_id id);


/** @brief Get resource URN.
 *
 * @param[in] rsrc Resource pointer.
 *
 * @return New URI term. It must be freed with #LSUP_term_free() eventually.
 */
inline LSUP_Term *
LSR_dres_urn (const LSR_Dres *rsrc)
{ return LSR_id_to_urn (rsrc->id, NULL); }


#endif /* _LSR_DESC_H */