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