User-Documentation/Storage.md

@@ -125,13 +125,73 @@ Once this is done, you can use your new implementation in the same way as presen
 
 We can describe the storages available in the two following kinds
 
-### InteGraal storages
 
-These storages are handled entierly by InteGraal. They are accessible using the StorageBuilder and give access to read, write and update queries.
+### InteGraal Wrappers
+
+A Wrapper is an implementation of a factbase, which is based on an external system (ie, which is not InteGraal). For example, you can use as external system a DBMS (relational, triplestore, graph, noSQL, ...) or a Web Application.
+
+As a Wrapper is an implementation of a factbase, it must provide the facilities for:
+1. answering queries
+2. inserting data
+3. deleting data
+
+These facilities are defined in the `Factbase` interface, and indeed a Wrapper needs to implement the `Factbase` interface to work.
+
+
+When defining your own wrapper, we suggest to respect the following guidelines.
+
+1. Create a driver. 
+
+This object is supposed to do two things, namely:
+(a) connecting to the target system (DBMS, Web Application) and 
+(b) know the conventions of the native query language of the system (eg, there are several SQL dialects which slightly differ between RDBMS ; the driver must know the right query/update SQL syntax).
+
+2. Create a strategy.
+
+This object is supposed to do two things, namely:
+(a) define the data-layout for atoms (eg, they can become a relational table, a tree, a graph, etc)
+(b) translate terms and predicates from InteGraal to the external system (eg, the predicate foad:friendOf becomes the table name "pred_foaf_friend_of" in SQL, or again term "Bob" becomes the integer 3 if an encoding for terms is used)
+
+Note : the strategy may need the driver (defined before) to retrieve meta-informations about the data-layout. For example, in our implementation of SQL Wrappers the correspondance between predicates and table-names in SQL is stored in a dedicated table of the DBMS itself.
+
+3. Create an evaluator.
+
+This object is supposed to take a native query (SQL, ... ) and return the result of the native query.
+
+The evaluator evidently will use the driver.
+
+4. Create a transformer.
+
+This object is supposed to take the result of a native query and convert it into the corresponding InteGraal objects.
+
+5. Create the wrapper itself.
+
+A Wrapper is an implementation of a factbase supposed to implement methods for 
+- `match(atom a)`
+- `add(atom a)`
+- `remove(atom a)`
+
+To do so, the wrapper will use all of the previous objects we defined.
+Furthermore, it will have a dedicated algorithm for constructing the native queries to be shipped to the external system.
+
+For example, to implement `match(atom a)` the wrapper must do the following
+1. Use strategy to build a native query corresponding to `match(atom a)`
+2. Use the evaluator to evaluate the native query
+3. Use the transformer to build the InteGraal objects corresponding to the answers to `match(atom a)`
+
+The implementation of `add(atom a)` and `remove(atom a)` is similar ; they simply do not require the last step of conversion into InteGraal objects. 
+
+6. Extend StorageBuilder.
+
+Add your new wrapper to the StorageBuilder class
+
+
+### Delegate more complex queries
 
 Some algorithm exist to handle queries and even rules directly on the storage without retrieving data in memory. This is denoted by the `DatalogRuleDelegatable` interface.
 
-### External datasources
+
+### External datasources (renommmer)
 
 These storages are not handled entierly by InteGraal. They are accessible using user-defined queries.
 
@@ -148,3 +208,6 @@ To use this type of storages, represented by the `MappingDatasourceWrapper`, mul
 * Some way to transform the result from the query to relational.
 
 We provide some generic solutions for SQL and SPARQL as well as some potential solution for JSON data.
+
+
+