Code source wiki de Documentation technique

Version 5.1 par Matthieu Manginot le 23/07/2020 - 14:14
Afficher les derniers auteurs
1 == Prérequis ==
2
3 Hypercerts est une application Java qui se connecte à Apogée et au LDAP. Elle requiert l'utilisation d'une base MariaDB pour son fonctionnement interne. Elle se déploie sur des serveurs comme une application SpringBoot classique. Le WAR pourra être pris en charge par un tomcat et servir les utilisateur•ices via l'URL configurée.
4
5 |=(((
6 Technologie
7 )))|=(((
8 Version
9 )))
10 |(((
11 JDK
12 )))|(((
13 11+
14 )))
15 |(% colspan="1" %)(((
16 SpringBoot
17 )))|(% colspan="1" %)(((
18 2.3
19 )))
20 |(% colspan="1" %)(((
21 Vaadin (Frontend)
22 )))|(% colspan="1" %)(((
23 14
24 )))
25 |(((
26 Tomcat
27 )))|(((
28 9+
29 )))
30 |(% colspan="1" %)(((
31 MariaDB
32 )))|(% colspan="1" %)(((
33 14+
34 )))
35 |(% colspan="1" %)(((
36 Maven
37 )))|(% colspan="1" %)(((
38 3.6+
39 )))
40 |(% colspan="1" %)(((
41 Connection Apogée
42 )))|(% colspan="1" %)(((
43 \\
44 )))
45 |(% colspan="1" %)(((
46 Connection Apogée via WS
47 )))|(% colspan="1" %)(((
48 \\
49 )))
50 |(% colspan="1" %)(((
51 Connection LDAP
52 )))|(% colspan="1" %)(((
53 \\
54 )))
55 |(% colspan="1" %)(((
56 Docker (optionnel)
57 )))|(% colspan="1" %)(((
58 docker-compose 3
59 )))
60
61 == Téléchargement des sources ==
62
63 Les sources de l'application peuvent être téléchargées à [[cet endroit>>url:ftp://dufour18@download-sig.univ-lorraine.fr/public/hypercerts/hypercerts-1.0.2-SNAPSHOT.zip||shape="rect"]].
64
65 == Installation d'Hypercerts ==
66
67 === **Initialisation de la base** ===
68
69 La base de données MariaDB/MySQL s'initialise avec la commande Flyway suivante :
70
71 {{code language="bash" theme="Eclipse"}}
72 mvn -Dflyway.configFiles=flyway.properties flyway:migrate
73 {{/code}}
74
75 Le fichier flyway.properties doit être créé à partir du fichier exemple flyway-sample.properties. Il contient les properties standard à Flyway.
76
77 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
78 # Flyway
79 # ConfigFiles : https://flywaydb.org/documentation/configfiles
80 # mvn -Dflyway.configFiles=xxx.properties flyway:migrate
81 flyway.url=jdbc:mariadb://localhost/hypercerts?serverTimezone=Europe/Paris
82 flyway.schemas=hypercerts
83 flyway.user=XXX
84 flyway.password=
85 # Emplacement des fichiers sql de migration
86 flyway.locations=classpath:db/migration
87 # baselineOnMigrate
88 flyway.baselineOnMigrate=false
89 {{/code}}
90
91 Au besoin, les fichiers sql de migration peuvent être trouvés sous //src/main/resources/db/migration//.
92
93 Pour remettre à zéro la base, lancer le script //src/main/resources/db/reset/reset.sql //puis exécuter à nouveau Flyway//.//
94
95 === Configuration de l'application ===
96
97 Créer et compléter un fichier **application.yaml** à la racine du projet sur le modèle de **application-sample.yaml**
98
99 Des indications sont présentes dans le fichier pour aider à sa configuration.
100
101 === **Éléments de configuration importants** ===
102
103 ==== Property //app.production// ====
104
105 Pour les tests, mettre **app.production** à false pour obtenir une année supplémentaire (N-2) pour la génération, ainsi des diplômes avec résultats seront plus facilement trouvables.
106
107 En étant à false, cette property autorise également l'interception de tous les mails applicatifs.
108
109 ==== **Envoi de mail** ====
110
111 (% style="color: rgb(0,51,102);" %)__**Sur votre environnement de test/développement**, pour empêcher l'envoi de mails de test en réel, il est conseillé :__
112
113 * d'utiliser un mail catcher ([[https:~~/~~/mailcatcher.me/>>url:https://mailcatcher.me/||shape="rect"]]) en remplacement de votre smtp
114 * ou de configurer l'application pour intercepter tous les mails applicatifs avec ces valeurs :
115 ** **app.production** à false
116 ** **spring.mail.intercept.active** à true
117 ** et **spring.mail.intercept.mails** contenant une ou plusieurs adresses de réception des mails
118
119 Enfin, la property **app.mails** sert à définir une ou plusieurs adresses permettant de recevoir les mails applicatifs. ⚠ Aujourd'hui, dans cette version tous les envois sont en copie de cette property. Elle peut être laissée vide.
120
121 ==== WebServices Apogée ====
122
123 Les WebServices Apogée sont appelés par l'intermédiaire d'une librairie UL.
124
125 Les properties différent du classique configUrlServices.properties de l'AMUE.
126
127 Des headers peuvent être ajoutés en paramètre de chaque WebService.
128
129 Exemple :
130
131 {{code language="bash" theme="Eclipse" linenumbers="true" collapse="true"}}
132 ws:
133 apogee:
134 administratif:
135 url: https://api.univ.fr/apo/amue_apo_administratif
136 headers:
137 # header1: value1
138 # header2: value2
139 username: xxxx
140 password: xxxx
141 {{/code}}
142
143 === Configurer et lancer le projet dans Eclipse ===
144
145 * Importer le projet Maven dans eclipse.
146 * Lorsque la configuration est terminée, démarrer l'application en faisant un clic droit sur {{code language="none"}}fr.univlorraine.hypercerts.Application.java{{/code}} et en choisissant 'Run As / Java Application'.
147
148 === Customisation des services ===
149
150 Plusieurs services sont personnalisables en fonction de votre environnement.
151
152 Sous //fr.univlorraine.hypercerts.apogee.service.customs// :
153
154 * ApogeeUserServiceCustomExample
155 ** Personnalisation de la récupération des adresses mails des utilisateurs Apogée à partir de l'uid LDAP
156 * BlocageServiceCustomExample
157 ** Personnalisation de la récupération des blocages/interdits à partir d'un code étudiant Apogée
158 * ComposanteServiceCustomExample
159 ** Personnalisation de la récupération :
160 *** de toutes les composantes
161 *** des composantes pour un utilisateur à partir de l'uid LDAP
162 *** du nombre de composantes pour un utilisateur à partir de l'uid LDAP
163
164 Pour personnaliser un de ces services :
165
166 1. Copier la classe en la renommant
167 1. Implémenter la ou les méthodes
168 11. Vous êtes libre de créer des repositories ou d'utiliser l'entityManager directement
169 1. (((
170 Dé-commenter les 2 annotations :1. (((
171 @Service → Pour que Spring implémente le Service au démarrage
172 )))
173 1. (((
174 et @Override~*~* → Pour que l'implémentation surcharge le service par défaut
175 )))
176 )))
177 1. Au démarrage de l'application
178 11. Une ligne "//Overriding XXX for YYY implementation//" doit apparaître dans les logs
179
180 Exemple :
181
182 {{code language="java" theme="Eclipse" linenumbers="true" collapse="true"}}
183 /**
184 * Override default ApogeeUserService implementation.
185 * >> README
186 * Décommenter l'annotation @Service pour que le service soit instancié et l'annotation @OverrideApogeeUserService pour que l'implémentation soit utilisée.
187 *
188 * @author Matthieu Manginot
189 */
190 @NoArgsConstructor
191 @Slf4j
192 @Service
193 @OverrideApogeeUserService
194 public class ApogeeUserServicePERSO implements IApogeeUserService {
195
196 @PersistenceContext(unitName = "apogeeEntityManagerFactory")
197 private EntityManager entityManagerApogee;
198
199 @PostConstruct
200 public void init() {
201 log.info("Overriding {} for IApogeeUserService implementation", getClass().getCanonicalName());
202 }
203
204 /**
205 * @see fr.univlorraine.hypercerts.apogee.services.IApogeeUserService#getEmail(java.lang.String)
206 */
207 @Override
208 public String getEmail(final String uidLdap) {
209 /* Implémentation personnalisée de getEmail. entityManagerApogee.createNativeQuery... */
210 return "mail@univ.fr";
211 }
212 }
213 {{/code}}
214
215 ===
216 Paramétrage de Digiposte ===
217
218 //Documentation à venir. Toutes les fonctionnalités ne sont pas encore implémentées.//
219
220 === Tâches Maven ===
221
222 * Lancer l'application (hors d'un IDE) :
223
224 {{code language="bash" theme="Eclipse"}}
225 mvn spring-boot:run
226 {{/code}}
227
228 * Lancer les tests :
229
230 {{code language="bash" theme="Eclipse"}}
231 mvn verify
232 {{/code}}
233
234 * Créer le package pour production :
235
236 {{code language="bash" theme="Eclipse"}}
237 mvn clean package -Pproduction
238 {{/code}}
239
240 === Makefile ===
241
242 Un Makefile est également disponible. A la racine, utilisez `make help` pour obtenir les commandes disponibles.
243
244 == Tests unitaires ==
245
246 Pour s'assurez que les résultats d'admission de vos étudiants soient bien correctes, et afin d'éviter les faux positifs (donc envoyer une attestation de réussite à un•e étudiant•e non reçu•e aux examens), vous pouvez créer des tests unitaires avec vos propres jeux de données.
247
248 Les tests utilisent 3 classes:
249
250 * ResultatsTests.java
251 * ResultatsTestCase.java
252 * ResultatsServiceTest.java
253
254 ResultatTests.java énumère tous les tests. Il utilise l'objet ResultatTestCase dans lequel on précise:
255
256 * Le codEtu
257 * L'année
258 * Le diplôme
259 * La VDI
260 * Le résultat attendu (le test réussi si c'est ce résultat qui est trouvé dans ResultatService.java)
261
262 ResultatServiceTest.java est responsable du lancement des tests JUnit.
263
264 Ainsi, pour créer vos tests, ajoutez votre jeu de données dans ResultatTests, avec des résultats d'admissions réputés corrects et utilisez ResultatServiceTest pour tester les cas consécutivement.