Classe de base

Cette page donne accès à la documentation sur la classe de base XmlConfig qui gère les paramètres de configuration.
Pour plus de détail vous pouvez consulter la documentation javadoc.

La classe net.sourceforge.jezxmlconfig.XmlConfig implémente un objet qui contient des paramètres de configuration.

Les paramètres sont contenus dans des sections hiérarchiques.
C'est-à-dire qu'une section peut contenir des sous-sections et des paramètres.
Il n'y a pas de limite sur le niveau de profondeur des sous-section.

Voici un exemple de la structure d'une configuration :

Un paramètre est identifié par son nom et possède une valeur.
La valeur d'un paramètre peut contenir une référence à une constante définie ou à une propriété système.

Pour plus d'information sur le format JEZXmlConfig vous pouvez consulter le DTD.

Exemple concret de configuration:

On veut définir les paramètres d'une application qui lit des fichiers en entrée et qui produit un résultat dans un répertoire.

Deux sources sont traitées en entrée:

Les fichiers qui viennent de la facturation seront lus dans un sous-répertoire de l'utilisateur qui correspond à l'environnement d'exécution, et dans le sous-répertoire billing.
Le nom des fichiers a pour format Bill_*.dat.
Exemple: "/home/frederic/production/billing"
Ici le répertoire de l'utilisateur est "/home/frederic", et on exécute dans l'environnement de production.

Les fichiers provenant des autres sources sont présents dans le sous-répertoire other qui est au même niveau que billing.
Le nom des fichiers a pour format Oth_*.xml.

Les résultats sont stockés dans le répertoire /DATA.

Enfin, l'application sera lancée automatiquement toutes les 60 minutes et produira des fichiers qui contiendront un maximum de 5000 enregistrements.

Voici donc une façon de stocker les paramètres de configuration de cette application.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <configuration>
        <constants>
            <constant name="env" value="production"/>
        </constants>
        <parameters>
            <section name="Input">
                <section name="Billing">
                    <param name="subDir" value="billing"/>
                    <param name="prefix" value="Bill_"/>
                    <param name="suffix" value=".dat"/>
                </section>
                <section name="Other">
                    <param name="subDir" value="other"/>
                    <param name="prefix" value="Oth_"/>
                    <param name="suffix" value=".xml"/>
                </section>
                <param name="rootPath" value="${user.home}/${env}"/>
            </section>
            <section name="Output">
                <param name="resultDir" value="/DATA"/>
            </section>
            <section name="Process">
                <param name="maxRecordPerFile" value="5000"/>
                <param name="frequency" value="60"/>
            </section>
        </parameters>
    </configuration>

Bien sûr, vous pouvez saisir les paramètres directement dans un fichier XML.
Mais si vous n'êtes pas très familier avec la syntaxe XML vous pouvez utiliser l'éditeur fourni.

Chargement de la configuration

Votre application chargera certainement la configuration lors de son lancement initial.
Le code de votre méthode pourra ressembler aux lignes suivantes:

  // Get configuration instance: Build an empty configuration at very first access
  private XmlConfig config = XmlConfig.getInstance(); // Instance variable

  ...

  /**
   * Load application configuration in memory.
   * @param configFile Configuration file.
   * @exception MyApplicationException If configuration cannot be loaded (details in exception message).
   */
  private void loadConfig(File configFile) {
      try {
          this.config.load(configFile);
      }
      catch(XmlConfigException xce) {
          throw MyApplicationException("Cannot load configuration: " + xce.getMessage());
      }
  }

Remarque 1: Vous pouvez importer un fichier de propriétés Java avec la méthode loadProperties(). Comme tout paramètre est dans une section, un nom simple (sans point dans son identifiant) est considéré comme une constante.
Exemple:

word1.word2.word3=value1: sera le paramètre word3 dans la sous-section word2 de la section racine word1.
word0=value2: sera la constante word0.

Remarque 2: Il est également possible de charger une configuration avec JNDI (Java Naming Directory Interface).

Accès aux paramètres

Lorsque vous voulez accéder aux paramètres dans votre application, il vous suffit d'écrire quelques lignes simples:

      // Get process frequency
      int freq = this.config.getIntParameter("Process", "frequency", DEFAULT_FREQUENCY);

      ...

      // Get all billing files
      File billingDir;
      try {
          // Config object verify if rootPath directory exists
          File rootPath = (File)this.config.getObject(TYPE_DIR, "Input", "rootPath");
          billingDir = new File(rootPath, this.config.getStringParameter("Input.billing", "subDir"));
      }
      catch(XmlConfigException xce) {
          // Billing directory parameter is missed in configuration, or directory does not exist !
          throw new MyApplicationException("Cannot acces billing directory parameter: " + xce.getMessage());
      }

      ...

      File[] files = billingDir.listFiles();

      ...

Modification de la configuration

Supposez que votre application possède une interface utilisateur qui permet de rajouter des sources de données.

Un administrateur veut ainsi ajouter le traitement des fichiers provenant d'un nouveau sous-répertoire "accounting".

Votre code peut contenir une méthode pour modifier le fichier de configuration et le sauvegarder:

  private void addSourceDirectory(String sourceName, String directory, String prefix, String suffix) throws XmlConfigException {
      // Get configuration instance
      XmlConfig myConfig = XmlConfig.getInstance();

      // Add new section for new data source
      String fullSectionName = "Input." + sourceName;
      config.addSection(fullSectionName);

      // Add new section parameters
      config.addParameter(fullSectionName, "subDir", directory);
      config.addParameter(fullSectionName, "prefix", prefix);
      config.addParameter(fullSectionName, "suffix", suffix);

      // Save configuration
      config.save();
  }

Après l'exécution de ce code, vous obtenez le fichier de configuration suivant:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <configuration>
        <constants>
            <constant name="env" value="production"/>
        </constants>
        <parameters>
            <section name="Input">
                <section name="Billing">
                    <param name="subDir" value="billing"/>
                    <param name="prefix" value="Bill_"/>
                    <param name="suffix" value=".dat"/>
                </section>
                <section name="Other">
                    <param name="subDir" value="other"/>
                    <param name="prefix" value="Oth_"/>
                    <param name="suffix" value=".xml"/>
                </section>
                <section name="Accounting">
                    <param name="subDir" value="acct"/>
                    <param name="prefix" value="Acct_"/>
                    <param name="suffix" value=".bin"/>
                </section>
                <param name="rootPath" value="${user.home}/${env}"/>
            </section>
            <section name="Output">
                <param name="resultDir" value="/DATA"/>
            </section>
            <section name="Process">
                <param name="maxRecordPerFile" value="5000"/>
                <param name="frequency" value="60"/>
            </section>
        </parameters>
    </configuration>

Enfin, si vous voulez éviter de coder pour la modification de votre configuration, rien ne vous empêche de livrer l'éditeur avec votre application et de demander à un administrateur responsable de l'utiliser directement...

Rubriques

Classe de base