lsup_repo/include/desc.h

/** @file desc.h
 *
 * @brief Description (RDF) resource.
 *
 * The Description Resource (DESC-R), 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_DESC_H
#define _LSR_DESC_H

#include "core.h"


/*
 * Typedefs.
 */

typedef char LSR_id[UUIDSTR_SIZE];

typedef enum res_flags_t {
    LSR_RS_MANAGED          = 1 << 0,       // Managed by the repo.
} LSR_ResFlags;

/** @brief DESC-R structure.
 *
 * A Descriptive Resource (DESC-R) is made up of several RDF named graphs.
 * Each graph has a function defined by the framework and can 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_attr` and `admin_attr` graphs contain triples whose objects are
 * not managed resources—i.e. URIs on the WWW, blank nodes or literal terms.
 * These triples are generally referred to as "attributes" in this
 * documentation.
 *
 * The `user_rel` and `admin_rel` graphs contain exclusively triples whose
 * objects are URIs managed by the current 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). These triples are
 * generally referred to as "relationships" in this documentation.
 *
 * Relationships between these graphs are expressed by triples stored in the
 * default graph.
 */
typedef struct desc_t {
    LSUP_Graph *            user_attr;      // User-defined attributes.
    LSUP_Graph *            admin_attr;     // Managed attributes.
    LSUP_Graph *            user_rel;       // User-defined relationships.
    LSUP_Graph *            admin_rel;      // Managed relationships.
    uuid_t                  id;             // Resource identifier (UUID4).
    LSR_ResFlags            flags;          // Flags.
} LSR_Desc;


/*
 * API functions.
 */

/** @brief Create an in-memory DESC-R from graph data.
 *
 * 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 Graph with triples to populate the new resource. The graph
 *  URI is not used. All URIs in the graph may be relative to the resource.
 *  Hence, to reference the resource itself, an IRIRef with an empty string as
 *  data is used.
 *
 * @param[out] rsrc Resource handle. It must be freed with #LSR_desc_free().
 */
LSUP_rc
LSR_desc_new (LSUP_Graph *data, LSR_Desc **rsrc);


/** @brief Create an in-memory DESC-R 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_desc_store().
 *
 * @param[in] id ID of the resource to be retrieved, without the namespace.
 *
 * @param[out] rsrc Resource handle. It must be freed with #LSR_desc_free().
 */
LSUP_rc
LSR_desc_get (LSR_id id, LSR_Desc **rsrc);


/** @brief Free a DESC-R.
 */
void
LSR_desc_free (LSR_Desc *rsrc);


/** @brief Store a DESC-R, overwriting any data if it already exists.
 *
 * 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_desc_store (LSR_Desc *rsrc);


/** Perform a delta update on a stored resource.
 *
 * This function operates directly on a stored resource without the need to
 * provide an in-memory DESC-R. It first deletes triples by given patterns,
 * then adds triples. Both steps are optional.
 *
 * @param[in] id ID of the resource to be modified, without the namespace.
 *
 * @param[in] remove Array of 3-member array of terms. Each set of
 *  terms represents the s, p, o bound terms. Any and all can be NULL, as in
 *  #LSUP_graph_remove(). The array is terminated by a `{NULL}` array.
 *
 * @param[in] add Array of triples to be added, terminated by a NULL.
 */
LSUP_rc
LSUP_desc_update (LSR_id id, LSUP_Term **remove, LSUP_Triple *add);

#endif /* _LSR_DESC_H */