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
27extern "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 */
40typedef 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 */
118struct 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 */
259typedef void (*librdf_storage_module_register_function)(librdf_world *world);
260
261
262#ifdef __cplusplus
263}
264#endif
265
266#endif
267
268