Commentaire sur la fiche : Routes du logiciel BDF

Si la réponse à cette question ne vous parait pas claire ou si elle vous semble obsolète, n’hésitez pas à nous en faire part.

Et nous sommes preneurs également de toute correction de faute d’orthographe ou de grammaire...

Rappel du texte de la fiche :

Principe général

Les applications inspirées des API Rest ont habitué à des URLs fortemement arborescentes (par exemple, /event/1/edit). Ce n’est pas le choix de conception du logiciel BDF. Ce dernier propose deux grandes familles d’URLs :

1) Les domaines d’action : ce sont toutes les URLs d’un seul tenant sans arborescence, (par exemple /session ou /edition) ; ce sont les URLs qui vont notamment gérer toutes les commandes ainsi que l’affichage des formulaires de l’interface ; ces domaines sont accompagnés de nombreux paramètres sous la forme classique ?param1=value1&param2=value2 (s’il s’agit d’une requête GET)
2) Les contenus qui peuvent être dynamiques (générées à la volée par le logiciel) ou statiques (ils sont appelés par ailleurs « ressources ») : leurs URLs est arborescentes et le premier niveau indique le type du contenu (Par exemple, l’URL d’une fiche est /fiches/suivi-3.html, le premier niveau /fiches/ indique que c’est un contenu de type fiches) ; les règles qui régissent la construction de ces URLs dépendent du type de contenu.

Un autre choix du conception du logiciel BDF, c’est que bien que s’appuyant sur le logiciel Tomcat, le routage n’est pas effectué par WEB-INF/web.xml. De fait, ce fichier ne fait appel qu’à une seule servlet : fr.exemole.bdfserver.servlets.BDFServlet, c’est d’ailleurs la seule de tout le logiciel (et BDF n’utilise à aucun moment le langage JSP). C’est cette servlet qui fait le travail de routage en s’appuyant notamment sur les méthodes statiques de fr.exemole.bdfserver.servlets.BDFRoutes.

En se plongeant dans le code, on verra que le routage est compliqué par le fait que BDF peut être utilisé en deux modes : avec une seule fichothèque ou avec des fichothèques multiples. Dans le cas de fichothèques multiples, il y a un niveau supplémentaire avec le nom de la fichothèque et des domaines spécifiques à la gestion des fichothèques multiples (commençant par /multi-*). Dans la présente fiche, on ne s’intéresse qu’au routage d’une fichothèque particulière.

Dernière remarque au passage sur la conception du logiciel, BDF ne s’appuie pas sur les types de requête (GET, POST, PUT, etc.), seules les requêtes GET et POST sont traitées et elles sont pratiquement interchangeables.

Les domaines

La liste des domaines est définie dans l’interface fr.exemole.bdfserver.api.interaction.Domains : on peut les séparer en deux familles : les domaines communs et les domaines spéciaux.

Les domaines communs

Les domaines communs fonctionnent tous le même manière. Le paramètre le plus répandu est cmd pour « Commande » : sa présence indique que le logiciel doit réaliser une action, la plupart du temps, une modification des données mais cela peut être aussi l’envoi d’un courriel. Chaque commande nécessite ses propres paramètres.

Un des paramètres suivants est presque toujours présent pour indiquer l’affichage en retour de l’action demandée :

page quand il s’agit de servir une page HTML,
json quand il s’agit de servir du JSON,
stream quand il s’agit de tout autre type de contenu.

Dans certains cas particuliers, on pourra trouver une URL avec un tiret comme /administration-resources : il s’agit d’une notation raccourcie du paramètre page, notre exemple est équivalent à /administration?page=resources.

On pourra partir du code de fr.exemole.bdfserver.servlets.instructions.DomainInstruction pour se plonger dans le traitement de ces domaines et dans fr.exemole.bdfserver.commands.CoreBdfCommandProvider pour la partie « Construction d’une commande ».

Les domaines communs sont les suivants, chacun correspond à une des grandes fonctions de l’interface :

/addenda: Gestion des addenda et des documents
/album: Gestion des albums et des illustrations
/administration: Opérations d’administration particulières (par exemple, la sauvegarde
/configuration: Configuration globale de la fichothèque
/corpus: Gestion des corpus
/edition: Édition des fiches
/exportation: Exportation des données (par exemple, sous forme de fichier ODS)
/ext-*: Cas particulier, /ext- est un suffixe pour désigner le domaine d’une extension (par exemple : /ext-scarabe) ; pour le reste le comportement est le même que les autres domaines
/importation: Importation de données (notamment, la saisie en masse)
/mailing: Envoi par courriel des fiches
/main: Affichage de l’interface principale
/misc: Commandes diverses
/pioche: Interrogation des données (notamment, pour l’insertion dans un formulaire)
/selection: Sélection de fiches
/sphere: Gestion des sphères et des personnes
/thesaurus: Gestion des thésaurus et mots-clés

Les domaines spécifiques

Ces domaines ont leur propre traitement particulier.

/app-*: Ce domaine ne vient jamais seul mais accompagné du nom d’une mini-application séparé par un tiret (exemple : /app-tableaudebord) ; c’est en fait l’URL d’accès à la mini-application
/run: Lancement de certains traitements, notamment ceux issus de fichiers
/session: Domaine gérant la connexion à une fichothèque

Les contenus

Les URLs de contenu sont traité par la classe fr.exemole.bdfserver.get.GetInstructionFactory assistée par la classe fr.exemole.bdfserver.get.instructions.StreamInstruction. Le premier niveau de l’arborescence de l’URL indique le type du contenu. On distingue les contenus dynamiques des ressources :

Contenu dynamique

/admin/: Contenu dynamique lié à l’administration (par exemple, le fichier récapitulatif au format ODS des rôles)
/balayagecontents/: Fichiers de définition des balayages (alias balayage/)
/balayages/: Récupération du résultat d’un balayage pour un élément donné (peu utilisé)
/diagrams/: Diagrammes UML de la structure de la fichothèque
/documents/: Accès par id ou par nom aux documents des addendas
/dyn/: Divers contenus générés dynamiquement (par exemple, le fichier XML des libellés d’un corpus)
/dyn-pub/: Contenus générés dynamiquement et publics (par exemple, l’icone 32 pixels de la fichothèque)
/ext/: Accès aux extensions
/fiches/: Accès aux fiches
/illustrations/: Accès aux images des albums
/inc/: Fichiers à inclure lors d’un balayage
/motcles/: Accès aux mots-clés (alias motscles/)
/output/: Résultats de génération de fichiers (sauvegarde, export SQL, etc.)
/pub/: Contenu du répertoire des fichiers publics
/tableexport/: Fichiers de définition des exportations tabulaires
/tables/: Résultat des exportations tabulaires
/transformations/: Fichiers de définition des gabarits de transformation (alias transformation/)
/users/: Accès aux rédacteurs (alias redacteurs/)
/xml-pack/: Empaquetage de ressources dans un format XML pour sa récupération en XSLT (par exemple, l’insertion de fichiers CSS)

Les ressources

Tout premier niveau autre que ceux listés dans les contenus dynamique est résolu en regardant son existence comme premier niveau dans les ressources statiques. Les premiers niveaux par défaut dans la distribution sont les suivants :

/css/: CSS associés aux résultats des transformations (par exemple, CSS d’une fiche)
/custom/: Fichiers de personnalisation (vides par défaut)
/ext-rsc/: Ressources des extensions
images/: Images statiques (par exemple, le logo)
/js/: Fichiers Javascript
/l10n/: Fichiers de localisation
/templates/: Gabarits HTML au format JSRender
/theme/: Thème de l’interface (CSS et icones)
/third-lib/: Bibliothèques Javascript tierce
/xml/: Fichiers XML (par exemple, le mémento)
/xslt/: Fichiers XSLT utilisés par les transformations