1 /* -*- Mode: c; c-basic-offset: 2 -*- 2 * 3 * librdf_storage_module.h - Interface for a Redland storage module 4 * 5 * Copyright (C) 2000-2008, David Beckett http://www.dajobe.org/ 6 * Copyright (C) 2000-2005, University of Bristol, UK http://www.bristol.ac.uk/ 7 * 8 * This package is Free Software and part of Redland http://librdf.org/ 9 * 10 * It is licensed under the following three licenses as alternatives: 11 * 1. GNU Lesser General Public License (LGPL) V2.1 or any newer version 12 * 2. GNU General Public License (GPL) V2 or any newer version 13 * 3. Apache License, V2.0 or any newer version 14 * 15 * You may not use this file except in compliance with at least one of 16 * the above three licenses. 17 * 18 * See LICENSE.html or LICENSE.txt at the top of this package for the 19 * complete terms and further detail along with the license texts for 20 * the licenses in COPYING.LIB, COPYING and LICENSE-2.0.txt respectively. 21 */ 22 23 #ifndef LIBRDF_STORAGE_FACTORY_H 24 #define LIBRDF_STORAGE_FACTORY_H 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 31 /** 32 * librdf_storage_instance: 33 * 34 * Opaque storage module instance handle. 35 * 36 * For use with a storage module and the librdf_storage_get_instance() 37 * and librdf_storage_set_instance() functions. The instance handle 38 * should be set in the #librdf_storage_factory init factory method. 39 */ 40 typedef void* librdf_storage_instance; 41 42 43 /** 44 * LIBRDF_STORAGE_MIN_INTERFACE_VERSION: 45 * 46 * Oldest support librdf storage module interface version. 47 * 48 */ 49 #define LIBRDF_STORAGE_MIN_INTERFACE_VERSION 1 50 51 /** 52 * LIBRDF_STORAGE_MAX_INTERFACE_VERSION: 53 * 54 * Newest supported librdf storage module interface version. 55 * 56 */ 57 #define LIBRDF_STORAGE_MAX_INTERFACE_VERSION 1 58 59 /** 60 * LIBRDF_STORAGE_INTERFACE_VERSION: 61 * 62 * Default librdf storage module interface version. 63 * 64 */ 65 #define LIBRDF_STORAGE_INTERFACE_VERSION LIBRDF_STORAGE_MAX_INTERFACE_VERSION 66 67 /** 68 * librdf_storage_factory: 69 * @version: Interface version. Only version 1 is defined. 70 * @name: Name (ID) of this storage, e.g. "megastore" 71 * @label: Label of this storage, e.g. "Megastore Storage" 72 * @init: Create a new storage. 73 * This method should create the required instance data and store it with 74 * librdf_storage_set_instance() so it can be used in other methods. 75 * @clone: Copy a storage. 76 * This is assumed to leave the new storage in the same state as an existing 77 * storage after an init() method - i.e ready to use but closed. 78 * @terminate: Destroy a storage. 79 * This method is responsible for freeing all memory allocated in the init method. 80 * @open: Make storage be associated with model 81 * @close: Close storage/model context 82 * @size: Return the number of statements in the storage for model 83 * @add_statement: Add a statement to the storage from the given model. OPTIONAL 84 * @add_statements: Add a statement to the storage from the given model. OPTIONAL 85 * @remove_statement: Remove a statement from the storage. OPTIONAL 86 * @contains_statement: Check if statement is in storage 87 * @has_arc_in: Check for [node, property, ?] 88 * @has_arc_out: Check for [?, property, node] 89 * @serialise: Serialise the model in storage 90 * @find_statements: Return a stream of triples matching a triple pattern 91 * @find_statements_with_options: Return a stream of triples matching a triple pattern with some options. OPTIONAL 92 * @find_sources: Return a list of Nodes marching given arc, target 93 * @find_arcs: Return a list of Nodes marching given source, target 94 * @find_targets: Return a list of Nodes marching given source, target 95 * @get_arcs_in: Return list of properties to a node (i.e. with node as the object) 96 * @get_arcs_out: Return list of properties from a node (i.e. with node as the subject) 97 * @context_add_statement: Add a statement to the storage from the context. 98 * NOTE: If context is NULL, this MUST be equivalent to @add_statement. OPTIONAL. 99 * @context_remove_statement: Remove a statement from a context. 100 * NOTE: if context is NULL, this MUST be equivalent to remove_statement. OPTIONAL. 101 * @context_serialise: Serialise statements in a context. OPTIONAL 102 * @sync: Synchronise to underlying storage. OPTIONAL 103 * @context_add_statements: Add statements to a context. storage core will do this using context_add_statement if missing. 104 * NOTE: If context is NULL, this MUST be equivalent to add_statements. OPTIONAL 105 * @context_remove_statements: Remove statements from a context. storage core will do this using context_remove_statement if missing). OPTIONAL 106 * @find_statements_in_context: Search for statement in a context. storage core will do this using find_statements if missing. OPTIONAL 107 * @get_contexts: Return an iterator of context nodes. Returns NULL if contexts not supported. OPTIONAL 108 * @get_feature: Get a feature. OPTIONAL 109 * @set_feature: Set a feature. OPTIONAL 110 * @transaction_start: Begin a transaction. OPTIONAL 111 * @transaction_start_with_handle: Begin a transaction with opaque data handle. OPTIONAL 112 * @transaction_commit: Commit a transaction. OPTIONAL 113 * @transaction_rollback: Rollback a transaction. OPTIONAL 114 * @transaction_get_handle: Get opaque data handle passed to transaction_start_with_handle. OPTIONAL 115 * 116 * A Storage Factory 117 */ 118 struct librdf_storage_factory_s { 119 /* Interface version */ 120 int version; 121 122 /* Name (ID) of this storage */ 123 char* name; 124 125 /* Label of this storage */ 126 char* label; 127 128 /* The rest of this structure is populated by the storage-specific 129 * register function 130 */ 131 132 /* Create a new storage. */ 133 int (*init)(librdf_storage* storage, const char *name, librdf_hash* options); 134 135 /* Copy a storage. */ 136 int (*clone)(librdf_storage* new_storage, librdf_storage* old_storage); 137 138 /* Destroy a storage. */ 139 void (*terminate)(librdf_storage* storage); 140 141 /* Make storage be associated with model */ 142 int (*open)(librdf_storage* storage, librdf_model* model); 143 144 /* Close storage/model context */ 145 int (*close)(librdf_storage* storage); 146 147 /* Return the number of statements in the storage for model */ 148 int (*size)(librdf_storage* storage); 149 150 /* Add a statement to the storage from the given model */ 151 int (*add_statement)(librdf_storage* storage, librdf_statement* statement); 152 153 /* Add a statement to the storage from the given model */ 154 int (*add_statements)(librdf_storage* storage, librdf_stream* statement_stream); 155 156 /* Remove a statement from the storage */ 157 int (*remove_statement)(librdf_storage* storage, librdf_statement* statement); 158 159 /* Check if statement is in storage */ 160 int (*contains_statement)(librdf_storage* storage, librdf_statement* statement); 161 162 /* Check for [node, property, ?] */ 163 int (*has_arc_in)(librdf_storage *storage, librdf_node *node, librdf_node *property); 164 165 /* Check for [?, property, node] */ 166 int (*has_arc_out)(librdf_storage *storage, librdf_node *node, librdf_node *property); 167 168 /* Serialise the model in storage */ 169 librdf_stream* (*serialise)(librdf_storage* storage); 170 171 /* Return a stream of triples matching a triple pattern */ 172 librdf_stream* (*find_statements)(librdf_storage* storage, librdf_statement* statement); 173 174 /* Return a stream of triples matching a triple pattern with some options. */ 175 librdf_stream* (*find_statements_with_options)(librdf_storage* storage, librdf_statement* statement, librdf_node* context_node, librdf_hash* options); 176 177 /* Return a list of Nodes marching given arc, target */ 178 librdf_iterator* (*find_sources)(librdf_storage* storage, librdf_node *arc, librdf_node *target); 179 180 /* Return a list of Nodes marching given source, target */ 181 librdf_iterator* (*find_arcs)(librdf_storage* storage, librdf_node *src, librdf_node *target); 182 183 /* Return a list of Nodes marching given source, target */ 184 librdf_iterator* (*find_targets)(librdf_storage* storage, librdf_node *src, librdf_node *target); 185 186 /** Return list of properties to a node (i.e. with node as the object) */ 187 librdf_iterator* (*get_arcs_in)(librdf_storage *storage, librdf_node *node); 188 189 /* Return list of properties from a node (i.e. with node as the subject) */ 190 librdf_iterator* (*get_arcs_out)(librdf_storage *storage, librdf_node *node); 191 192 /* Add a statement to the storage from the context */ 193 int (*context_add_statement)(librdf_storage* storage, librdf_node* context, librdf_statement *statement); 194 195 /* Remove a statement from a context */ 196 int (*context_remove_statement)(librdf_storage* storage, librdf_node* context, librdf_statement *statement); 197 198 /* Serialise statements in a context */ 199 librdf_stream* (*context_serialise)(librdf_storage* storage, librdf_node* context); 200 201 /* Synchronise to underlying storage */ 202 int (*sync)(librdf_storage* storage); 203 204 /* Add statements to a context */ 205 int (*context_add_statements)(librdf_storage* storage, librdf_node* context, librdf_stream *stream); 206 207 /* Remove statements from a context */ 208 int (*context_remove_statements)(librdf_storage* storage, librdf_node* context); 209 210 /* Search for statement in a context */ 211 librdf_stream* (*find_statements_in_context)(librdf_storage* storage, 212 librdf_statement* statement, librdf_node* context_node); 213 214 /* Return an iterator of context nodes */ 215 librdf_iterator* (*get_contexts)(librdf_storage* storage); 216 217 /* Get a feature */ 218 librdf_node* (*get_feature)(librdf_storage* storaage, librdf_uri* feature); 219 220 /* Set a feature */ 221 int (*set_feature)(librdf_storage* storage, librdf_uri* feature, librdf_node* value); 222 223 /* Begin a transaction */ 224 int (*transaction_start)(librdf_storage* storage); 225 226 /* Begin a transaction with opaque data handle */ 227 int (*transaction_start_with_handle)(librdf_storage* storage, void* handle); 228 229 /* Commit a transaction */ 230 int (*transaction_commit)(librdf_storage* storage); 231 232 /* Rollback a transaction */ 233 int (*transaction_rollback)(librdf_storage* storage); 234 235 /* Get opaque data handle passed to transaction_start_with_handle */ 236 void* (*transaction_get_handle)(librdf_storage* storage); 237 238 /** Storage engine supports querying - OPTIONAL */ 239 int (*supports_query)(librdf_storage* storage, librdf_query *query); 240 241 /** Storage engine returns query results - OPTIONAL */ 242 librdf_query_results* (*query_execute)(librdf_storage* storage, librdf_query *query); 243 }; 244 245 246 /** 247 * librdf_storage_module_register_function: 248 * @world: world object 249 * 250 * Registration function for storage 251 * 252 * A storage module must define and export a function named of this 253 * type with function name "librdf_storage_module_register_factory". 254 * 255 * This function will be called by Redland and must call 256 * librdf_storage_register_factory() to register whatever storage 257 * backends are implemented in the module. 258 */ 259 typedef void (*librdf_storage_module_register_function)(librdf_world *world); 260 261 262 #ifdef __cplusplus 263 } 264 #endif 265 266 #endif 267 268