This is an automated email from the git hooks/post-receive script. New commit to branch develop in repository nuiton-config. See https://gitlab.nuiton.org/nuiton/nuiton-config.git commit 6c0877ccb8921df0d5ae7567d463830c3a5727a3 Author: Tony CHEMIT <chemit@codelutin.com> Date: Sat Oct 1 17:37:38 2016 +0200 Review doc --- nuiton-config-example/src/site/apt/index.apt.vm | 8 +- src/site/apt/index.apt | 13 ++ .../apt/index.apt.vm => src/site/apt/usage.apt.vm | 164 ++++++++++++++++----- src/site/site_fr.xml | 3 +- 4 files changed, 149 insertions(+), 39 deletions(-) diff --git a/nuiton-config-example/src/site/apt/index.apt.vm b/nuiton-config-example/src/site/apt/index.apt.vm index be82fd8..d2b3820 100644 --- a/nuiton-config-example/src/site/apt/index.apt.vm +++ b/nuiton-config-example/src/site/apt/index.apt.vm @@ -58,7 +58,7 @@ Utilisation * Décrire les options et les actions de la configuration - Dans notre exemple, nous avons 4 options dans la configuration : + Dans notre exemple, nous avons quatre options dans la configuration : * <<lastName>> le nom de l'utilisateur @@ -129,8 +129,8 @@ actions: +------------------------------------------------ <plugin> - <groupId>org.nuiton</groupId> - <artifactId>nuiton-config-maven-plugin</artifactId> + <groupId>${project.groupId}</groupId> + <artifactId>${project.artifactId}</artifactId> <version>${project.version}</version> <executions> <execution> @@ -192,7 +192,7 @@ target +------------------------------------------------ <plugin> <groupId>${project.groupId}</groupId> - <artifactId>nuiton-config-maven-plugin</artifactId> + <artifactId>${project.artifactId}</artifactId> <version>${project.version}</version> <reportSets> <reportSet> diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 69320ed..056289f 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -37,3 +37,16 @@ Présentation * un projet exemple qui utilise <<nuiton-config>> (voir {{{./nuiton-config-example/index.html} module Exemple}}). [] + +Philosophie du projet + + Le but de ce projet est de fournir une manière simple et efficace de gérer une ou plusieurs configurations dans un + projet Java. + + Pour ce faire, on propose de décrire les options et actions d'une configuration dans un format simple et concis (yaml) + + Ensuite on utilise le plugin de génération fourni pour générer une classe de configuration prête à l'emploi. + + On peut aussi par la suite générer un rapport <maven> de documentation de la configuration. + + Pour plus de détails, consulter la {{{./usages.html}page d'utilisation}}. diff --git a/nuiton-config-example/src/site/apt/index.apt.vm b/src/site/apt/usage.apt.vm similarity index 51% copy from nuiton-config-example/src/site/apt/index.apt.vm copy to src/site/apt/usage.apt.vm index be82fd8..2a12fcd 100644 --- a/nuiton-config-example/src/site/apt/index.apt.vm +++ b/src/site/apt/usage.apt.vm @@ -1,6 +1,6 @@ ~~~ ~~ #%L -~~ Nuiton Config :: Example +~~ Nuiton Config ~~ %% ~~ Copyright (C) 2016 Code Lutin, Tony Chemit ~~ %% @@ -8,57 +8,129 @@ ~~ it under the terms of the GNU Lesser 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 Lesser Public License for more details. -~~ +~~ ~~ You should have received a copy of the GNU General Lesser Public ~~ License along with this program. If not, see ~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. ~~ #L% ~~~ ---- - Nuiton Config Exemple + Nuiton Config Utilisation ---- ---- 2016-09-30 ---- -Utilisation +Décrire les options et les actions d'une configuration - Ce module est un exemple d'utilisation de <<nuiton-config>>. + Un format simple a été conçu pour décrire les options et actions d'une configuration. Il est base sur le format <<yaml>>. - Le principe est simple + Une configuration est composée d'une description, d'options et d'actions (optionnelles) - * Décrire la configuration dans un fichier au format simple ; ++------------------------------------------------ +description: Exemple de configuration +options: + - !option + - !option + ... +actions: + - !action + - !action + ... ++------------------------------------------------ - * Générer via le plugin maven le code java à partir de la description ; +* Comment décrire une option - * Utiliser la classe java de configuration qui a été générée ; + Une option contient les propriétés suivantes : - * Documenter votre configuration via le plugin de report. + * <<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. [] - Vous pouvez télécharger les sources du projet {{{https://nexus.nuiton.org/nexus/service/local/artifact/maven/redirect?g=public&g=org.nuiton&a=nuiton-config-example&v=${project.version}&e=zip&c=full}ici}}. +** 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>> - Dans cet exemple, nous utilisations toutes les valeurs par défaut fournies par le plugin (ZéroConf). + * <<url>> : <<java.net.URL>> - Voici le GAV du projet + * <<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 +------------------------------------------------ - <groupId>${project.groupId}</groupId> - <artifactId>${project.artifactId}</artifactId> - <version>${project.version}</version> + - !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 + ++------------------------------------------------ + - !action + name: help + description: Pour afficher l'aide + action: org.nuiton.config.example.NuitonConfigExample#help + aliases: + - "-h" + - "--help" +------------------------------------------------ - En utilisant les conventions du projet, la classe de configuration se nommera <<org.nuiton.config.example.NuitonConfigExampleConfig>>. +* Exemple -* Décrire les options et les actions de la configuration - Dans notre exemple, nous avons 4 options dans la configuration : + Dans notre exemple, nous avons cinq options dans la configuration : * <<lastName>> le nom de l'utilisateur @@ -78,7 +150,7 @@ Utilisation [] - Voici le fichier de description de cette configuration : + Voici la description qui correspond : +------------------------------------------------ description: Exemple de configuration @@ -122,27 +194,53 @@ actions: - "--help" +------------------------------------------------ +Générer la configuration -* Générer les classes de configuration - - Utiliser le mojo <<generate>> pour générer les classes. + Il suffit d'excuter le goal <<generate>> en lui indiquant le chemin de description de la configuration. +------------------------------------------------ <plugin> - <groupId>org.nuiton</groupId> + <groupId>${project.groupId}</groupId> <artifactId>nuiton-config-maven-plugin</artifactId> <version>${project.version}</version> <executions> <execution> <goals> <goal>generate</goal> - </goals> + </goals> </execution> </executions> </plugin> +------------------------------------------------ - Cela va générer les classes suivantes : + 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.yml>> + + Si vous voulez utiliser un autre nom, ajouter la propriété de configuration <<modelName>>. + +* Utilisation de Nuiton-I18n + + Il est possible d'utiliser {{{http://nuiton-i18n.nuiton.org/v/latest}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>${project.groupId}</groupId> + <artifactId>nuiton-config-example</artifactId> + <version>${project.version}</version> ++------------------------------------------------ + + Le nom du modèle est <<NuitonConfigExample>>, voici les classes qui seront générées : +------------------------------------------------ target @@ -157,7 +255,7 @@ target └── example ├── GeneratedNuitonConfigExampleConfig.java (2) ├── GeneratedNuitonConfigExampleConfigProvider.java (3) - ├── NuitonConfigExampleConfig.java (4) +---------------------> ├── NuitonConfigExampleConfig.java (4) <---------------------------- ├── NuitonConfigExampleConfigAction.java (5) ├── NuitonConfigExampleConfigOption.java (6) └── NuitonConfigExampleConfigProvider.java (7) @@ -170,7 +268,7 @@ target * (3) classe abstraite de provider - * <<(4) classe de configuration prête à l'emploi dans votre application>> + * <<(4) La classe de configuration prête à l'emploi dans votre application>> * (5) classe qui décrit les actions @@ -180,11 +278,9 @@ target [] - <« Et Voila !»>, vous pouvez utiliser la classe de configuration qui est prête à l'emploi. - - Retrouver le code source de toues les classes du projet ({{{./xref/index.html}ici}}). + <« Et Voila ! »>, vous pouvez utiliser votre configuration en Java. -* Générer la documentation de la configuration +Pour 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. @@ -204,4 +300,4 @@ target </plugin> +------------------------------------------------ - Retrouver le rapport généré ({{{./config-report.html}ici}}). + {{{./nuiton-config-example/config-report.html}Retrouver un exemple de rapport généré }}. diff --git a/src/site/site_fr.xml b/src/site/site_fr.xml index 330ca1a..e59f532 100644 --- a/src/site/site_fr.xml +++ b/src/site/site_fr.xml @@ -50,7 +50,8 @@ </breadcrumbs> <menu name="Utilisateur"> - <item name="Accueil" href="index.html"/> + <item name="Présentation" href="index.html"/> + <item name="Utilisation" href="usage.html"/> <item name="Note de versions" href="versions.html"/> </menu> -- To stop receiving notification emails like this one, please contact nuiton.org SCM administrator <admin+scm@nuiton.org>.