User-Documentation/Storage.md

@@ -162,7 +162,7 @@ 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.
+This object is supposed to take the result of a native query and convert it into the corresponding InteGraal atoms or substitutions.
 
 5. Create the wrapper itself.
 
@@ -210,4 +210,53 @@ To use this type of storages, represented by the `MappingDatasourceWrapper`, mul
 We provide some generic solutions for SQL and SPARQL as well as some potential solution for JSON data.
 
 
+### InteGraal Relational View Definition (Mapping Wrapper)
+
+A Mapping Wrapper is an implementation of a factbase, which allows to define a Relational View on any system (ie, it can be an external system or even InteGraal). For example, you can define a view over an external  DBMS system (relational, triplestore, graph, noSQL, ...), a Web Application, or an existing InteGraal knowledge base.
+
+As Mapping 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.
+
+Note that a Mapping Wrapper can operate in read-only mode, or in read-write mode. In the first case, data insertion and data deletion operations are supposed to raise an exception. For the time being, InteGraal implementations only supports Relational Views working in read-only mode. This means that the current implementation cannot update the a Relational View, by adding a new tuple or by removing an existing tuple. This feature can of course be added.
+
+
+When defining your own mapping wrapper, we suggest to respect the following guidelines.
+
+1. Create a driver. 
+
+This object is supposed to only connecti to the target system (DBMS, Web Application). Note that this is a major difference with the Wrapper defined above.
+
+2. Create a query specializer.
+
+This object is supposed to take in input a "pre"-query and output a native query for the target system. A "pre"-query is a query which contains placeholders for parameters (eg, `SELECT NAME FROM EMP WHERE ID=%%`). The specializers then replaces these placeholders (eg, %%) with concrete values (eg, 42) that are necessary to obtain a native query which is syntactically correct `SELECT NAME FROM EMP WHERE ID=42`. 
+
+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 atoms or substitutions.
+
+5. Create the mapping wrapper itself.
+
+To do so, the mapping wrapper will have to extend the abstract class `MappingDatasourceWrapper<NativeQueryType, NativeResultType>`. 
+
+It suffices to implement the constructor and pass as parameter 
+
+1. the specializer
+2. the evaluator 
+3. the transformer
+
+6. Extend MappingBuilder.
+
+Add your new mapping wrapper to the MappingBuilder class
+.
+