Nuiton Config – Nuiton Config Utilisation

Première étape : décrire sa configuration

La première chose à faire est de décrire sa configuration (options, actions, description, ...).

Il existe trois formats Ini, (Toml) ou (Yaml) pour décrire la configuration.

Le format par défaut est le Ini car il est le plus concis.

Comment décrire une configuration ?

Une configuration est composée d'une description, d'options et d'actions (optionnelles)

Format Ini

description = Exemple de configuration
[option 1]
[option 2]
...
[action 1]
[action 2]
...

Format Toml

description = "Exemple de configuration"
[[options]]
[[options]]
...
[[actions]]
[[actions]]
...

Format Yaml

description: Exemple de configuration
options:
  - !option
  - !option
  ...
actions:
  - !action
  - !action
  ...

Comment décrire une option ?

Une option contient les propriétés suivantes :

name : [obligatoire] nom de l'option (dans la configuration générée, on pourra accéder à cette option via des getters/setters adaptés) ;
key : [obligatoire] la clef de l'option à utiliser pour la sauvegarde dans le fichier de configuration ;
type : [obligatoire] type de l'option (voir plus bas) ;
description : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ;
defaultvalue : [optionnel] une valeur par défaut.

Types d'une option

Tous les types natifs de l'API nution-config sont disponibles simplement via les alias suivants :

string : java.lang.String
les types primitifs (boolean, int, ...) et leur équivalents en objet (Boolean, Integer, ...)
file : java.io.File
class : java.lang.Class
url : java.net.URL
color : java.awt.Color
keystroke : javax.swing.KeyStroke
version : org.nuiton.version.Version
date : java.util.Date
time : java.sql.Time
timestamp : java.sql.Timestamp

Pour pouvez aussi mettre n'importe quelle classe java qui dispose d'une constructeur publique via son nom qualifié.

Exemple d'une option au format Ini

[options age]
name = age
key = identity.age
description = age de l'utilisateur
type = int
defaultValue = 56

Exemple d'une option au format Toml

[[options]]
name = "age"
key = "identity.age"
description = "age de l'utilisateur"
type = "int"
defaultValue = "56"

Exemple d'une option au format Yaml

  - !option
    name: age
    key: identity.age
    type: int
    description: age de l'utilisateur
    defaultValue: 56

Comment décrire une action ?

Une action contient les propriétés suivantes :

name : [obligatoire] nom de l'action ;
description : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ;
action : [obligatoire] l'action à executer ;
aliases : [optionnel] des alias pour activer l'action.

Exemple d'une action au format Toml

[action help]
description = Pour afficher l'aide
action = org.nuiton.config.example.NuitonConfigExample#help
aliases = -h, --help

Exemple d'une action au format Toml

[[actions]]
name = "help"
description = "Pour afficher l'aide"
action = "org.nuiton.config.example.NuitonConfigExample#help"
aliases = ["-h", "--help"]

Exemple d'une action au format Yaml

  - !action
    name: help
    description: Pour afficher l'aide
    action: org.nuiton.config.example.NuitonConfigExample#help
    aliases:
      - "-h"
      - "--help"

Exemple

Dans notre exemple, nous avons cinq options dans la configuration :

lastName le nom de l'utilisateur
firstName le prénom de passe de l'utilisateur
email le courriel de l'utilisateur
twitter le compte twitter de l'utilisateur
age l'age de l'utilisateur

Nous avons aussi défini une action :

help pour afficher l'aide

Voir le fichier de configuration au format Ini, Toml ou Yaml.

Deuxième étape : Générer la configuration

Il suffit d'excuter le goal generate en lui indiquant le chemin de description de la configuration.

      <plugin>
        <groupId>org.nuiton</groupId>
        <artifactId>nuiton-config-maven-plugin</artifactId>
        <version>3.5-SNAPSHOT</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
           </goals>
          </execution>
        </executions>
      </plugin>

Le format par défaut utilisé est ini, vous pouvez aussi utiliser le format toml ou yaml.

Par défaut, on place le fichier de description dans le répertoire src/main/config.

Si on ne précise pas de nom de modèle, le plugin utilise l'identifiant de l'artefact en le transformant au format «Camel Case».

Par exemple, si l'artifactId est nuiton-config-example, le nom de fichier est NuitonConfigExample.toml

Si vous voulez utiliser un autre nom, ajouter la propriété de configuration modelName.

Utilisation de Nuiton-I18n

Il est possible d'utiliser Nuiton-I18n pour externaliser les descriptions de la configuration, options et actions.

Il suffit d'activer la propriété useNuitonI18n dans le plugin de génération.

Dans le fichier de description, remplacer tous les descriptions par des clefs i18n.

Exemple

En supposant que le gav de votre projet soit :

  <groupId>org.nuiton</groupId>
  <artifactId>nuiton-config-example</artifactId>
  <version>3.5-SNAPSHOT</version>

Le nom du modèle est NuitonConfigExample, voici les classes qui seront générées :

target
└── generated-sources
    └── java
        ├── META-INF
        │   └── services
        │       └── org.nuiton.config.ApplicationConfigProvider             (1)
        └── org
            └── nuiton
                └── config
                    └── example
                        ├── GeneratedNuitonConfigExampleConfig.java         (2)
                        ├── GeneratedNuitonConfigExampleConfigProvider.java (3)
--------------------->  ├── NuitonConfigExampleConfig.java                  (4) <----------------------------
                        ├── NuitonConfigExampleConfigAction.java            (5)
                        ├── NuitonConfigExampleConfigOption.java            (6)
                        └── NuitonConfigExampleConfigProvider.java          (7)

fichier qui enregistre (en utilisant le mécanisme ServiceLoader), le provider de configuration généré
classe abstraite de configuration
classe abstraite de provider
classe de configuration prête à l'emploi dans votre application
classe qui décrit les actions
classe qui décrit les options
provider de configuration prêt à l'emploi (il sert pour la génération de la documentation notamment)

« Et Voila ! », vous pouvez utiliser votre configuration en Java.

Troisième étape : générer la documentation de votre configuration

Utiliser le mojo de report report ou aggregate-report pour générer la documentation sur les configurations détectées via les providers.

      <plugin>
        <groupId>org.nuiton</groupId>
        <artifactId>nuiton-config-maven-plugin</artifactId>
        <version>3.5-SNAPSHOT</version>
        <reportSets>
          <reportSet>
            <reports>
              <report>report</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>

Exemple de rapport généré.

Décrire une configuration à partir des classes java (migration)

Il est possible facilement de convertir des classes java de configuration en fichier de description (ensuite il suffit alors de supprimer les classes java et de les générer iva le plugin).

Pour cela il faut utiliser le goal describe.

Il faut au préalable que vous ayez défini un provider de configuration (Voir ApplicationConfigProvider TODO).

Lancer ensuite en ligne de commande

mvn nuiton-config:describe [ -Dconfig.providerName=NuitonConfigExample ]

Cela va générer le fichier (ini) à l'emplacement suivant :

src
└── main
    └── config
        └── NuitonConfigExample.ini

Vous pouvez aussi choisir le format toml ou yaml en passant l'option -Dconfig.format=ini|toml|yaml.

Lire et enregistrer ApplicationConfig au format ini

Depuis la version 3.1, il est possible de lire et d'enregistrer sa configuration au format ini.

Pour ce faire, vous reporter à la page d'utilisation de ApplicationConfig.