Jakarta Commons Configuration

I-A. Contenu de l'API▲

I-B. Dépendances▲

Comme nous l'avons dit, toutes les classes servant à gérer une configuration implémentent org.apache.commons.configuration.Configuration. Les configurations sont basées sur un principe de paires clé/valeur. L'interface de base définit des méthodes communes permettant d'obtenir différents éléments à partir de la Configuration. Celle-ci permet de récupérer des objets (ou des types primitifs) des types suivants : BigDecimal, BigInteger, Boolean/boolean, Byte/byte, Double/double, Float/float, Integer/int, List d'Object, Long/long, Short/short et String. Chaque méthode est déclinée en deux versions :

• une version qui ne prend que la clé. Si la clé n'existe pas dans la Configuration, une NoSuchElementException est soulevée, si la valeur n'est pas du type demandé, une ConversionException est soulevée ;
• une version qui prend la clé et une valeur par défaut (d'un type primitif ou wrapper) si la clé n'existe pas. Si la valeur n'est pas du type demandé, une ConversionException est soulevée.

Si vous souhaitez récupérer un wrapper (Boolean, Long, etc.), il faut fournir une valeur par défaut qui soit de la classe du wrapper, sinon c'est une valeur de type primitif, s'il en existe un, qui est renvoyée. Une méthode générique existe également, il s'agit de getProperty(String key), elle renvoie un objet sans se préoccuper de son type. Il faut savoir que dans le cas où la configuration est sauvegardée par programmation, les objets sont écrits sous forme de chaine et chargés sous la même forme, il est donc nécessaire d'avoir une méthode permettant de régénérer l'objet à partir de la chaîne. Lorsque plusieurs valeurs correspondent à la même clé, les méthodes classiques ne renvoient que la première. Vous pouvez alors passer par la méthode getList qui renvoie une List contenant toutes les chaines correspondant à la clé. La méthode getProperty peut également être utilisée, elle renvoie un objet qui sera une instance de Collection s'il existe plusieurs valeurs pour la clé. Les éléments de configuration de type chaîne peuvent faire référence les uns aux autres grâce à la séquence ${autreChaine}. Dans ce cas, la séquence sera remplacée par le contenu de la propriété autreChaine.

Ainsi, la lecture d'un élément de configuration aura l'aspect suivant :

Configuration c = new BaseConfiguration(); // On crée une configuration simple
try {
    boolean b1 = c.getBoolean(«valeurbool»);                // Type de base (nsee ou ce possibles)
    boolean b2 = c.getBoolean(«valeurbool», true);          // Type de base (ce possible)
    Boolean b3 = c.getBoolean(«valeurbool», Boolean.TRUE);  // Wrapper (ce possible)
} catch(NoSuchElementException nsee) {
    log.fatal(«La propriété valeurbool n'est pas définie !»);
} catch(ConversionException ce) {
    log.fatal(«La propriété valeurbool doit être un booléen !»);
}

Une série de méthodes est également fournie de façon à gérer la configuration via la programmation. Ainsi, clearPropertie(String clé) supprime la propriété identifiée par clé, addPropertie(String clé, Object val) ajoute la propriété définie par la paire clé/valeur, si une propriété avec la même clé existait déjà, elles sont chaînées dans une List contrairement à setPropertie(String clé, Object val) qui supprime toute valeur préexistante.

Nous allons maintenant voir les différents types de configuration proposés par l'API commons configuration.

Il existe deux types de configurations basées sur les fichiers : les fichiers properties et les fichiers XML. Quel que soit le type choisi, un certain nombre de fonctionnalités communes sont disponibles. Nous les décrivons ici avant d'explorer chaque type plus en détail.

Les configurations basées sur des fichiers implémentent l'interface org.apache.commons.configuration.FileConfiguration. Celle-ci définit des méthodes permettant de charger la configuration à partir d'un fichier (File), de l'emplacement du fichier ou d'une URL. S'il est impossible de charger le fichier, une ConfigurationException est soulevée.

Il est possible de forcer le rechargement au cours de l'exécution en appelant la méthode load ; invoquée sans argument, celle-ci ne rechargera le même fichier que lors de la création de l'objet. Mais il est plus intéressant d'utiliser un mécanisme proposé par l'API appelé ReloadingStrategy. Ce mécanisme détermine si le fichier doit être rechargé ou non. Lors d'un appel à l'une des méthodes get, la stratégie est interrogée pour savoir si le fichier doit être rechargé. Par défaut, le fichier n'est jamais rechargé (InvariantReloadingStrategy), mais il est possible de modifier ce comportement en appelant la méthode setReloadingStrategy et en lui passant une instance de FileChangedReloadingStrategy qui effectue un rechargement à chaque fois que le fichier est modifié. Vous n'aurez probablement pas à créer vos propres ReloadingStrategies.

Comme pour le chargement, il est possible de forcer la sauvegarde à n'importe quel moment en appelant la méthode save qui sauvegarde la totalité de la configuration à l'emplacement spécifié lors de sa création si on ne lui passe pas d'arguments. Là encore, une méthode de sauvegarde automatique est proposée, elle est désactivée par défaut. Vous pouvez l'activer en appelant setAutoSave(true), dès lors, chaque modification, définition ou suppression de propriété entrainera la sauvegarde du fichier.

L'extrait de code suivant met en évidence ces deux mécanismes :

FileConfiguration reader = new PropertiesConfiguration(«test.properties»);
FileConfiguration writer = new PropertiesConfiguration("test.properties");
writer.setAutoSave(true);
reader.setReloadingStrategy(new FileChangedReloadingStrategy());
System.out.print(«Test d'existence de la clé nom : »);
System.out.println(reader.containsKey(«nom»));
System.out.println(«Le writer définit nom à beuss...»);
writer.setProperty(«nom», «beuss»);
System.out.print(«Valeur de nom pour le reader : »);
System.out.println(reader.getString(«nom»));

La sortie de cette portion de programme est la suivante (à la première exécution) :

Test d'existence de la clé nom : false
Le writer définit nom à beuss...
Valeur de nom pour le reader : beuss

On voit que la configuration est bien écrite et rechargée lorsque c'est nécessaire. Voici le contenu du fichier test.properties après l'exécution (il existait auparavant, mais était vide) :

# written by PropertiesConfiguration
# Thu Jun 30 21:05:24 CEST 2005
nom = beuss

Comme on le voit, il s'agit d'un fichier de configuration classique. Nous reparlerons de son format plus loin.

Divers autres paramètres peuvent être définis pour les configurations basées sur des fichiers, parmi ceux-ci citons le répertoire de base (pour les chemins relatifs) et l'encodage du fichier.

III-A. Fichier properties▲

<?xml version="1.0"?>
<!DOCTYPE properties SYSTEM «http://java.sun.com/dtd/properties.dtd»>
<properties>
</properties>

<entry key="cle">Valeur</entry>

III-B. Fichiers XML▲

<properties>
    <listeners>
        <listener>
            <name>l1</name>
        </listener>
        <listener>
            <name>l2</name>
            <param>
                <name>p1</name>
                <value>1</value>
            </param>
        </listener>
    </listeners>
    <writers>
        <writer>
            <name>w1</name>
        </writer>
    </writers>
</properties>

String wnom = conf.getString(«writers.writer.name»); // renvoie «w1»

String lnom = conf.getString(«listeners.listener(0).name»)

conf.getMaxIndex(«listeners.listener»); // Renvoie 1 dans notre exemple

<properties>
    <listeners>
        <listener name="l1" />
        <listener name="l2" alias="list2, listener2">
            <param name="p1" value="1"/>
        </listener>
    </listeners>
</properties>

String lnom = conf.getString(«listeners.listener(0).[@name]»)

String lnom = conf.getString(«listeners.listener(1).[@name](1)»)

IV-A. Base de données▲

DataSource ds = ...;
Configuration conf = 
    new DatabaseConfiguration(ds, "T_CONFIG", "NomConfig", "Cle", "Valeur", "NomDeLaConfiguration");

IV-B. JNDI▲

IV-C. Bean Dynamique▲

DynaBean bean = new ConfigurationDynaBean(new XMLConfiguration("config.xml"));

IV-D. Configuration Système▲

En plus de gérer des configurations stockées sous des formes diverses, l'API commons configuration offre une fonctionnalité intéressante consistant à fournir une vue unique de plusieurs configurations. Autrement dit, il est possible d'agréger plusieurs configurations de sources différentes et de les manipuler comme si elles n'étaient issues que d'une source. Ce procédé est mis en œuvre au moyen de la classe org.apache.commons.configuration.CompositeConfiguration.

Bien sûr, l'utilisation d'une configuration composite nécessite de renoncer aux spécificités des différentes configurations et de n'utiliser que celles définies dans l'interface org.apache.commons.Configuration. Néanmoins, l'ajout de configurations se faisant au coup par coup, il est possible de paramétrer chaque configuration (par exemple, activer le rechargement automatique d'une configuration basée sur un fichier) avant de l'ajouter à la vue.

La configuration obtenue est modifiable, cependant tout appel à la méthode setProperty ou addProperty est appliqué à la configuration passée au constructeur (appelée configuration en mémoire ou «in memory configuration»). Ainsi dans l'exemple suivant :

CompositeConfiguration conf =
    new CompositeConfiguration(new PropertiesConfiguration("config.properties"));
conf.addConfiguration(new XMLConfiguration(«config.xml»));
conf.addProperty(«couleur», «FF0000»);

C'est la PropertyConfiguration qui est modifiée par l'ajout de la propriété couleur. Lors d'un appel à clearProperty (et donc à setProperty), la propriété est supprimée de toutes les configurations. Lors de la demande d'une propriété, les différentes configurations sont interrogées dans l'ordre d'ajout (en commençant par la configuration en mémoire), la valeur renvoyée est celle stockée dans la première configuration qui contient la clé. Si l'on demande la liste des valeurs correspondant à une clé, toutes les configurations sont interrogées et chacune ajoute ses valeurs s'il y a lieu.

La classe CompositeConfiguration définit par ailleurs différentes méthodes permettant d'accéder aux configurations qu'elle contient ou de les modifier. Notez que lorsque vous accédez aux différentes configurations (via la méthode getConfiguration), la configuration en mémoire a l'indice zéro. Cette dernière est également accessible en utilisant la méthode getInMemoryConfiguration.

La seconde possibilité intéressante offerte par l'API commons configuration est la possibilité de créer des configurations dynamiques. Cela signifie que les sources des différentes configurations ne sont pas spécifiées dans le code source, mais dans un fichier XML. Ce fichier est analysé par la classe org.apache.commons.configuration.ConfigurationFactory qui va créer une CompositeConfiguration contenant toutes les configurations spécifiées dans le fichier. Voici un exemple de fichier de définition des sources de configuration :

<?xml version="1.0» encoding="ISO-8859-1"?>
<configuration>
    <override>
        <properties fileName="userprefs.properties"/>
        <properties fileName="default.properties"/>
    </override>
    <additional>
        <properties fileName="extensions.properties">
        <properties fileName="additionalexts.properties» optional="true">
    </additional>
</configuration>

Comme on le voit, ce fichier est composé de deux sections, nous y reviendrons plus tard. Chaque source de configuration est déclarée dans une balise qui lui est propre. La balise dépend du type de configuration.

Le chargement d'une configuration dynamique est assez simple, il suit le schéma suivant :

ConfigurationFactory factory = new ConfigurationFactory();
factory.setConfigurationURL(Main.class.getResource(«/config.xml»));
Configuration conf = factory.getConfiguration();

Il existe quatre balises correspondant aux quatre configurations supportées :

• properties : indique que la configuration à créer est une PropertiesConfiguration, l'attribut fileName spécifie le fichier à utiliser ;
• xml ou hierarchicalXml : crée une configuration XML à partir du fichier spécifié par l'attribut fileName. L'utilisation de la première forme est préférable pour une question de cohérence (la classe HierarchicalXMLConfiguration est deprecated et a été remplacée par XMLConfiguration) ;
• jndi : demande à la ConfigurationFactory de créer une configuration JNDI ;
• system : crée une SystemConfiguration.

Toutes les balises concernant des configurations basées sur des fichiers acceptent l'attribut optional auquel doit être assignée une valeur booléenne (true/false, yes/no, on/off) indiquant si la configuration est optionnelle ou non. Par défaut, cet attribut est à false ce qui signifie que l'absence du fichier de configuration indiqué dans la balise fileName soulève une ConfigurationException.

Revenons maintenant aux deux parties composant le fichier. Celles-ci indiquent la façon dont sont gérées les collisions, c'est-à-dire le comportement à adopter lorsqu'une même clé est définie dans plusieurs configurations.

Pour les configurations déclarées dans la partie override, les propriétés définies dans les premiers fichiers écrasent les suivantes. Imaginons que userprefs.properties contienne une propriété appelée gui.font.color, si celle-ci est également définie dans default.properties seule la valeur déclarée dans userprefs.properties sera conservée. Cela permet par exemple de gérer les préférences utilisateurs, userprefs contient les préférences et default les valeurs par défaut, si une propriété n'est pas définie dans userprefs, c'est la valeur par défaut qui est prise, sinon, la valeur par défaut est tout simplement ignorée.

En ce qui concerne les configurations définies dans la section additional, elles sont toutes fusionnées en une seule configuration. Les propriétés en double sont combinées et il est possible d'y accéder via des indices (comme avec la XMLConfiguration). Si l'on dispose d'un premier fichier qui contient la valeur bleu pour la propriété gui.font.color et d'un autre qui contient la valeur rouge, conf.getString(«font.color(0)») renverra bleu et conf.getString(«font.color(1)») renverra rouge. Les balises de définition de configuration dans la section additional acceptent l'attribut at qui indique le point de raccordement dans la configuration additionnelle. Par exemple, si l'on dispose d'un fichier windowprefs et d'un fichier menuprefs contenant chacun la propriété font, on peut utiliser le fichier de configuration suivant :

<?xml version="1.0» encoding="ISO-8859-1"?>
<configuration>
    <additional>
        <properties fileName="windowprefs.properties» at="gui.window">
        <properties fileName="menuprefs.properties» at="gui.menu">
    </additional>
</configuration>

De cette façon, les deux propriétés citées précédemment seront accessibles via les clés gui.window.font et gui.menu.font, respectivement. Cela permet de décomposer un fichier en plusieurs petits fichiers et d'en simplifier la syntaxe (les clés sont moins longues).

VII-A. Décorateurs▲

DataConfiguration data = new DataConfiguration(new XMLConfiguration("config.xml"));
Locale loc = data.getLocale(«app.locale»);

Configuration windowConf = new SubsetConfiguration(globalConf, «gui.window», «.»);

Configuration windowConf = globalConf.subset(«gui.window»);

VII-B. Utilitaires▲

Vous en savez maintenant un peu plus sur l'API commons configuration. Essayez de l'appliquer à vos différents projets, vous verrez, elle devient vite indispensable. Bien que j'aie essayé de rendre cet article le plus complet possible, il peut rester des zones d'ombre ou des imprécisions, vous pouvez me contacter par MP pour avoir des précisions sur certains points (parcourez la javadoc avant) ou me signaler des erreurs.

Merci à adiGuba et vedaer pour leur relecture, à Gnux pour ses corrections.

• L' API commons configuration ;
• L'article au format HTML zippé (mirroir) ;
• L'article au format PDF (mirroir).