Merge pull request #52 from Zenika/zenika-dev

Zenika dev

docs/fr/conversions/README.md

@@ -1 +1,50 @@
-# Conversions Pogues / DDI
+# Conversion de formats
+
+Le passage d'un format de meta donnée à un autre est une fonctionalité clef de l'application Pogues. Ces transformations peuvent être réalisées au moyen d'appels à des services externes, de transformations XSLT ou de n'importe quel autre moyen susceptible d'apparaître au gré des besoins. Ces transformations peuvent être chaînées tout comme elles peuvent être appliquées de façon unitaire.
+
+Toutes les implementations utilisées pour mener à bien ces transformations s'appuient donc sur une interface commune afin de faciliter la mise en place de chaînes de transformations répondant aux cas d'usages imposés par les spécifications. 
+
+## L'interface Transformer
+
+En conséquence toute implémentation de transformation DOIT implémenter l'interface Transformer dont le contrat définit un certain nombre de méthodes  ```transform``` s'appliquant à différents types d'entrées/sorties 
+
+[include](../../../src/main/java/fr/insee/pogues/transforms/Transformer.java)
+
+Une table de paramètre passée en argument permet aux transformers  de s'appuyer sur de la configuratione externe pour produire leur sortie.
+
+## L'interface fonctionnelle transform
+
+Pour nous permettre d'utiliser les méthodes de l'interface Transform en s'appuyant sur [les références de méthodes](https://docs.oracle.com/javase/tutorial/java/javaOO/methodreferences.html) de Java 8, une interface fonctionnelle Transform est définie, à laquelle se conforment toutes les méthodes de l'interface Transformer:
+
+[import:'marker0'](../../../src/main/java/fr/insee/pogues/transforms/PipeLine.java)
+
+## La classe Pipeline
+
+La classe Pipeline nous permet de chaîner nos méthodes de transformation pour élaborer des scenarios de transformation complexes
+
+Par exemple la visualisation d'un questionnaire dans l'application est réalisée au moyen de la chaîne de transformation suivante:
+
+```[Pogues JSON] -> [Pogues XML] -> [DDI] -> [XForm] -> [Form URI]```
+
+Voici un example de code représentant une chaîne de transformation:
+```java
+class PipeSample{
+    public String pipe(HttpServletRequest request){
+        return pipeline
+            .from(request.getInputStream())
+            .map(jsonToXML::transform, params)
+            .map(xmlToDDI::transform, params)
+            .map(ddiToXForm::transform, params)
+            .map(xformToUri::transform, params)
+            .transform()
+            .getBytes();
+    }
+}
+``` 
+
+Dans cette version les chaînes de transformation s'appuient sur des entrées/sorties de type String, à l'exception du point d'entrée fournit sous forme de Stream ou de String. 
+
+La réalisation de la chaine de transformation s'effectue en fournissant une entrée à la chaîne au moyen de la méthode ```from``` de la classe PipeLine.
+Nous pouvons ensuite chaîner nos différentes étapes de transformation en utilisant la méthode ```map``` de la classe PipeLine. Les méthodes from et map retournent l'instance de la classe PipeLine, permettant une écriture fluide de la chaîne de transformation.
+
+La transformation est rélisée uniquement à l'appe de la methode transform() sur l'instance de la classe PipeLine

docs/fr/workflow/docker/README.md

@@ -48,3 +48,16 @@ Docker et docker-compose sont utilisés pour orchestrer un environnement d'exéc
  - Exécuter des tests d'intégration pendant la phase de build avec Travis.
 
 
+## Utilisation avec Windows
+
+### Installation de docker toolbox
+
+[Documentation officielle](https://docs.docker.com/toolbox/toolbox_install_windows/)
+
+### Accès au container tomcat
+
+Sur les systèmes Unix (mac/linux) la configuration définie dans le répertoire docker nous permet d'accéder au point d'entrée de l'application (le container tomcat) à l'adresse localhost sur le port 8080.
+Après installation de docker toolbox, les plateformes windows s'appuient sur une machine virtuelle pour exécuter nos containers. L'accès au point d'entrée de l'application s'effectue donc alors par l'addresse ip de la machine virtuelle démarrée au lancement de vos containers.
+
+*NB: Pour accéder au point d'entrée sur l'hôte local il est possible de configurer une règle de redirection de port sur la machine virtuelle créée par docker toolbox* 
+

docs/fr/workflow/docker/docker-folders.md

@@ -5,7 +5,15 @@
 Les fichiers nécessaires à la génération des images docker et à l'exécution de l'environnement sont situés à la racine du projet dans le répertoire docker:
 
 ```
+├── colectica
+│   ├── app
+│   │   ├── db.json
+│   │   ├── middleware.js
+│   │   └── routes.json
+│   └── Dockerfile
 ├── docker-compose.yml
+├── elastic
+│   └── Dockerfile
 ├── ldap
 │   ├── db
 │   │   ├── groups.ldif
@@ -19,12 +27,15 @@ Les fichiers nécessaires à la génération des images docker et à l'exécutio
 │   │   └── data.sql
 │   └── Dockerfile
 └── tomcat
-    └── Dockerfile
+    ├── Dockerfile
+    ├── pogues-bo.properties
+    ├── rmspogfo.properties
+    └── rmspogfo.war
 
 ```
 
 
-Les trois sous répertoires contiennent chacun un fichier [Dockerfile](https://docs.docker.com/engine/reference/builder/)
+Les cinq sous répertoires contiennent chacun un fichier [Dockerfile](https://docs.docker.com/engine/reference/builder/)
 utilisé pour générer une image Docker, ainsi que les fichiers de configuration ajoutés au container (au build par utilisation des directives [ADD/COPY](https://stackoverflow.com/questions/24958140/what-is-the-difference-between-the-copy-and-add-commands-in-a-dockerfile) dans le Dockerfile ou à l'exécution par l'utilisation d'un volume monté)
 
 ### LDAP
@@ -41,6 +52,11 @@ Certains éléments du schéma défini divergent donc volontairement du schéma
 Le répertoire postgresql contient un fichier de définition pour la génération d'une image postgresql (version 9.5) contenant un script d'import 
 exécuté au lancement du container. Au démarrage du container, ce script crée les tables nécessaires au fonctionnement de l'application.
 
+### Colectica
+
+Le répertoire colectica s'appuie sur un serveur node.js pour répondre aux requeêtes adressées en production à l'API du dépôt Colectica
+
+
 ### Tomcat
 
 Le répertoire tomcat contient un environnement d'exécution pour l'application.

docs/fr/workflow/docker/docker-usage.md

@@ -22,35 +22,103 @@ docker-compose up
 
 L'exécution de cette commande démarre les trois containers et relie le container tomcat aux containers ldap et postgresql.
 
-***NB:*** Pour indiquer au serveur tomcat qu'il doit utiliser les containers comme backend il faut éditer la variable d'environement CATALINA_OPT comme ceci:
+***NB:*** Pour indiquer au serveur tomcat qu'il doit utiliser les containers comme backend on peut éditer la variable d'environement CATALINA_OPT dans le fichier docker-compose.yml
+
+```yaml
+  tomcat:
+    build: ./tomcat
+    environment:
+      - fr.insee.pogues.env=qa
+    volumes:
+      - "./tomcat/rmspogfo.war:/usr/local/tomcat/webapps/rmspogfo.war"
+      - "./tomcat/pogues-bo.properties:/usr/local/tomcat/webapps/rmspogfo.properties"
+    networks:
+      - intra
+    ports:
+      - "8080:8080"
+```
+
+Si un fichier rmspogfo.properties est présent dans le répertoire tomcat, les propriétés définies dans ce fichier surchargeront les propriétés définies dans le répertoire d'environnement qa
+
+### Utilisation en mode développement
+
+En mode développement, utiliser docker-compose pour démarrer uniquement les backends nécessaires à tomcat et laisser votre IDE gérer la compilation et le déploiement de votre application.
+
+ - Démarrer uniquement les backends nécessaires à tomcat:
 
 ```bash
-export CATALINA_OPTS="env.qav.qa"
+docker-compose up postgresql ldap elasticsearch colectica
 ```
 
-Cette variable est définie par défaut à la génération de l'image docker donc implicitement définie lors de l'utilisation de la commande ```docker-compose up```
+ - Indiquer à tomcat qu'il doit utiliser ces containers comme backends:
 
-### Utilisation en mode développement
+Sur Eclipse ou IntelliJ il suffit d'éditer la configuration de lancement 
+pour passer la variable d'environnement appropriée à tomcat
+
+```
+-Dfr.insee.pogues.env=dev
+```
+
+### Utilisation en mode déploiement
 
-En mode développement plusieurs solutions:
+ - Récupérer la dernière version stable de l'application
+
+   - [Accès aux release](https://github.com/InseeFr/Pogues-Back-Office/releases)
 
- - Configurer l'exécution de l'application pour utiliser le container tomcat comme environnement d'exécution
- - Utiliser docker-compose pour démarrer uniquement les backends nécessaires à tomcat et laisser votre IDE gérer la compilation et le déploiement de votre application.
+ - Déposer le war téléchargé dans le répertoire docker/tomcat
 
-Pour la seconde solution (privilégiée ici)
+*NB: Alternativement on peut packager la version locale en utilisant le script prévu à cet effet*
 
-Démarrer uniquement les backends nécessaires à tomcat:
+```bash
+bash scripts/build.sh rmspogfo
+```
 
+
+ - Lancer l'ensemble des containers
+
 ```bash
-docker-compose up postgresql ldap
+docker-compose up
 ```
 
+### Configurer le container colectica
 
-Indiquer à tomcat qu'il doit utiliser ces containers comme backends:
+Le container colectica s'appuie sur le module [json-server](https://github.com/typicode/json-server)
 
-Sur Eclipse ou IntelliJ il suffit d'éditer la configuration de lancement 
-pour passer la variable d'environnement appropriée à tomcat
+Ce module exploite un fichier json pour exposer des resources via une API REST
+
+L'API Colectica contourne un certain nombre de principes des architectures REST et il faut donc configurer json-server pour rendre son comportement similaire à celui de l'API Colectica
+
+#### Réécriture d'URL
 
+Pour prendre l'exemple de la resources /items, cette resource est définie par json-server à partir de la clef items définie dans le fichier db.json et de la collection associée.
+
+Pour faire correspondre cette url de resource à l'URL appelée en production on éditera le fichier routes.json de la manière suivante:
+
+```json
+{
+  "/api/v1/item/fr.insee/:id?api_key=ADMINKEY": "/items/:id",
+  "/api/v1/set/fr.insee/:id?api_key=ADMINKEY": "/set",
+  "/api/v1/item/_getList?api_key=ADMINKEY": "/items"
+}
 ```
--Dfr.insee.pogues.env=env.dev
+
+De la même manière, l'API Colectica expose un certain nombre de routes renvoyant des resources à l'invocation d'appels utilisant le verbe POST
+
+Ce type de comportement n'étant pas strictement conforme aux architectures REST, on a besoin d'ajouter les middleware nécessaires au code exécuté par notre serveur en éditant le fichier app/middleware.js:
+
+```js
+module.exports = (server, router) => {
+
+    server.post('/items', (req, res) => {
+        const db = router.db    
+        const items = router.db.get('items').value()
+        res.jsonp(items)
+    })
+
+    server.get('/items/:id', (req, res) => {
+        const db = router.db
+        const item = router.db.get('items').find({ 'Identifier': req.params.id }).value()
+        res.jsonp(item)
+    })
+}
 ```

docs/fr/workflow/travis.md

@@ -35,7 +35,7 @@ La publication des fichiers compilés par gitbook s'effectue via un push sur le
  - Inclure ce token dans le scope public_repo (repo pour un repository privé)
  - Associer la variable d'environnement GITHUB_TOKEN au token sur le  [tableau de bord de Travis du projet](https://travis-ci.org/)
 
- ## Reporting
+## Reporting
 
 Chaque build génère un rapport de couverture envoyé à [coveralls.io](https://coveralls.io/)
 
@@ -51,3 +51,12 @@ Chaque build génère un rapport de couverture envoyé à [coveralls.io](https:/
 mvn -DrepoToken=$COVERALLS_TOKEN coveralls:report
 ```
 
+## Publication des releases
+
+ Pour publier une release, il suffit de mettre à jour la version de l'application dans le fichier pom.xml et de soumettre une pull request sur le dépôt de l'INSEE
+
+ Par convention, on préfèrera associer un commit à cette unique mise à jour avec le message "Draft release vx.x.x" 
+
+ Les releases sont publiées sur github sous la forme d'un war contenant l'application packagée (frontend + backend) et sont accessibles à [l'adresse suivante](https://github.com/InseeFr/Pogues-Back-Office/releases)
+
+

pom.xml

@@ -4,7 +4,7 @@
     <groupId>fr.insee</groupId>
     <artifactId>Pogues-BO</artifactId>
     <packaging>war</packaging>
-    <version>0.0.28-SNAPSHOT</version>
+    <version>0.0.29-SNAPSHOT</version>
     <name>Pogues-BO</name>
 
     <properties>