La classe EnumProperty

La classe capsis.util.EnumProperty propose une implémentation de variable énumération : une variable qui prend une valeur parmi n valeurs connues.

A chaque valeur (type int) correspond un nom (ex: “spruce”, “fir”) qui est une clé traductible dans la langue courante par le système de traduction Capsis Translator.swap (key).

Un nom pour le groupe de propriétés définit de quoi on parle, par exemple “Espèce” ou “Statut social”.

Les méthodes principales de EnumProperty sont les suivantes :

java.lang.String getPropertyName () Renvoie le nom du groupe de propriétés (ex: “Espèce”).

int getValue () Renvoie la valeur de la propriété (Ex: 0).

java.lang.String getName () Renvoie le nom de la propriété (Ex: Epicea).

Principe

Pour créer une variable pour coder l'espèce des arbres dans le module Samsara, on crée une classe SamsaSpecies qui hérite de EnumProperty. L'arbre SamsaTree possède une référence de type SamsaSpecies vers son espèce, avec des accesseurs associés setSpecies (…) et getSpecies ().

La classe SamsaSpecies doit être accompagnée de clés de traduction pour le nom du groupe de propriétés (ex: “SamsaSpecies.species” → “Espèce” / “Species”) ainsi que pour chaque nom d'espèce (ex: “SamsaSpecies.spruce” → “Epicea” / “Spruce”…). Ces traductions peuvent être dans des fichiers SamsaSpecies_fr.properties et SamsaSpecies_en.properties, ou bien ajoutées dans les fichiers de traduction des labels du module (SamsaLabels_fr/en.properties).

    public class SamsaSpecies extends EnumProperty implements Serializable, Cloneable {
        static {
            Translator.addBundle("samsara.model.SamsaSpecies");    // translations for names
        }
        public SamsaSpecies (int v, String name, EnumProperty model, String propertyName) {
            super (v, name, model, propertyName);
        }
        public String toString () {return Translator.swap (getName ());}
        public boolean equals (Object obj) {
            if (obj == null) {return false;}	// fc - 29.11.2001
            boolean equal = false;
            if (((SamsaSpecies) obj).getValue () == this.getValue ()) {
                equal = true;
            }
            return equal;
        }
    }

Lors de la lecture du fichier inventaire choisi pour la génération du peuplement initial dans un projet, on commence par construire les objets espèce (voir Construction).

Lors de la lecture des enregistrements arbres, on pourra reconnaitre l'espèce de l'arbre grâce à son code (type int) et relier chaque arbre instancié à son espèce. Pour cette étape, on pourra s'appuyer sur une méthode getSpecies (int value) qui renvoie l'instance d'espèce correspondant au code passé (voir Gestion des références).

Construction

A la construction, il faut porter attention au chaînage des EnumProperty entre elles. Ainsi par exemple, si on charge un fichier pour construire des instances d'espèces d'arbres, on pourra procéder approximativement de la manière suivante :

    // EnumProperty construction and chaining
    //
    SamsaSpecies prevSpecies = null;
    for (Iterator i = this.iterator (); i.hasNext ();) {
        SpeciesRecord sr = (SpeciesRecord) i.next ();    // a record read in the file
        SamsaSpecies s = new SamsaSpecies (
                sr.speciesValue, sr.speciesName,         // value and name ex: 0, "spruce"; 1, "fir"; 2, "other" (...)
                prevSpecies, "SamsaSpecies.species");    // previous species and name of the property group ex : "species"
        if (prevSpecies == null) {
            prevSpecies = s;
            // SamsaModel must know one Species to answer getSpecies (speciesValue)
            ((SamsaModel) model).setSpecimen (s);
        }
        ...
    }
Gestion des références

Il peut être utile de retrouver une instance d'EnumProperty à partir de sa valeur (int). Pour cela, on peut par exemple prévoir une méthode getSpecies (int value) dans la classe modèle du module Samsara, facilement accessible à tout moment. Cette méthode a besoin pour répondre de connaître une instance de SamsaSpecies (ces dernières étant liées les unes aux autres).

Pour positionner la référence à la première SamsaSpecies instanciée, on pourra utiiser une méthode setSpecimen (SamsaSpecies s) dans SamsaModel.

    public class SamsaModel extends GModel {
        ...
        private EnumProperty species;    // the specimen, to find its sisters
        ...
 
        /** Use this method when first species is built */
        public void setSpecimen (SamsaSpecies species) {this.species = species;}
 
        /** Use this method to retrieve a SamsaSpecies from its value
        *   (when constructing trees, to link them with their species)
        */
        public SamsaSpecies getSpecies (int speciesCode) {
            return (SamsaSpecies) species.getInfo ().getValueToProperty ().get (new Integer (speciesCode));
        }
 
        /** Optional method */
        public SamsaSpecies getSpecimen () {return (SamsaSpecies) species;}
    }
Intérêt

Les EnumProperty peuvent être détectées automatiquement par certains outils Capsis, par exemple :

* création de groupes automatiques au démarrage ou à la réouverture d'un projet sur les valeurs différentes des EnumProperty trouvées dans les arbres, * utilisation possible du filtre sur propriété qualitative pour créer des groupes interactivement sur les valeurs souhaitées et surveiller ainsi des populations différentes, * utilisation du même filtre dans l'extension “Eclaircie complexe” pour couper des arbres selon des règles définies interactivement par l'utilisateur, * possibilité de créer des histogrammes montrant les effectifs en arbres pour chaque valeur de la variable (ex : effectif par espèce).