Jakarta Commons Configuration

Date de publication : 28/07/2005 , Date de mise a jour : 28/07/2005

Licence : CC-by-SA

Par Sébastien Le Ray (Accueil)
 

Cet article décrit les mécanismes et l'utilisation de l'API Commons Configuration du projet Jakarta.

I. Introduction

I.A. Contenu de l'API

I.B. Dépendances

II. Configuration de base

• 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.

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 !");
}

III. Configurations basées sur des fichiers

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"));

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

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

III.A. Fichier properties

III.A.1. Fichiers properties classiques

III.A.2. Fichiers properties XML

<?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. Autres types de configurations

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

V. Configuration Composite

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

VI. Configuration Dynamique

<?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>

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

• 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.

<?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>

VII. Décorateurs & Utilitaires

VII.A. Décorateurs

VII.A.1. Support de types supplémentaires

• Calendar ;
• Color ;
• Date ;
• Locale ;
• URL.

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

VII.A.2. Utilisation d'une Map comme configuration

VII.A.3. Sous ensembles d'une configuration

• via la classe org.apache.commons.configuration.SubsetConfiguration, son constructeur prend une Configuration, un préfixe qui correspond au préfixe ajouté à toutes les clés lors de l'interrogation et, éventuellement, un délimiteur qui correspond au délimiteur des différentes parties de la clé (concrètement, il sera inséré entre le préfixe et la clé demandée lors de l'interrogation de la Configuration décorée) ;
• via la méthode subset, celle-ci renvoie une Configuration (en fait une SubsetConfiguration) qui ne contient que les clés commençant par le préfixe indiqué, le séparateur utilisé est le point (.).

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

Configuration windowConf = globalConf.subset("gui.window");

VII.B. Utilitaires

VII.B.1. ConfigurationUtils

• append(Configuration source, Configuration cible) : permet d'ajouter tout le contenu de la configuration source à la configuration cible. Si une clé de la source existe déjà dans la configuration cible, les valeurs de la configuration source sont ajoutées sans écraser celles qui existaient auparavant ;
• copy(Configuration source, Configuration cible) : copie la source vers la cible, si une clé de la source existe déjà dans la configuration cible, les valeurs correspondantes sont écrasées ;
• dump(Configuration conf, PrintStream/PrintWriter out) : envoie tout le contenu de la configuration sous la forme clé = valeur vers le PrintStream ou le PrintWriter spécifié (par exemple System.out) ;
• toString(Configuration conf) : renvoie une chaine correspondant à la configuration passée en paramètre (forme clé = valeur).

• getFile : renvoie, si possible, un objet File correspondant au fichier dont le répertoire de base et le nom sont passés en paramètres (les URL sont gérées) ;
• getURL : renvoie, si possible, un objet URL correspondant au fichier dont le répertoire de base et le nom sont passés en paramètres ;
• locate : recherche le fichier dont le nom et le répertoire sont passés en paramètres dans le répertoire personnel de l'utilisateur, le classpath courant et le classpath système, si le fichier est introuvable, renvoie null.

VII.B.2. Encapsulation d'autres configurations

VIII. Conclusion

IX. Remerciements

X. Téléchargements

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