Vue d'ensemble : Directives du fichier de configuration

Le Wrapper définit des directives spéciales qui sont traitées lors du chargement du fichier de configuration. Celles-ci sont classées dans les sections ci-dessous :

AVERTISSEMENT

Avant la version 3.6.0 du Wrapper, les directives s'écrivaient en commençant par le caractère '#' au lieu de '@'. Cela rendait toutefois difficile de les distinguer des commentaires, qui commencent également par un caractère '#'.

Lorsque vous utilisez une version du Wrapper antérieure à 3.6.0, n'oubliez pas de remplacer le '@' dans les exemples ci-dessous et d'écrire toujours les directives en commençant par un '#'.

Lorsque vous utilisez la version 3.6.0 du Wrapper ou une version ultérieure, l'ancienne syntaxe utilisant '#' reste prise en charge pour des raisons de compatibilité. Toutefois, la syntaxe par défaut et recommandée consiste à écrire les directives en commençant par un '@'.

Encodage du fichier de configuration

À partir de la version 3.5.0 du Wrapper, il est devenu possible de spécifier l'encodage de chaque fichier de configuration. L'encodage le plus portable est UTF-8, mais d'autres encodages sont pris en charge sur certaines plates-formes.

La directive d'encodage doit être spécifiée sur la première ligne d'un fichier de configuration. Le Wrapper consignera un avertissement si un fichier ne contient pas cette directive. Il est possible de spécifier des encodages différents dans les fichiers inclus (style en cascade).

Exemple UTF-8 : 
@encoding=UTF-8

wrapper.debug=FALSE
...

Inclusion de fichiers de configuration en cascade

Il est possible de répartir une configuration dans un ou plusieurs fichiers de configuration facultatifs et de les inclure ensuite depuis le fichier principal. Consultez la page Fichier de configuration en cascade (« fichier include ») pour plus d'informations.

Exemple : 
@include ../conf/wrapper-settings.conf

Mode d'inclusion

Par conception, le Wrapper ignore silencieusement tout fichier inclus qu'il ne parvient pas à localiser ou à lire, pour quelque raison que ce soit. Cela peut s'avérer très puissant, car cela permet de créer des configurations spécifiques à une plate-forme ou de remplacer éventuellement des valeurs de propriétés existantes.

Dans certains cas, toutefois, un fichier inclus est requis pour le bon fonctionnement d'une application. C'est notamment le cas des fichiers sécurisés contenant des mots de passe ou des données sensibles. À partir de la version 3.5.5 du Wrapper, il est possible de spécifier une inclusion obligatoire, ce qui provoquera une erreur et empêchera le Wrapper de démarrer si le fichier est manquant.

Exemple : 
@include.required ../conf/wrapper-settings.conf

À partir de la version 3.6.0 du Wrapper, il est possible de spécifier si les fichiers inclus sont facultatifs ou obligatoires par défaut. Ce mode d'inclusion peut être défini avec la directive @include.default_mode et peut être modifié n'importe où dans le fichier de configuration actuel ou dans ses fichiers inclus.

Exemple : 
@include.default_mode=required

# These are required includes
@include ../conf/wrapper-settings1.conf
@include ../conf/wrapper-settings2.conf
@include ../conf/wrapper-settings3.conf

@include.default_mode=optional

# These are optional includes
@include ../conf/wrapper-additional-settings1.conf
@include ../conf/wrapper-additional-settings2.conf
@include ../conf/wrapper-additional-settings3.conf

@include.optional permet de spécifier un fichier inclus facultatif lorsque le mode d'inclusion par défaut est 'required'.

Exemple : 
@include.default_mode=required

# This is a required include
@include ../conf/wrapper-settings.conf

# This is a optional include
@include.optional ../conf/wrapper-additional-settings.conf

Débogage des fichiers inclus

À partir de la version 3.3.0 du Wrapper, il est possible de déboguer le fonctionnement de la directive @include en voyant exactement ce qui est inclus et ce qui ne l'est pas. Consultez la page Messages de débogage dans le « fichier include » (style en cascade) pour plus d'informations.

Exemple : 
@include.debug

Déclarer des propriétés finales
Compatibilité :3.7.0
Éditions :Édition ProfessionnelleÉdition StandardÉdition Community (non prise en charge)
Plateformes :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

À partir de la version 3.7.0 du Wrapper, vous pouvez créer des sections dans votre fichier de configuration où les propriétés (ou les définitions de variables) sont marquées comme finales. Déclarer une propriété comme finale verrouille sa valeur, empêchant toute déclaration ultérieure dans le même fichier ou dans un fichier inclus de la remplacer.

Cas d'utilisation pratique :

Répartissez votre configuration dans plusieurs fichiers inclus. Stockez les propriétés critiques de l'application dans un fichier avec des permissions restrictives et marquez-les comme finales. Stockez les propriétés secondaires dans un fichier distinct avec des permissions plus larges, permettant aux utilisateurs de les remplacer ou de les modifier si nécessaire.

Syntaxe et portée :

Pour commencer une section où les propriétés sont définies comme finales, ajoutez @properties.final=TRUE n'importe où dans votre fichier de configuration.

Pour revenir au mode par défaut où les propriétés peuvent être remplacées, utilisez @properties.final=FALSE.

NOTE

Cette directive n'affecte que le fichier de configuration actuel dans lequel elle est déclarée et ne se propage pas aux fichiers inclus.

Exemple de déclaration finale : 
# Start a final section to ensure the following properties will never be modified
@properties.final=TRUE

# Main class.
wrapper.java.mainclass=org.tanukisoftware.wrapper.test.Main

# Application parameters.
#  Pass parameters via the backend instead of the command line.
wrapper.app.parameter.backend=TRUE

#  Add parameters as needed starting from 1
wrapper.app.parameter.1=param1
wrapper.app.parameter.2=param2

# Back to normal mode
@properties.final=FALSE

AVERTISSEMENT

Si des déclarations finales en double sont trouvées pour la même propriété, le Wrapper considérera cela comme une mauvaise configuration et interrompra le démarrage afin d'éviter un état de configuration ambigu.

Ce comportement strict s'applique également aux propriétés de la ligne de commande. Les remplacements via la ligne de commande étant intrinsèquement traités comme finaux, toute tentative de remplacer une propriété déjà marquée comme finale dans le fichier de configuration provoquera un conflit fatal.

Dans tous les cas, le Wrapper consignera un message d'erreur détaillant le conflit avant de s'arrêter.

Débogage des propriétés

À partir de la version 3.5.4 du Wrapper, il est possible de configurer le Wrapper afin qu'il affiche un message au démarrage chaque fois qu'une propriété est remplacée par une autre déclaration, ou lorsqu'une propriété ne peut pas être définie car sa valeur est fixe.

La version 3.5.27 du Wrapper améliore cette fonctionnalité. Il est désormais possible de contrôler le niveau de journalisation de ces messages et de spécifier si le Wrapper doit s'arrêter après les avoir consignés. Vous pouvez également appliquer des paramètres différents par sections de vos fichiers de configuration et ainsi être plus ou moins strict dans certaines parties. Cela peut être réalisé à l'aide de deux nouvelles directives :

Selon la nature des propriétés, le Wrapper affichera des messages différents. Ces messages sont décrits ci-dessous.

NOTE

Ces messages ne sont consignés qu'en mode débogage par défaut car il est courant de remplacer les valeurs de propriétés à l'aide d'un fichier de configuration en cascade (« fichier include ») facultatif, ou d'autres méthodes.

AVERTISSEMENT

Les propriétés wrapper.name et wrapper.displayname étant définies dans le script shell UNIX, si vous utilisez ce script pour lancer le Wrapper et si vous déboguez les propriétés à l'aide des directives ci-dessus, vous pourriez obtenir des messages d'avertissement, car ces variables sont également définies par défaut dans le fichier de configuration.

Vous pouvez éviter ces messages soit en supprimant les propriétés redondantes dans le fichier de configuration, soit en décommentant la ligne '#APP_NAME_PASS_TO_WRAPPER=false' dans le fichier de script.

La seconde option fera en sorte que le script ne transmette plus ces paramètres au Wrapper. Veillez à ne pas désactiver les propriétés 'APP_NAME' et 'APP_LONG_NAME', qui sont nécessaires au bon fonctionnement du script.

Messages

Pour aider à comprendre pourquoi une propriété a une valeur spécifique, il peut être utile de visualiser le moment où sa valeur a été modifiée, ou au contraire, le moment où elle a été ignorée malgré une tentative de remplacement.

Voici les messages que vous pouvez obtenir :

Propriétés superposées :

Le Wrapper est configuré de sorte que la dernière instance définie d'une propriété spécifique soit utilisée. Cela peut s'avérer très puissant, car des valeurs par défaut peuvent être définies, puis un fichier inclus facultatif contenant des valeurs spécifiques à un système peut être référencé.

Exemple de redéfinition de propriété : 
STATUS | wrapper  | The "foo.bar" property was redefined.
STATUS | wrapper  |   Old Value foo.bar=123 (on line #10 of configuration file: /home/wrapper/conf/wrapper.conf)
STATUS | wrapper  |   New Value foo.bar=XYZ (on line #12 of configuration file: /home/wrapper/conf/wrapper-custom.conf)

Propriétés de la ligne de commande :

Les valeurs de propriétés spécifiées sur la ligne de commande du Wrapper sont « finales », ce qui signifie qu' elles ne peuvent pas être modifiées ou remplacées par des valeurs du fichier de configuration. Cela est très utile, car un utilisateur peut exécuter le Wrapper avec une valeur de test sans avoir à modifier réellement le fichier de configuration.

Exemple de redéfinition d'une propriété finale : 
STATUS | wrapper  | The "foo.bar" property is defined on the Wrapper command line and cannot be overwritten.
STATUS | wrapper  |   Fixed Value foo.bar=123
STATUS | wrapper  |   Ignored Value foo.bar=XYZ (on line #8 of configuration file: /home/wrapper/conf/wrapper.conf)

Variables d'environnement internes :

Le Wrapper définit également plusieurs variables d'environnement internes. Celles-ci sont définies à l'aide de propriétés finales. Si le fichier de configuration de l'utilisateur tente de définir l'une d'entre elles, le Wrapper les ignorera et conservera les valeurs définies par le Wrapper.

Exemple de redéfinition d'une propriété finale : 
STATUS | wrapper  | The "set.WRAPPER_ARCH" property is defined by the Wrapper internally and cannot be overwritten.
STATUS | wrapper  |   Fixed Value set.WRAPPER_ARCH=x86
STATUS | wrapper  |   Ignored Value set.WRAPPER_ARCH=special (on line #10 of configuration file: /home/wrapper/conf/wrapper.conf)

@properties.on_overwrite.loglevel
Compatibilité :3.5.27
Éditions :Édition ProfessionnelleÉdition StandardÉdition Community
Plateformes :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Cette directive est utilisée pour définir le niveau de journalisation auquel les messages doivent être consignés.

Les valeurs valides sont les suivantes :

  • AUTO : une valeur par défaut pour résoudre automatiquement le niveau de journalisation (voir ci-dessous).

  • NOTICE : pour consigner au niveau de journalisation NOTICE.

  • ADVICE : pour consigner au niveau de journalisation ADVICE.

  • FATAL : pour consigner au niveau de journalisation FATAL.

  • ERROR : pour consigner au niveau de journalisation ERROR.

  • WARN : pour consigner au niveau de journalisation WARN.

  • STATUS : pour consigner au niveau de journalisation STATUS.

  • INFO : pour consigner au niveau de journalisation INFO.

  • DEBUG : pour consigner au niveau de journalisation DEBUG.

La valeur par défaut est AUTO, qui est résolue en 'WARN' chaque fois qu'une propriété est remplacée dans le même fichier de configuration ou dans un fichier avec une profondeur d'inclusion inférieure à celle du fichier de la définition précédente. Elle est également résolue en 'WARN' lorsqu'une propriété finale intégrée lors de la personnalisation est remplacée. Dans tous les autres cas, elle est résolue en 'DEBUG'.

NOTE

Avant la version 3.5.36, la valeur par défaut de cette directive était DEBUG.

Exemple (consigner les propriétés remplaçées au niveau d'avertissement) : 
@properties.on_overwrite.loglevel=WARN

NOTE

L'utilisation de la directive #properties.debug est dépréciée depuis la version 3.5.27 du Wrapper au profit de ces nouvelles directives qui offrent un contrôle plus fin du débogage des propriétés. Pour des raisons de compatibilité, #properties.debug aura le même effet que @properties.on_overwrite.loglevel=STATUS.

@properties.on_overwrite.exit
Compatibilité :3.5.27
Éditions :Édition ProfessionnelleÉdition StandardÉdition Community
Plateformes :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Cette directive est utilisée pour spécifier si le Wrapper doit s'arrêter si une propriété est remplacée.

Les valeurs valides sont les suivantes :

  • TRUE : spécifie que le Wrapper doit s'arrêter si une propriété suivant cette directive est remplacée.

  • FALSE : spécifie que le Wrapper ne doit pas s'arrêter si une propriété suivant cette directive est remplacée.

La valeur par défaut est FALSE.

Exemple (s'arrêter si une propriété remplacée est rencontrée) : 
@properties.on_overwrite.exit=TRUE

Utilisation

Une directive est valide à partir de la ligne où elle est insérée dans le fichier de configuration jusqu'à la fin du fichier ou jusqu'à ce qu'une directive suivante portant le même nom soit rencontrée. Si elle est trouvée, la valeur de la nouvelle directive devient alors valide pour la section suivante du fichier de configuration.

Lorsque @properties.on_overwrite.exit est défini sur TRUE, la valeur de @properties.on_overwrite.loglevel est automatiquement élevée à FATAL (si elle est définie à un niveau inférieur). Cela reste en vigueur tant que @properties.on_overwrite.exit n'est pas réinitialisé à FALSE.

Exemple : 
wrapper.name=@app.name@
wrapper.lang.folder=../lang
...

@properties.on_overwrite.loglevel=STATUS
wrapper.lang.folder=../../lang
...

@properties.on_overwrite.loglevel=INFO
wrapper.name=newAppName
...

@properties.on_overwrite.exit=TRUE
wrapper.app.parameter.3=start
...

wrapper.app.parameter.3=start_app
...

@properties.on_overwrite.exit=FALSE
...

Dans la configuration ci-dessus, wrapper.lang.folder sera consigné avec un niveau 'STATUS', wrapper.name sera consigné avec un niveau 'INFO', et wrapper.app.parameter.3 sera consigné à un niveau 'FATAL', ce qui provoquera l'arrêt du Wrapper. Toute propriété suivant '@properties.on_overwrite.exit=FALSE' ne provoquera pas l'arrêt du Wrapper et sera consignée avec un niveau 'INFO', tel que défini précédemment.

NOTE

À partir de la version 3.5.27, le Wrapper consignera également des messages si la ligne de commande contient des propriétés dupliquées ou tente de définir une variable d'environnement interne.

Vous pouvez toujours utiliser @properties.on_overwrite.loglevel et @properties.on_overwrite.exit pour contrôler le niveau de journalisation auquel ces messages doivent apparaître et pour spécifier si le Wrapper doit s'arrêter après les avoir consignés. Si plusieurs directives sont définies dans le fichier de configuration, la dernière directive de chaque type s'appliquera.

Activer ou désactiver l'expansion des variables
Compatibilité :3.5.55
Éditions :Édition ProfessionnelleÉdition StandardÉdition Community
Plateformes :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Toute valeur de propriété de configuration peut référencer des variables avec la syntaxe suivante : %MYVAR%. Pour plus de détails sur la façon de définir une variable et la liste des variables prédéfinies, veuillez consulter cette page.

À partir de la version 3.5.55 du Wrapper, il est possible d'activer ou de désactiver l'expansion des variables (c'est-à-dire le remplacement de la notation syntaxique ci-dessus par la valeur de la variable) pour des sections du fichier de configuration.

Par défaut (si cette directive n'est pas utilisée), l'expansion des variables est activée. Vous pouvez la désactiver en ajoutant '@variables.expand=FALSE' n'importe où dans votre fichier de configuration. Les propriétés référencées sur les lignes suivantes n'effectueront pas l'expansion des variables. '@variables.expand=TRUE' vous permet de réactiver l'expansion des variables à partir d'une certaine ligne.

Exemple : 
set.MYVAR=some_value

@variables.expand=FALSE

# %MYVAR% will not be expanded
wrapper.app.parameter.1=%MYVAR% 

@variables.expand=TRUE

# %MYVAR% will be expanded to 'some_value'
wrapper.app.parameter.2=%MYVAR%

NOTE

La désactivation de l'expansion des variables s'applique uniquement au fichier de configuration actuel, et non aux fichiers inclus. Si un fichier est inclus après que @variables.expand a été défini sur FALSE, les variables référencées dans le fichier inclus seront étendues, sauf si le fichier lui-même spécifie également @variables.expand=FALSE.

Pourquoi est-ce utile ?

Dans certains cas, vous pouvez avoir besoin d'utiliser le caractère '%' dans une valeur de propriété. Lorsque ce caractère est référencé deux fois dans la même valeur, ils seront interprétés comme des délimiteurs de variable, même si vous n'aviez pas l'intention de référencer une variable.

Exemple : (la valeur suivante générera un avertissement « The '20with' environment variable was referenced but has not been defined. ») 
wrapper.app.parameter.1=http://url%20with%20spaces

Pour contourner ce problème, une possibilité consiste à utiliser une variable spéciale %WRAPPER_PERCENTAGE% dont la valeur est un seul caractère '%'.

Exemple : (s'étendra en 'http://url%20with%20spaces' sans générer d'avertissement) 
wrapper.app.parameter.1=http://url%WRAPPER_PERCENTAGE%20with%WRAPPER_PERCENTAGE%20spaces

Toutefois, cela peut rendre la valeur plus difficile à lire, surtout si '%' est utilisé de nombreuses fois.

@variables.expand offre une alternative pour désactiver complètement l'expansion des variables si vous savez que certaines parties de votre configuration ne référencent aucune variable et doivent utiliser le caractère '%' sans qu'il soit interprété comme un délimiteur de variable.

Référence : Niveau de journalisation
  • wrapper.console.loglevel (1.0.0)

    Filtre les messages envoyés à la console selon leur niveau de journalisation.

  • wrapper.logdialog.loglevel (3.3.1)

    Filtre les messages de la boîte de dialogue de journal selon leur niveau de journalisation.

  • wrapper.logfile.loglevel (2.2.5)

    Filtre les messages envoyés au fichier journal selon leur niveau de journalisation.

  • wrapper.syslog.loglevel (2.2.5)

    Filtre les messages envoyés au syslog (ou au journal des événements sous Windows) selon leur niveau de journalisation.