Configuration resolver - Configuration/extensions

Owned by Joël DRIGO
Last updated: Nov 06, 2023
7 min read

Overview

Ce document ne concerne que la configuration des extensions d'éléments de configuration :

  • mappings

  • base locations (emplacements des fichiers de configuration de base (ou produit))

  • configuration location (emplacements des fichiers de configuration projet)

  • processeurs (composants permettant de déterminer un emplacement en fonction du contexte de connexion)

Il y a deux façons de configurer chacun de ces éléments :

  • par la configuration du plugin “config resolver”. On parle de config settings.

  • par contribution, c’est-à-dire par des configurations situés dans des plugins (dit de contribution (sous-entendu contribution à la configuration du “config resolver”). On parle aussi d’external config settings.

Les config settings sont dit forts, c’est-à-dire prioritaire sur les contributions. Si un élément est configuré dans les config settings, mais également dans un plugin, les “config settings” seront prépondérants. Dans certains cas l'élément de contribution sera considéré comme doublon et donc ignoré. Dans d’autres cas, il sera “fusionné” avec ce qui configuré dans les config settings (un peu comme si les config settings étaient une redéfinition des contributions).

Plugin de contribution

Un plugin peut contribuer à la configuration du config resolver :

  • s’il est activé ;

  • si ce n’est

    • ni le plugin “config resolver” lui-même ;

    • ni le default holding plugin (plugin configuré dans la configuration du plugin par le paramètre default_holding_plugin) ;

  • s’il n’est pas exclu par le paramètre discover_external_config_settings_exclusion ;

  • si la contribution est activée (paramètre discover_external_config_settings à true)

  • s’il contient un élément nécessaire pour qu’il soit reconnu comme plugin de contribution

  • si l'élément de contribution n’est pas considéré comme doublon d’un élément déjà configuré dans les config settings.

Chargement, démarrage, initialisation, prise en compte, etc

Dans tous les cas, la détection, le chargement, l’initialisation, le démarrage, de n’importe quel élément configuré est fait au démarrage du plugin “config resolver”. Il n’y a pas de rechargement à chaud.

Si un élément de contribution est modifié après le démarrage du “config resolver”, il est nécessaire de redémarrer ce dernier pour en tenir compte.

Plugin de configuration par défaut

Par défaut, on considère que le plugin de configuration est un plugin de même nom que le plugin config resolver auquel on ajoute “_CONFIG” (donc par défaut WXM_CONFIG_RESOLVER_CONFIG” : si ce plugin n’existe pas ou n’est pas activé, on utilise le plugin WXM_CONFIG_RESOLVER lui-même. Pour indiquer un autre plugin, on utilise le paramètre de plugin defaultHoldingPlugin. Le plugin ainsi désigné est le plugin par défaut pour les fichiers de configuration projet (stockés dans res/config_resolver/configs) et les bases (stockées dans config/config_resolver/bases).

Configuration des mappings

Overview

Un mapping est l’association d’un identifiant et d’un chemin de configuration.

Le chemin de configuration détermine les différentes couches de configuration (layer) qui vont être fusionnées pour obtenir la configuration final correspondant à cet identifiant. Il s’agit d’un nom de dossier et donc ne doit pas contenir de caractères invalides pour un chemin de fichier.

Un chemin est constitué de plusieurs parties séparées par des arobas (@). Lors de la construction de la configuration, on considèrera chaque partie pour construire un chemin physique en prenant successivement la première partie, puis les deux premières parties, puis les trois premières est ainsi de suite. Par exemple exemple@exemple1@exemple2 donnera les chemins physiques suivants : exemple, puis exemple@exemple1, puis exemple@exemple1@exemple2.

Une partie de ce chemin peut être :

  • statique : une valeur fixe

  • dynamique : l’identifiant d’un processeur, qui déterminera la valeur fixe en fonction du contexte de connexion (le surfer, s’il est connecté ou non, ses propriétés (son rôle par exemple), les headers (pour déterminer par exemple le type de navigateur, etc)
    Dans ce cas, on fait précéder l’identifiant de processeur par le caractère deux-points (:). Par exemple, exemple@:processeur1. Ici la seconde partie du chemin sera évaluée en faisant appel au processeur d’identifiant processeur1. Par exemple, si ce processeur retourne les valeurs valeur1 et valeur2 par exemple, les chemins obtenus seront exemple@valeur1 et exemple@valeur2.

On peut indiquer une coupure dans le chemin par le caractère dollar ($). Par exemple exemple@$exemple1@exemple2. Dans ce cas, le premier dossier est toujours exemple, mais le deuxième dossier n'est pas exemple@exemple1, mais exemple1, et le troisième est exemple1@exemple2 au lieu de exemple@exemple1@exemple2.

On peut combiner identifiant de processeur et coupure : exemple@exemple1@$:processeur1@exemple2 (ou exemple@exemple1@:$processeur1@exemple2, c’est pareil). Dans ce cas, si le processeur retourne les valeurs valeur1 et valeur2, les chemins possibles seront exemple, exemple@exemple1, valeur1@exemple2 et valeur2@exemple2.

Les valeurs vides ou nulles retournées par un processeur sont ignorées. Si le chemin est exemple@:processeur1@exemple1 et que le processeur retourne "", on obtiendra exemple@exemple1.

Un processeur peut retourner un sous-chemin, lui-même donc constitué de parties statiques ou dynamiques, avec coupure ou non. Par exemple, si le chemin est exemple@:processeur et si la valeur retournée par le processeur est valeur1@:unautreprocesseur et valeur2@:unautreprocesseur, et que autreprocesseur retourne sousvaleur1 et sousvaleur2 les chemins obtenus seront exemple, exemple@valeur1, exemple@valeur2, exemple@valeur1@sousvaleur1, exemple@valeur1@sousvaleur2, exemple@valeur2@sousvaleur1, exemple@valeur2@sousvaleur2,etc.

On peut bien sûr avoir un chemin exemple@:processeur1 et processeur1 qui retourne les valeurs :processeur2 et :processeur3.

Attention avec la récursivité, aucun contrôle de boucle infinie n’est effectué et la résolution peut soit partir en boucle infinie, soit en stack overflow.

On peut voir ce que donne les différentes combinaisons avec le end point debug/path.

 

 

Config settings

On configure les mappings dans la section mappings du paramètre config_settings du plugin.

Il s’agit d’un objet JSON dont les clefs sont les identifiants et les valeurs les chemins associés.

Exemple

{ "id_of_mapping","example@of@path" }

Contribution

On peut contribuer aux mappings en mettant dans le dossier config d’un plugin de contribution un fichier JSON :

  • dont le nom est config-resolver-mappings.json

  • dont le contenu est du même format que la section mappings du paramètre config_settings du plugin

Configuration des bases

Par défaut, on considère qu’une base est dans le plugin de configuration par défaut, dans son dossier config/config_resolver/bases.

Config settings

On peut configurer d’autres emplacements de base dans la section baseLocations du paramètre config_settings du plugin.

Il s’agit d’un objet jSON dont les clefs sont les identifiants de mapping, et les valeurs :

  • un nom de plugin (une string) pour un emplacement dans config/config_resolver/bases

  • un objet avec les propriétés suivantes :

    • plugin: le nom du plugin (une string)

    • path: le chemin relatif au dossier du plugin (par exemple res/config_resolver/bases pour obtenir le même chemin que par défaut)

      Overview

Contribution

Pour configurer un emplacement dans un plugin, il suffit de placer le dossier config_resolver/bases dans l’un des dossiers suivants (dans le plugin de contribution):

  • /config

  • /res

  • / (racine du plugin)

Configuration des emplacements de configuration

Overview

Par défaut, les dossiers de configuration projet (layers) sont stockés dans le plugin de configuration par défaut, dans le dossier res/config_resolver/configs.

Cela permet d’avoir plusieurs dossiers de configuration. La prise en compte des dossiers est faite dans un ordre déterminable, indiqué ici:

  • le stockage client est toujours le dernier appliqué

  • juste avant on applique le dossier de configuration par défaut (celui du plugin de configuration par défaut)

  • avant on applique les autres dossiers de configuration qui ont un ordre configuré, dans cet ordre, du plus grand au plus petit (le plugin d’ordre 1 est appliqué après celui d’ordre 2, donc le plugin d’ordre 1 surcharge celui d’ordre 2).

  • les plugins n’ayant pas d’ordre sont appliqués en premier dans un ordre indéterminable et indéterminé

Config settings

Il est possible de déterminer un plugin de stockage de configuration spécifique via la section configLocations du paramètre config_settings du plugin "config resolver".

Il s’agit d’un tableau JSON dont les valeurs sont

  • des noms de plugins, pour une configuration automatique

  • d’objets JSON avec les propriétés suivantes:

    • plugin: un nom de plugin (obligatoire)

    • path: un chemin (relatif au dossier de plugin). Par défaut, le chemin est /res/config_resolver/configs. Le dossier indiqué doit obligatoire exister au démarrage.

    • order: un ordre de prise en compte (un entier supérieur à 0)

    • id: un identifiant permettant de référencer le dossier de configuration au lieu d'utiliser le nom de plugin (une chaine de caractères ne pouvant être un nom de plugin)

Contribution

Pour indiquer qu’un plugin contribue en tant que dossier de configuration, il suffit de mettre un dossier res/config_resolver/configs dans ce plugin.

On peut également placer dans le dossier config du plugin un fichier config-resolver-config.json.

Ce fichier est au même format que l’objet de la section configLocations du paramètre config_settings, excepté que la propriété plugin y est ignoré. Ce fichier permet de définir un chemin spécifique (si différent de res/config_resolver/configs) obligatoirement dans le plugin, un ordre ou un identifiant.

Configuration des processeurs

Overview

Les processeurs sont des composants qui déterminent une valeur en fonction du contexte de connexion. Ils permettent d’adapter le chemin associé au mapping en fonction des propriétés du surfer, du navigateur, etc.

Voir d’autres informations pour l’instant ici:

Config settings

L’installation et la configuratiion des processeurs est faite dans la section postProcessors du paramètre config_settings du plugin.

Il s’agit d’un objet JSON dont les clefs sont des identifiants de processeurs et la valeur correspondante est la définition du processeur correspondant.

La définition peut être :

  • une string:

    • le nom d’une classe (fournie en standard dans le plugin “config resolver”
      Par exemple:

      { "surferRole": "fr.wedia.confres.core.model.processor.SurferRolePostProcessor" }

    • un chemin vers un fichier groovy définissant la classe du processeur (le chemin est relatif au plugin défini par le paramètre default_contribution_plugin, ou plugin si celui-ci est indiqué)
      Par exemple:

      { "myprocessor": "res/postprocessors/myprocessor.groovy" }

    • une uri relative dans un jar (uniquement pour les plugins de contribution), situé dans le dossier lib du plugin
      Par exemple:

  • un objet JSON, avec les propriétés suivantes

    • processor: la même valeur qu’indiquée ci-dessus dans le point “une string”

    • plugin: le plugin

    • A ces propriétés, on peut ajouter des propriétés de configuration, ou une configuration par la propriété config. Voir ci-après, la section Configuration d'un processeur.

Contribution

Pour installer et configurer un processeur à partir d’un plugin, il suffit de mettre un fichierconfig-resolver-postprocessors.json dans le dossier config de ce plugin. Le format de ce fichier est similaire à la section postProcessors du paramètre de plugin config_settings(sauf que le seul plugin configuré est lui-même).

Configuration de processeur

Config Resolver (v0) | Set up.2

TODO: intégrer le contenu de la doc ci-dessus

Démarrage

Config Resolver (v0) | Startup

TODO: intégrer le contenu de la doc ci-dessus

Plugin de processeurs

Dans la configuration du plugin "config resolver", le paramètre default_contribution_plugin permet d'indiquer un plugin par défaut pour stocker des fichiers groovy de définition de processeurs.

Déboguage et monitoring

Il est possible d’analyser comment les différents éléments de configuration ou de contribution sont pris en compte par la page /_plugins/WXM_CONFIG_RESOLVER/page/admin/configreport.jspz ou par le menu “Plugin configuration” (Configuration Resolver - Toolkit | Plugin Configuration)