Tony CHEMIT pushed to branch develop-9.0.x at ultreiaio / ird-observe Commits: 8530bbf1 by Tony Chemit at 2023-01-14T14:30:39+01:00 Documentation de l'outil de reporting - Closes #2597 - - - - - c41c5fe8 by Tony Chemit at 2023-01-14T14:30:39+01:00 Report API - Remove no more used operation GroupByLength - - - - - 296f1bb9 by Tony Chemit at 2023-01-14T14:30:39+01:00 Report API - Replace operation SumFloatColumn by SumColumn and remove it - - - - - 006fa12f by Tony Chemit at 2023-01-14T14:30:39+01:00 update pom - - - - - 12 changed files: - core/persistence/report/src/main/resources/observe-reports.properties - core/services/test/src/main/resources/fixtures/fr/ird/observe/services/service/ReportService-psLogbookWellPlanCheck.properties - model/src/main/resources/observe-reports-legacy.properties - pom.xml - src/site/markdown/index.md - + src/site/markdown/report/embedded-operations.md - + src/site/markdown/report/embedded-reports.md - + src/site/markdown/report/index.md.vm - + src/site/markdown/report/syntax.md - src/site/site_fr.xml - − toolkit/api-report/src/main/java/fr/ird/observe/report/operations/GroupByLength.java - − toolkit/api-report/src/main/java/fr/ird/observe/report/operations/SumFloatColumn.java Changes: ===================================== core/persistence/report/src/main/resources/observe-reports.properties ===================================== @@ -969,7 +969,8 @@ Left Join a.vesselActivity vesselActivity \ Where t.id In :tripId and w.activity = a and vesselActivity.id = 'fr.ird.referential.ps.common.VesselActivity#1239832675369#0.12552908048322586' \ Group By vessel.code,vessel.label2,t.startDate,t.endDate,r.date,a.time,a.number \ Order By vessel.code,t.startDate,r.date,a.time -report.psLogbookWellPlanCheck.operations.1.type=SumFloatColumn +report.psLogbookWellPlanCheck.operations.1.type=SumColumn +report.psLogbookWellPlanCheck.operations.1.parameters=0|6 report.psObservationActivityWithComment.modelType=PS report.psObservationActivityWithComment.name=Observations - Activités avec comment et leurs positions report.psObservationActivityWithComment.description=Afficher les activités avec comment et leurs positions géographiques ===================================== core/services/test/src/main/resources/fixtures/fr/ird/observe/services/service/ReportService-psLogbookWellPlanCheck.properties ===================================== @@ -20,9 +20,8 @@ # #L% ### result.0=483^CAP BOJADOR^30/3/2019^8/4/2019^30/3/2019^1^15:12^0.0^123.0^43.0^0.0^0.0^0.0^0.0^24.0^0.0^0.0^166.0^24.0^142.0 -result.1=Total^-^-^-^-^-^-^0^123^43^0^0^0^0^24^0^0^166^24^142 result.columns=20 -result.rows=2 +result.rows=1 syntax.columns=20 syntax.columnsHeader=Code bateau^Nom bateau^Date départ^Date arrivée^Date de route^Numéro activité^Heure activité^Logbook YFT^Logbook SKJ^Logbook BET^Logbook ALB^Logbook Autres^Plan de cuves YFT^Plan de cuves SKJ^Plan de cuves BET^Plan de cuves ALB^Plan de cuves Autres^Logbook Total^Plan de cuves Total^Différence syntax.description=Livre de bord - Vérification des plan de cuves ===================================== model/src/main/resources/observe-reports-legacy.properties ===================================== @@ -1403,7 +1403,7 @@ Plan de cuves Autres,\ Logbook Total,\ Plan de cuves Total,\ Différence -report.psLogbookWellPlanCheck.operations.1=SumFloatColumn +report.psLogbookWellPlanCheck.operations.1=SumColumn:0|6 report.psLogbookWellPlanCheck.request.1=0,0|row| \ Select vessel.code,\ vessel.label2,\ ===================================== pom.xml ===================================== @@ -23,7 +23,7 @@ <parent> <groupId>io.ultreia.maven</groupId> <artifactId>pom</artifactId> - <version>2023.2</version> + <version>2023.3</version> </parent> <groupId>fr.ird.observe</groupId> <artifactId>ird-observe</artifactId> ===================================== src/site/markdown/index.md ===================================== @@ -2,7 +2,7 @@ ## Présentation -Le logiciel *ObServe*... TODO +Le logiciel *ObServe*... **TODO** # Les documents @@ -13,6 +13,7 @@ Le logiciel *ObServe*... TODO - [Administration web (v7)](./server-configuration-application-v7.html) - [Configuration client](./observe-client.html) - [Configuration server](./observe-server.html) +- [Documentation de l'outil de reporting](./report/index.html) ===================================== src/site/markdown/report/embedded-operations.md ===================================== @@ -0,0 +1,266 @@ +# Documentation des opérations disponibles + +Ce document décrit toutes les opérations disponibles sur les rapports. + +On en distingue deux types : + + * les opérations génériques : elles peuvent être utilisées pour écrire de nouveaux rapports, leur fonctionnement n'est pas lié au modèle de données d'ObServe + * les opérations spécifiques : elles correspondent à des opérations utilisées sur des rapports embarqués et ne devraient pas être utilisées pour de nouveaux rapports + +## Les opérations génériques + +### ComputeDynamicHeader + +Cette opération permet de construire des en-têtes du résultat à partir de deux choses : + + * une première partie qui est une liste de colonnes fixes + * une seconde partie qui utilise une variable de répétition pour décrire le reste des en-têtes de colonnes de manière dynamique + +**Cette opération requière un paramétrage**. + +Exemple d'utilisation : + +```properties +report.xxx.repeatVariable.1.name=reasonForDiscard +report.xxx.repeatVariable.1.type=fr.ird.observe.entities.referential.ps.observation.ReasonForDiscard +report.xxx.repeatVariable.1.request=Select sf \ +From ReasonForDiscardImpl sf \ +Order by sf.code +report.xxx.operations.1.type=ComputeDynamicHeader +report.xxx.operations.1.parameters=Espèce,Total BL,Total BO|reasonForDiscard +``` + +**À noter que pour décorer les valeurs dynamique, on utilise si c'est une entité de référentiel de type *I18n*, son *label2*, sinon un *toString*.** + +Les décorations pourraient être améliorées pour utiliser les décorateurs associées au type d'entitée, mais nous n'avons pas eu ce besoin pour le moment. + +### CopyRepeatVariableToFirstColumn + +Cette opération permet de recopier dans la première colonne du résultat, l'univers d'une variable de répétition. + +**Cette opération requière un paramétrage**. + +Exemple d'utilisation : + +```properties +report.xxx.repeatVariable.1.name=length +report.xxx.repeatVariable.1.type=java.lang.Float +report.xxx.repeatVariable.1.request=Select distinct ntl.length \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set.sample nts \ +Join nts.sampleMeasure ntl with ntl.species.id = :species And ntl.sizeMeasureType.id = :sizeMeasureType \ +Where t.id In :tripId \ +Order By ntl.length +report.xxx.operations.1.type=CopyRepeatVariableToFirstColumn +report.xxx.operations.1.parameters=length +``` + +Le meme mécanisme de décoration que pour l'opération précédente est utilisé. + +### ExecuteRequestAndReorganizeDataByRepeatVariable + +Cette opération permet d'exécuter une requête et ensuite de réorganiser le résultat selon les valeurs définies +via deux variables de répétition, une pour l'axe des abscisses et une par l'axe des ordonnées. + +**Cette opération requière un paramétrage** avec trois valeurs (séparées via des *pipes*) : + + * le premier paramètre indique la variable de répétition pour ordonner sur l'axe des abscisses + * le second paramètre indique la variable de répétition pour ordonner sur l'axe des ordonnées + * le troisième paramètre est la requête à executer + +Exemple d'utilisation + +```properties +report.xxx.repeatVariable.1.name=length +report.xxx.repeatVariable.1.type=java.lang.Float +report.xxx.repeatVariable.1.request=Select distinct ntl.length \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set.sample nts \ +Join nts.sampleMeasure ntl with ntl.species.id = :species And ntl.sizeMeasureType.id = :sizeMeasureType \ +Where t.id In :tripId \ +Order By ntl.length +report.xxx.repeatVariable.2.name=speciesFate +report.xxx.repeatVariable.2.type=fr.ird.observe.entities.referential.ps.common.SpeciesFate +report.xxx.repeatVariable.2.request=Select sf \ +From SpeciesFateImpl sf \ +Order by sf.discard, sf.code +report.xxx.repeatVariable.2.addNull=true +report.xxx.operations.1.type=ExecuteRequestAndReorganizeDataByRepeatVariable +report.xxx.operations.1.parameters=length|speciesFate|Select ntl.length, sf.id, sum(ntl.count) \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set.sample nts \ +Join nts.sampleMeasure ntl With ntl.species.id = :species And ntl.sizeMeasureType.id = :sizeMeasureType \ +Left Join ntl.speciesFate sf \ +Where t.id In :tripId \ +Group By ntl.length, sf \ +Order By ntl.length +``` + +**À noter que la requête doit produire une résultat avec trois colonnes, la première pour l'axe des abscisses, +la seconde pour l'axe des ordonnées et la troisième pour la valeur effective à replacer à la bonne position**. + +**À noter aussi que les deux variables de répétition doivent être ordonnées afin de produire un résultat invariant.** +### SumColumn + +Cette opération permet de réaliser la somme par colonne, i.e de rajouter une dernière ligne qui fait la somme des +valeurs décimales de chaque colonne. + +Le résultat sera un **entier avec décimales** (on arrondit à 4 décimales). + +**À noter que si une colonne contient des valeurs non numériques, le total n'est pas effectué et la valeur de la +celulle sera *-***. + +**À noter aussi que si on se retrouve avec une seule colonne à sommer, alors la ligne *total* ne sera pas ajoutée**. + +Exemple d'utilisation (sans paramétrage) + +```properties +report.xxx.operations.1.type=SumColumn +``` + +L'opéréation peut être paramétrée pour indiquer sur quelle zone on doit effectuer les sommes. + +Le paramétrage est une position sur le résultat final codifié sous la forme ```x|y```. + +Exemple d'utilisation (avec paramétrage) + +```properties +report.xxx.operations.1.type=SumColumn +report.xxx.operations.1.parameters=0|1 +``` + +Ici on commence la somme à partir de la ligne **0** et la colonne **1**. + +### SumIntColumn + +Cette opération est identique à l'opération précédente, pour des entiers. + +On effectue donc ici une somme d'entiers. Si une des valeurs de la colonne n'est pas un entier, on remplace alors +le résultat par **-**. + +Le paramétrage optionnel est identique aussi. + +Exemple d'utilisation (sans paramétrage) + +```properties +report.xxx.operations.1.type=SumIntColumn +``` +Exemple d'utilisation (avec paramétrage) + +```properties +report.xxx.operations.1.type=SumIntColumn +report.xxx.operations.1.parameters=0|1 +``` + +Ici on commence la somme à partir de la ligne **0** et la colonne **1**. + +### SumRow + +Cette opération permet de réaliser la somme par ligne, i.e de rajouter une dernière colonne qui fait la somme des +valeurs décimales de chaque ligne. + +Le résultat sera un **entier avec décimales** (on arrondit à 4 décimales). + +**À noter que si une ligne contient des valeurs non numériques, le total n'est pas effectué et la valeur de la +celulle sera *-***. + +**À noter aussi que si on se retrouve avec une ligne colonne à sommer, alors la colonne *total* ne sera pas ajoutée**. + +Exemple d'utilisation (sans paramétrage) + +```properties +report.xxx.operations.1.type=SumRow +``` + +L'opéréation peut être paramétrée pour indiquer sur quelle zone on doit effectuer les sommes. + +Le paramétrage est une position sur le résultat final codifié sous la forme ```x|y```. + +Exemple d'utilisation (avec paramétrage) + +```properties +report.xxx.operations.1.type=SumRow +report.xxx.operations.1.parameters=0|1 +``` + +Ici on commence la somme à partir de la ligne **0** et la colonne **1**. + +### SumIntRow + +Cette opération est identique à l'opération précédente, pour des entiers. + +On effectue donc ici une somme d'entiers. Si une des valeurs de la colonne n'est pas un entier, on remplace alors +le résultat par **-**. + +Le paramétrage optionnel est identique aussi. + +Exemple d'utilisation (sans paramétrage) + +```properties +report.xxx.operations.1.type=SumIntRow +``` + +Exemple d'utilisation (avec paramétrage) + +```properties +report.xxx.operations.1.type=SumIntRow +report.xxx.operations.1.parameters=0|1 +``` + +Ici on commence la somme à partir de la ligne **0** et la colonne **1**. + +## Opérations spécifiques à ObServe + +Ces opérations étant utilisées uniquement dans les rapport embarqués, elles ne possèdent aucun paramétrage. + +Nous ne donnerons pas d'exemple d'utilisation, mais le lien vers le rapport qui l'utilise. + +## ComputeMeasurementsLongline + +Cette opération permet pour un équipement déclaré d'une marée (du domaine Palangre), de regrouper les différentes +composantes de cet équipement. + +**Cette opération ne requière aucun paramétrage.** + +Elle est utilisée dans le rapport [llCommonTripGearUseFeatures](./embedded-reports.html#llCommonTripGearUseFeatures). + +## UnionAndSortLlLogbookSamples + +Cette opération permet de regrouper les échantillons du modèle *Senne - Livre de bord* qui existent au niveau des +activités et des marées, puis de les trier. + +**Cette opération ne requière aucun paramétrage.** + +Elle est utilisée dans le rapport [llLogbookSamplesOnBoth](./embedded-reports.html#llLogbookSamplesOnBoth). + +## ComputeLocalmarketSampleWellAndSpeciesMeasure + +Cette opération permet de calculer les distributions d'échantillons du modèle *Senne - Marché local* au niveau des cuves. + +**Cette opération ne requière aucun paramétrage.** + +Elle est utilisée dans le rapport [psLocalmarketSample](./embedded-reports.html#psLocalmarketSample). + +## ComputeLocalmarketSurveyPart + +Cette opération permet de calculer les données des sondages du modèle *Senne - Marché local*. + +**Cette opération ne requière aucun paramétrage.** + +Elle est utilisée dans le rapport [psLocalmarketSurvey](./embedded-reports.html#psLocalmarketSurvey). + +## ComputeMeasurementsSeine + +Cette opération permet pour un équipement déclaré d'une marée (du domaine Senne), de regrouper les différentes +composantes de cet équipement. + +**Cette opération ne requière aucun paramétrage.** + +Elle est utilisée dans le rapport [psCommonTripGearUseFeatures](./embedded-reports.html#psCommonTripGearUseFeatures). + ===================================== src/site/markdown/report/embedded-reports.md ===================================== @@ -0,0 +1,143 @@ +# Documentation des rapports embarqués par l'application + +Ce document décrit l'ensemble des rapports embarqués par l'application. + +## Modèle Palangre + +### llCommonTripGearUseFeatures + +Liste des équipements + +### llLanding + +Liste des débarquements + +### llLogbookActivities + +Livre de bord - Liste des activités + +### llLogbookCatches + +Livre de bord - Liste des captures + +### llLogbookSamplesOnActivity + +Livre de bord - Liste des échantillons rattachés au niveau calée + +### llLogbookSamplesOnBoth + +Livre de bord - Liste des échantillons + +### llLogbookSamplesOnTrip + +Livre de bord - Liste des échantillons rattachés au niveau marée + +## Modèle Senne + +### psCommonTripGearUseFeatures + +Liste des équipements + +### psLocalmarketBatch + +Marché local - Lots + +### psLocalmarketSample + +Marché local - Échantillons + +### psLocalmarketSurvey + +Marché local - Sondages + +### psLogbookActivity + +Livre de bord - Vérification croisée des captures + +### psLogbookSampleMeasures + +Livre de bord - Mesures par échantillons + +### psLogbookSampleSet + +Livre de bord - Calées des échantillons + +### psLogbookSampleSpeciesMeasures + +Livre de bord - Mesures par sous échantillons + +### psLogbookSampleSpeciesMeasuresCount + +Livre de bord - Nombre de mesures par sous échantillons + +### psLogbookTrip + +Livre de bord - Vérification croisée des données débarquements + +### psLogbookWellPlan + +Livre de bord - Plan de cuves + +### psLogbookWellPlanCheck + +Livre de bord - Vérification des plan de cuves + +### psObservationActivityWithComment + +Observations - Activités avec comment et leurs positions + +### psObservationAllActivities + +Observations - Toutes les activités et leurs positions + +### psObservationCatch + +Observations - Liste des captures selon le type de banc, filtrées par groupe + +### psObservationCatchTotalCountByGroupAndSpeciesFateDiscardPerAssociation + +Observations - Dénombrement des captures selon le type d'association, filtrées par groupe et mode (rejeté/conservé) + +### psObservationCatchTotalCountByGroupPerReasonForDiscard + +Observations - Dénombrement des rejets par type de banc et raison de rejet, filtrés par groupe (en t) + +### psObservationCatchTotalCountByGroupPerSpeciesFate + +Observations - Dénombrement des captures par type de banc et devenir, filtrés par groupe + +### psObservationCatchWeightByGroupAndSpeciesFateDiscardPerAssociation + +Observations - Poids des captures selon le type d'association, filtrées par groupe et mode (rejeté/conservé) (en t) + +### psObservationCatchWeightByGroupPerReasonForDiscard + +Observations - Poids des rejets par type de banc et raison de rejet, filtrés par groupe (en t) + +### psObservationCatchWeightByGroupPerSpeciesFate + +Observations - Poids des captures par type de banc et devenir, filtrés par groupe (en t) + +### psObservationDailySetAndCatch + +Observations - Nombre de calées et captures journalières d'une marée + +### psObservationFobUsageExtended + +Observations - Utilisation des FOB, tableau détaillé + +### psObservationFobUsageMinimal + +Observations - Utilisation des FOB, tableau simplifiée + +### psObservationLengthsDistribution + +Observations - Distribution des tailles par espèces et type de mesure + +### psObservationRepartionCaleeParCuve + +Observations - Répartition des calées par cuves + +### psObservationSetByAssociation + +Observations - Nombre de calées selon le type d’association \ No newline at end of file ===================================== src/site/markdown/report/index.md.vm ===================================== @@ -0,0 +1,161 @@ +# Documentation des rapports + +Ce document décrit les principes de base utilisés sur l'outil de reporting de l'application. + +Les rapports sont utilisables depuis l'assistant **Tableau de synthèse**. + +## De quoi est composé un rapport ? + +Pour décrire un rapport, quatre notions sont à comprendre : + +* les méta-données +* les variables *(1)* +* les variables de répétition *(1)* +* les requêtes *(1)* +* les opérations *(1)* + +*(1)* On peut avoir plusieurs données de ce type pour un même rapport, l'ordre importe, la syntaxe utilise +alors un incrément (qui commence à **1**) pour refléter cet ordre. + +### Les méta-données + +Les méta-données permettent de décrire le domaine métier, le nom, description et les en-têtes du rapport. + +### Les variables + +Une variable **[optionnelle]** permet à l'utilisateur de pouvoir choisir un discriminant sur le rapport parmi un +ensemble de valeurs (son *univers*); concrêtement cela va ajouter une liste déroulante dans l'interface graphique, +l'utilisateur devra alors choisir une *valeur* parmi l'univers calculé via sa définition. + +Depuis la *v9*, les variables peuvent être interdépendantes, ce qui a pour bénéfice de limiter les résultats d'un rapport +à des données réellement utilisées sur la source de données et de ne plus proposer des tuples de variables qui ne +produisent pas de résultats (*faux positifs*). + +**À noter que pour exécuter le rapport, toutes les variables doivent être renseignées dans l'interface graphique.** + +### Les variables de répetition + +Un variable de répétition **[optionnelle]** permet de définir un ensemble de valeurs qui pourront ensuite être utilisées +dans un requête comme discriminant, i.e que la requête sera jouée pour chacune des valeurs de la variable de répétition. + +Depuis la *v9*, les variables de répétitions peuvent utilisées les variables, mais aussi d'autres variables de répétition. + +**À noter que les variables de répétition ne sont calculées que lorsque le rapport va être executé (donc une fois toutes +les variables renseignées par l'utilisateur).** + +### Les requêtes + +Un requête **[optionnelle]** permet de définir une partie du tableau final du rapport. Bien qu'optionnel, dans la pratique +chacun des rapports embarqués par l'application en défini au moins une; on pourrait cependant définir un rapport qui +n'utilise pas de requête mais uniquement des opérations... + +Plusieurs requêtes peuvent être chaînées. + +### Les opérations + +Une opération **[optionnelle]** permet de définir une action à réaliser une fois que toutes les requêtes du rapport +ont été jouées sur le tableau de résultat alors produit. Par exemple, effectuer des totaux par colonne ou lignes. + +Un opération exécute un code *Java* sur le résultat pour en produire un nouveau. + +Plusieurs opérations peuvent être chaînées. + +### Ordre de description + +Comme dit plus haut, l'ordre de description des différents éléments d'un rapport est important : + + * L'ordre de description des variables permet d'ordonner leur affichage, mais aussi pour le calcul de leur univers dans le cas de variable interdépendantes + * Idem pour les variables de répétition + * L'ordre des requêtes ainsi que les opérations à joueur est tout aussi important pour produire le résultat voulu + +## Autres notions à prendre en considération avant d'apprendre à écrire un rapport + +Plusieurs autres points sont à préciser avant de se lancer dans l'écriture d'un rapport : + + * le type de données sur lequel porte le rapport + * la technologie utilisée pour exprimer les requêtes + +### Type de données (variable *tripId*) + +Le type de données de base pour un rapport est la marée, tout rapport (selon son type de modèle) se réfère donc à la +marée de son modèle métier (*Senne*, ou *Palangre*). + +Un variable spéciale nommée **tripId** est utilisable dans la définition des variables, requêtes, opérations et reflète +les identifiants des marées sélectionnées par l'utilisateur dans l'assistant. + +**Ce nom de variable est *protégé* et ne peut donc pas être utilisé pour définir une variable ou variable de répétition.** + +### Technologie utilisée pour exprimer les requêtes + +Nous utilisons le **hql** pour décrire toute requête d'un rapport. Il s'agit d'un language de requetage propre à +Hibernate (librairie *ORM* de persitence surlequel nous nous appuyons). + +Cela nous apporte les bénéfices suivants : + + * pouvoir créer des objets java à partir d'une requête + * effectuer des jointures et remplir plus facilement les objets crées + * *Hibernate* et donc le *hql* ne dépendent pas de la source de données cible (i.e du type de base cible (*H2*, *Posgresql*)) + +Cependant cela a aussi des désavantages : + + * les requêtes ne sont pas effectuées sur le modèle physique (*sql*) et donc cela oblige à connaitre le modèle objet Java associé à la couche de persistence + * la syntaxe *sql* permet de faire des choses qu'Hibernate ne sait pas faire (par exemple les *UNION*) avant la version *6*. + * la syntaxe *sql* est connue de tous, *hql* uniquement dans le monde *Java*... + +Ce choix pourrait être remis en question en *v10* pour utiliser directement du *sql*, mais pour ce faire, il faudra +avoir toutes les solutions techniques de remplacement. + +## Où sont les rapports embarqués par l'application ? + +L'application embarque un certain nombre de rapport décrits dans un fichier de type *properties*. + +La syntaxe a été uniformisée en version 9. + +Pour le moment, tous les rapports sont regroupés dans un seul fichier situé dans le répertoire des resources de la +version applicative, à savoir dans + +```.observe/resources-${project.version}/report/observe-reports.properties``` + +Dans la configuration de l'assistant, par défaut on utilise ce fichier. + +Il est envisagé en *v10* de faire évoluer cela pour que chaque rapport puisse être décrit dans un fichier séparé. + +Cela aura pour avantage : + + * de pouvoir rajouter des rapports sans à avoir à modifier le fichier des rapports embarqués par l'application. + * de simplifier l'écriture de ceux-ci (on pourra alors supprimer tous les préfixes actuellement utilisés pour identifier un rapport). + * de pouvoir organiser ces rapports par modèle métier, ou par type d'organisation + +## Description du fonctionnement général d'un rapport + +### Prération des variables + +Si un rapport contient des variables, il faut alors dans un premier temps calculer leurs univers de valeurs et présenter +à l'utilisateur ces univers pour qu'il puisse sélectionner **pour chaque variable**, une valeur qui sera ensuite +utilisée pour exécuter le rapport (ou calculer l'univers d'autres variables...). + +Si de plus il existe des variables interdépendantes, les variables qui ont des dépendances sur d'autres variables ne +sont pas accéssibles tant que **toutes** ses dépendances ne sont pas renseignées. + +Une fois toutes les variables renseignées, le rapport est exécuté. + +**À noter que dès que l'utilisateur modifie la valeur d'une variable, le rapport va être de nouveau exécuté. +S'il s'agit d'une variable utilisée par d'autres variables, alors on recalcule l'univers de ces variables, que +l'utilisateur devra alors re-sélectionné parmi le nouvel univers calculé). Le rapport sera alors exécuté de nouveau une +fois toutes les variables renseignées.** + +### Exécution d'un rapport + +L'exécution d'un rapport se fait en trois étapes (elles ne sont pas obligatoires selon la définition du rapport) : + + 1. calcul des variables de répétition (si le rapport en possède) + 2. exécution des requêtes du rapport pour construire le résultat final (si le rapport en possède) + 3. exécution des opérations du rapport (si le rapport en possède) sur le résultat produit à l'étape précédente + +Une fois ces trois étapes exécutées, le résultat obtenu est restitué à l'utilisateur dans un tableau. + +## Pour aller plus loin + +Une fois ces principes de base assimilés, vous pouvez aller voir + +- [la documentation de la syntaxe d'un rapport](./syntax.html) ===================================== src/site/markdown/report/syntax.md ===================================== @@ -0,0 +1,324 @@ +# Documentation de la syntaxe d'un rapport + +Ce document décrit comment écrire un rapport. + +## Syntaxe d'un rapport + +Comme écrit dans la page de présentation des rapports, ceux-ci sont décrits dans un fichier de type *properties*. + +La syntaxe a été uniformisée en version 9. + +### Identifiant d'un rapport + +Chaque rapport possède un identifiant unique; celui-ci est utilisé pour identifier toute sa description dans le fichier global. + +Voici un premier exemple de rapport pour mieux comprendre comment cela s'organise : + +```properties +report.llCommonTripGearUseFeatures.modelType=LL +report.llCommonTripGearUseFeatures.name=Liste des équipements +report.llCommonTripGearUseFeatures.description=Afficher les équipements +report.llCommonTripGearUseFeatures.columns=Equipement,Nombre,Utilisé dans la marée,Mesures +report.llCommonTripGearUseFeatures.repeatVariable.1.name=gearUseFeaturesId +report.llCommonTripGearUseFeatures.repeatVariable.1.type=java.lang.String +report.llCommonTripGearUseFeatures.repeatVariable.1.request=Select g.id \ +From fr.ird.observe.entities.data.ll.common.TripImpl m \ +Join m.gearUseFeatures g \ +Where \ +m.id In :tripId \ +and g in elements (m.gearUseFeatures) \ +Order By g.gear.label2 +report.llCommonTripGearUseFeatures.request.1.location=0,0 +report.llCommonTripGearUseFeatures.request.1.layout=row +report.llCommonTripGearUseFeatures.request.1.request=Select \ +concat(CASE When g.gear.code IS NULL Then 'Aucun code' Else g.gear.code End, ' - ', g.gear.label2), \ +g.number, \ +( CASE g.usedInTrip When true Then 'Oui' Else Case g.usedInTrip When false Then 'Non' Else 'Indéterminé' End End )\ +From fr.ird.observe.entities.data.ll.common.GearUseFeaturesImpl g \ +Where g.id = :gearUseFeaturesId +report.llCommonTripGearUseFeatures.request.1.repeat.name=gearUseFeaturesId +report.llCommonTripGearUseFeatures.request.1.repeat.layout=column +report.llCommonTripGearUseFeatures.operations.1.type=ComputeMeasurementsLongline +``` + +Ici l'identifiant du rapport est ```llCommonTripGearUseFeatures```. + +Par convention, on utilise le domaine métier **ll**, suivi du sous-domaine métier **Common**, puis enfin un suffixe qui +exprime ce que le rapport doit produire **TripGearUseFeatures**. + +Dans le fichier global, toutes les entrées commençants par **report.llCommonTripGearUseFeatures** permettent alors de +décrire le rapport. + +### Méta-données d'un rapport + +Il existe cinq méta-données pour un rapport (dont trois sont obligatoires) : + +```properties +report.xxx.modelType=PS ou LL +report.xxx.name=Nom du rapport +report.xxx.description=Description du rapport +report.xxx.columns=En-têtes des colonnes du rapport (séparées par des virgules) [Optionnel] +report.xxx.rows=En-têtes des lignes du rapport (séparées par des virgules) [Optionnel] +``` + +```report.xxx.modelType``` permet de définir le domaine métier sur lequel porte le rapport, valeurs possibles : + +* **PS** pour le domaine *Senne* +* **LL** pour le domaine *Palangre*. + +En *V10*, on ajoutera certainement **COMMON** pour le domaine métier des marées agnostiques. + +```report.xxx.name``` permet de définir le nom du rapport, ce texte est celui affiché dans la liste déroulante des +rapports à sélectionner dans l'assistant. + +```report.xxx.description``` permet de définir une description longue d'un rapport, ce texte est celui affiché +comme description lorsqu'un rapport est sélectionné dans l'assistant. + +```report.xxx.colomns``` **[Optionnel]** permet de définir les en-têtes de colonnes de manière fixe. + +```report.xxx.rows``` **[Optionnel]** permet de définir les en-têtes de lignes de manière fixe. + +Il est possible de ne pas les indiquer si le rapport n'a pas d'en-têtes de colonnes ou de lignes fixes; Ces en-têtes +seront alors définies via les requêtes du rapport. + +### Variables d'un rapport + +Dans notre premier exemple, il n'y avait pas de variable (mais des variables de répétition). La syntaxe de ces deux +notions est exactement la même, au détail près qu'une variable est préfixée par ```variable``` alors qu'une variable de +répétition est préfixée par ```repeatVariable```. + +Comme indiqué dans le préambule, l'ordre de description des variables importe, cet ordre sera utilisé pour : + +* afficher les variables dans l'interface graphique, +* effectuer le calcul de l'univers des variables (dans le cas où des variables sont inter-dépendantes). + +**À noter que l'outil de rapport utilise uniquement l'ordre induit dans la description du rapport, si par exemple la +première variable était dépendante de la seconde, alors le rapport ne pourra jamais être exécuté puisque la première +variable attend que la seconde soit remplie...** + +Pour décrire une variable trois lignes sont nécessaires, comme on peut le voir dans l'exemple suivant : + +```properties +report.xxx.variable.1.name=speciesGroup +report.xxx.variable.1.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference +report.xxx.variable.1.request=Select distinct sg \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set c \ +Join c.catches ca with ca.totalCount Is Not Null Or ca.catchWeight Is Not Null \ +Join ca.species e \ +Join e.speciesGroup sg \ +Where t.id In :tripId \ +Order By sg.code +``` + +```report.xxx.variable.1.name``` définit l'*alias* de la variable que l'on pourra ensuite utiliser dans le +reste de la définition du rapport (par exemple dans d'autres variables, variables de répétition, requêtes ou opérations).. + +```report.xxx.variable.1.type``` définit le type de la variable. Ce type doit être un type de *dto* ou une +*référence de dto*. On ne peut pas ici utiliser un type d'*entité*, puisque l'interface graphique (selon le principe de +séparation des couches) n'a pas connaissance du modèle des entités. + +Techniquement, chaque type d'entité possède son type de *dto* et chaque type de *dto* possède un type de *référence*. + +La notion de référence est utilisée dans l'application partout où l'on utilise des listes déroulantes, mais aussi dans +l'arbre de navigation; la notion de *dto* étant utilisée au niveau d'un formulaire. + +À partir d'un type de référence, l'application est capable d'en déduire : + +* le nom de la donnée à afficher +* comment décorer la donnée +* comment transformer l'entité + +```report.xxx.variable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de +la variable. + +Il est possible de documenter cette variable en utilise une quatrième ligne optionnelle : + +```properties +report.xxx.variable.1.comment=Un commentaire optionnel pour documenter la variable +``` + +**À noter que l'utilisation d'une variable dans le reste du rapport se fait toujours via son identifiant technique +(*topiaId*), ce qui ne sera pas le cas d'une variable de répétition qui elle utilisera toujours le type décrit.** + +**À noter aussi que l'on peut utiliser pour décrire une variable, de la variable spéciale *tripId* qui reflète la +sélection des marées sur lequel on veut appliquer le rapport**.. + +Voici un second exemple de deux variables dont la seconde utilise la première : + +```properties +report.xxx.variable.1.name=discardMode +report.xxx.variable.1.type=fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto +report.xxx.variable.1.request=Select distinct new fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto(sf.discard) \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set c \ +Join c.catches ca with ca.totalCount Is Not Null \ +Join ca.speciesFate sf \ +Where t.id In :tripId \ +Order By sf.discard +report.xxx.variable.2.name=speciesGroup +report.xxx.variable.2.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference +report.xxx.variable.2.request=Select distinct sg \ +From TripImpl t \ +Join t.routeObs r \ +Join r.activity a \ +Join a.set c \ +Join c.catches ca with ca.totalCount Is Not Null \ +Join ca.speciesFate sf with sf.discard = :discardMode \ +Join ca.species e \ +Join e.speciesGroup sg \ +Where t.id In :tripId \ +Order By sg.code +``` + +Cet exemple est intéressant car il nous permet de voir comment utiliser un type qui ne reflète pas exactement une entité. + +Ici **SpeciesFateDiscardModeDto** est un objet que l'on a ajouté dans le code de l'application pour refléter les différents modes de captures : +* conservé (sf.discard = ```false```) +* rejeté (sf.discard = ```true```) +* non connu (sf.discard = ```NULL```) + +### Variables de répétition d'un rapport + +Comme indiqué plus haut, la syntaxe d'une variable de répétition est identique à celle d'une simple variable. + +Pour décrire une variable de répétition, trois lignes sont nécessaires, comme on peut le voir dans l'exemple suivant : + +```properties +report.xxx.repeatVariable.1.name=gearUseFeaturesId +report.xxx.repeatVariable.1.type=java.lang.String +report.xxx.repeatVariable.1.request=Select g.id \ +From fr.ird.observe.entities.data.ll.common.TripImpl m \ +Join m.gearUseFeatures g \ +Where \ +m.id In :tripId \ +and g in elements (m.gearUseFeatures) \ +Order By g.gear.label2 +``` + +```report.xxx.repeatVariable.1.name``` définit l'*alias* de la variable de répétition à utiliser dans une requête, autre variable de répétition ou opération + +```report.xxx.repeatVariable.1.type``` définit le type de la variable de répétition. Contrairement aux variables, les +variables de répétition sont utilisées en interne pour exécuter le rapport, on peut donc utiliser directement des types d'*entité*, +ou bien des types *simples* qui correspondent aux types d'une colonne en base (**java.lang.String**, **java.lang.Float**, ...) + +**À noter que contrairement aux variables, ici le type de la donnée sera toujours utilisé tel quel dans les autres requêtes : +si on définit une variable de type *entité*, c'est bien l'entité qui sera injectée dans la requête *hql*, et non pas juste son identifiant technique.** + +```report.xxx.repeatVariable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de la variable de répétition + +Il est possible d'utiliser dans une requête de variable de répétition, un alias sur toute variable du rapport (dont la +variable spéciale **tripId**), ainsi que tout autre alias de variable de répétition. + +**À noter que l'outil de rapport utilise uniquement l'ordre induit dans la description du rapport, si par exemple la +première variable de répétition était dépendante de la seconde, alors le rapport ne pourra jamais être exécuté puisque la +première variable attend que l'univers de la seconde soit calculée...** + +On peut aussi ajouter une ligne supplémentaire pour indiquer que l'on veut rajouter la valeur **nulle** dans +l'univers de cette variable de répétion, ce qui peut etre utilise (et nous nous en servons), mais que nous ne pouvons +pas décrire via la requete *hql. + +```properties +report.xxx.repeatVariable.1.addNull=true +``` + +Il est possible de documenter cette variable de répétition en utilisant une ligne optionnelle : + +```properties +report.xxx.repeatVariable.1.comment=Un commentaire optionnel pour documenter la variable de répétition +``` + +### requêtes d'un rapport + +On distingue deux types de requêtes : + +* des requêtes *simples* +* des requêtes utilisant une variable de répétition (pour celles-ci on doit décrire en plus alors la variable de répétition à utiliser) + +Les deux types de requêtes nécessitent les trois lignes, comme décrit dans l'exemple suivant : + +```properties +report.xxx.request.1.location=0,0 +report.xxx.request.1.layout=row +report.xxx.request.1.request=Select \ +concat(CASE When g.gear.code IS NULL Then 'Aucun code' Else g.gear.code End, ' - ', g.gear.label2), \ +g.number, \ +( CASE g.usedInTrip When true Then 'Oui' Else Case g.usedInTrip When false Then 'Non' Else 'Indéterminé' End End )\ +From fr.ird.observe.entities.data.ll.common.GearUseFeaturesImpl g \ +Where g.id = :gearUseFeaturesId +``` + +```report.xxx.request.1.location``` définit la position dans le résultat final où positionner le résultat de cette requête. + +```report.xxx.request.1.layout``` définit la disposition à utiliser pour placer le résultat de cette requête dans le résultat final. Deux valeurs sont possibles : + +* **row** pour signifier que le résultat de la requête sera positionné en ligne à partir de la position précedemment définie. Ce mode correspond exactement au resultat de la requête. +* **column** pour signifier que le résultat de la requête sera positionné en colonne à partir de la position précedemment définie. Ce mode est une transposition du résultat de la requête : une ligne du résultat de la requête sera une colonne dans le résultat final + +```report.xxx.request.1.request``` définit le code **hql** qui permet de construire le résultat à placer ensuite dans le résultat final du rapport + +Pour une requête avec variable de répétition, il faut alors ajouter les deux lignes suivantes : + +```properties +report.xxx.request.1.repeat.name=gearUseFeaturesId +report.xxx.request.1.repeat.layout=column +``` + +```report.xxx.request.1.repeat.name``` définit l'*alias* de la variable de répétition à utiliser. La requête sera exécutée +autant de fois qu'il y a de valeurs dans l'univers calculé de la variable de répétition. + +**À noter qu'il faut alors que le corps de cette requête doit utiliser l'alias de cette variable de répétition, même si dans les faits, rien ne l'oblige, mais le résultat sera alors toujours le même...** + +```report.xxx.request.1.repeat.layout``` définit la disposition à utiliser pour constuire le résultat final de la requête appliqué à chaque valeur de la variable de répétition. Deux valeurs sont possibles : + +* **row** pour signifier que pour chaque valeur de l'univers de la variable de répétition, le résultat de la requête sera positionné sur la même ligne; +* **column** pour signifier que pour chaque valeur de l'univers de la variable de répétition, le résultat de la requête sera positionné sur la même colonne. + +**À noter qu'aucune vérification n'est effectuée sur la cohérence entre la disposition de la requête et la disposition +de la variable de répétition. On peut alors obtenir un résultat final de la requête incohérent si les dispositions ne sont pas compatibles.** + +Il est possible de documenter cette requête en utilisant une ligne optionnelle : + +```properties +report.xxx.request.1.comment=Un commentaire optionnel pour documenter la requête +``` + +### Opérations d'un rapport + +On distingue deux types d'opérations : + +* celles sans paramétrage (une seule ligne est alors nécessaire) +* celles savec paramétrage (dans ce cas deux lignes sont nécessaires pour la décrire). + +Les deux types d'opération nécessitent une première ligne pour déclarer le type d'opération à exécuter, comme décrit +dans l'exemple suivant : + +```properties +report.xxx.operations.1.type=SumIntRow +``` + +```report.xxx.operations.1.type``` définit le type d'opération à réaliser. + +Dans le cas où l'opération est paramétrable, on doit alors ajouter une autre ligne avec le paramétrage de l'opération : + +```properties +report.xxx.operations.1.parameters=0|1 +``` + +```report.xxx.operations.1.parameters``` définit le paramétrage à utiliser pour exécuter l'opération. + +Il est possible de documenter cette opération en utilisant une ligne optionnelle : + +```properties +report.xxx.operations.1.comment=Un commentaire optionnel pour documenter l'opération +``` + +Les opérations disponibles et leur documentation sont décrites dans le document [suivant](./embedded-operations.html). + +## Pour aller plus loin + +Vous pouvez aussi consulter la [documentation des rapports embarqués par l'application](./embedded-reports.html). ===================================== src/site/site_fr.xml ===================================== @@ -86,6 +86,11 @@ <item name="Configuration (fichier d'exemple)" target="_blank" href="./observe-client.conf"/> <item name="Filtrage des référentiels" href="./referential-filter.html"/> <item name="Synchronisation référentiel avancée" href="./synchro-referential.html"/> + <item name="Outil de reporting" href="./report/index.html"> + <item name="Syntaxe d'un rapport" href="./report/syntax.html"/> + <item name="Opérations disponibles pour un rapport" href="./report/embedded-operations.html"/> + <item name="Rapports embarqués dans l'application" href="./report/embedded-reports.html"/> + </item> </item> <item name="Server"> <item name="Administration Web v9" href="server-configuration-application.html"/> ===================================== toolkit/api-report/src/main/java/fr/ird/observe/report/operations/GroupByLength.java deleted ===================================== @@ -1,72 +0,0 @@ -package fr.ird.observe.report.operations; - -/*- - * #%L - * ObServe Toolkit :: API :: Report - * %% - * Copyright (C) 2008 - 2023 IRD, Ultreia.io - * %% - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this program. If not, see - * <http://www.gnu.org/licenses/gpl-3.0.html>. - * #L% - */ - -import com.google.auto.service.AutoService; -import fr.ird.observe.report.Report; -import fr.ird.observe.report.ReportOperationConsumer; -import fr.ird.observe.report.ReportRequestExecutor; -import io.ultreia.java4all.util.matrix.DataMatrix; - -import java.util.HashSet; -import java.util.LinkedHashMap; -import java.util.Map; -import java.util.Set; -import java.util.concurrent.atomic.AtomicInteger; - -/** - * Created on 21/09/2021. - * - * @author Tony Chemit - dev@tchemit.fr - * @since 5.0.44 - */ -@AutoService(ReportOperationConsumer.class) -public class GroupByLength implements ReportOperationConsumer { - - @Override - public DataMatrix consume(String parameters, ReportRequestExecutor requestExecutor, Report report, Set<String> tripId, DataMatrix incoming) { - // Première passe pour grouper par classe de taille - Map<String, AtomicInteger> data = new LinkedHashMap<>(); - for (int row = 0, nbRows = incoming.getHeight(); row < nbRows; row++) { - String length = (String) incoming.getValue(0, row); - int count = Integer.parseInt(incoming.getValue(1, row).toString()); - AtomicInteger mutableInt = data.computeIfAbsent(length, k -> new AtomicInteger()); - mutableInt.addAndGet(count); - } - // Deuxième passe pour remplir la matrice - Set<String> lengths = new HashSet<>(); - for (int row = 0; row < incoming.getHeight(); row++) { - lengths.add((String) incoming.getValue(0, row)); - } - DataMatrix result = createTmpMatrix(0, incoming.getHeight(), incoming.getWidth(), lengths.size()); - int row = 0; - for (Map.Entry<String, AtomicInteger> entry : data.entrySet()) { - String length = entry.getKey(); - AtomicInteger mutableInt = entry.getValue(); - result.setValue(0, row, length); - result.setValue(1, row, mutableInt.intValue()); - row++; - } - return result; - } -} ===================================== toolkit/api-report/src/main/java/fr/ird/observe/report/operations/SumFloatColumn.java deleted ===================================== @@ -1,72 +0,0 @@ -package fr.ird.observe.report.operations; - -/*- - * #%L - * ObServe Toolkit :: API :: Report - * %% - * Copyright (C) 2008 - 2023 IRD, Ultreia.io - * %% - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this program. If not, see - * <http://www.gnu.org/licenses/gpl-3.0.html>. - * #L% - */ - -import com.google.auto.service.AutoService; -import fr.ird.observe.report.ReportOperationConsumer; -import io.ultreia.java4all.util.matrix.DataMatrix; -import org.apache.logging.log4j.LogManager; -import org.apache.logging.log4j.Logger; - -import java.io.Serializable; - -/** - * Created on 21/09/2021. - * - * @author Tony Chemit - dev@tchemit.fr - * @since 5.0.44 - */ -@AutoService(ReportOperationConsumer.class) -public class SumFloatColumn extends SumColumn implements ReportOperationConsumer { - private static final Logger log = LogManager.getLogger(SumFloatColumn.class); - - @Override - protected Object getSumColumn(int column, int x, DataMatrix incoming) { - double result = 0d; - int nbRows = incoming.getHeight(); - for (int row = 0; row < nbRows; row++) { - Serializable o = incoming.getValue(column, row); - if (o == null || "null".equals(o)) { - o = 0; - } - try { - Integer.valueOf(o.toString()); - // real int, don't want it - return "-"; - - } catch (NumberFormatException ignored) { - } - double d; - try { - d = Double.parseDouble(o.toString()); - } catch (NumberFormatException e) { - // une des données de la colonne n'est pas un count on sort directement - log.debug(String.format("Could not convert %s to number", o), e); - return "-"; - } - result += d; - } - // FIXME Should we serve a float ? - return (int) result; - } -} View it on GitLab: https://gitlab.com/ultreiaio/ird-observe/-/compare/7ae50f72aac66fd8ed04c10df... -- View it on GitLab: https://gitlab.com/ultreiaio/ird-observe/-/compare/7ae50f72aac66fd8ed04c10df... You're receiving this email because of your account on gitlab.com.