Jakarta Commons Collections

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

Licence : CC-by-SA

Par Sébastien Le Ray (Accueil)
 

Nous continuons la série d'articles sur les API Commons du projet Apache Jakarta en nous intéressant aujourd'hui aux commons collections.

I. Introduction

II. Concepts

II.A. Design-Pattern Decorator

II.B. Décorateurs commons collections

Bag bagDecore = SynchronizedBag.decorate(new HashBag()); // Crée un nouveau Bag synchronisé

Bag bagDecore = BagUtils.synchronizedBag(new HashBag()); // Crée un nouveau Bag synchronisé

• Synchronized : La collection décorée voit toutes ses méthodes synchronisées(utile en environnement multi-threads) ;
• Unmodifiable : La collection décorée soulève une UnsupportedOperationException lors de l'appel à une quelconque méthode pouvant la modifier (utile pour les getters). Toutes les entités de ce type sont indirectement des instances de l'interface Unmodifiable ;
• Predicated : L'ajout d'un élément à la collection est soumis à sa conformance par rapport à un Predicat ;
• Typed : La collection décorée n'accepte que les éléments du type spécifié lors de sa décoration. Obsolète dans les versions de Java post 1.5 (apparition des templates). Si l'élément n'est pas du bon type, une IllegalArgumentException est levée ;
• Transformed : La collection décorée transforme les données avant l'ajout via le Transformer spécifié lors de sa décoration ;
• FixedSize : Empêche les ajouts/suppressions mais permet les modifications (ie set dans le cas d'une List, put si l'objet existe déjà pour une Map) ;
• Lazy : On précise une Factory qui crée un objet au moment de la demande (get) s'il n'existe pas.

	Bag	Buffer	Communs(1)	List	Map	BidiMap	Set
Synchronized			(2)	(2)	(2)		(2)
Unmodifiable			(2)	(2)	(2)		(2)
Predicated
Typed
Transformed
FixedSize
Lazy

• (1) : Utilise l'interface java.util.Collection, on perd les méthodes spécifiques.
• (2) : Disponible directement via JDK à partir de la version 1.4.

II.C. Catégories de sous-interfaces communes

III. Entités support

III.A. Comparator

• compare(Object o1, Object o2) : renvoie un entier inférieur à zéro si o1 < o2, zéro si o1 = o2 (au sens logique) et un entier supérieur à zéro si o1 > o2 ;
• equals(Object o) : renvoie true si l'autre objet est un comparateur qui implique le même ordre que celui pour lequel la méthode est appelée.

III.B. Comparable

IV. Functors

IV.A. Tranformer

IV.A.1. Implémentation utilisables directement

• CloneTransformer : Le résultat de la transformation est un clone de l'objet à transformer. L'objet doit posséder une méthode clone publique, avoir un constructeur par copie public (qui prend une instance de la classe en paramètre) ou implémenter java.io.Serializable ;
• ConstantTransformer : Le résultat de la transformation est toujours l'objet passé en paramètre au constructeur ;
• ExceptionTransformer : La transformation soulève toujours une FunctorException ;
• FactoryTransformer : Le résultat de la transformation est un objet créé par la Factory passée au constructeur ;
• InstantiateTransformer : Le résultat de la transformation est un nouvelle instance de l'objet créé en appelant son constructeur. Les types et les valeurs des paramètres sont passés au constructeur du Transformer ;
• InvokerTransformer : Le résultat de la transformation est l'objet renvoyé par une méthode de l'objet passé à transform. Le nom et les paramètres (types & valeurs) de la méthode sont précisés à la construction du Transformer ;
• MapTransformer : Le résultat de la transformation est la valeur obtenue par un get sur la Map passée au constructeur lorsque l'objet à transformer est utilisé comme clé ;
• NOPTransformer : Le résultat de la transformation est l'objet à transformer lui-même ;
• PredicateTransformer : Le résultat de la transformation est une instance de Boolean correspondant au résultat du Predicat passé en paramètre au constructeur ;
• StringValueTransformer : Le résultat de la transformation est la représentation de l'objet sous forme de String (par un appel à String.valueOf et donc à toString()).

La Javadoc contient une erreur pour PredicateTransformer et indique que c'est l'objet évalué qui est renvoyé !!!

IV.A.2. Décorateurs

• ChainedTransformer : Utilise le Design-Pattern "Chaîne de Responsabilités", c'est-à-dire qu'un premier Transformer est appelé, son résultat est passé à un second et ainsi de suite. Le résultat de la transformation est celui du dernier Transformer de la chaîne. Les Transformers à appliquer sont passés en paramètres au constructeur ;
• SwitchTransformer : Ce Transformer permet d'appliquer une transformation selon des Predicats, l'objet à transformer est évalué par une série de Predicats, lorsqu'un Predicat renvoie true, la transformation correspondante est appliquée. Si aucun Predicat ne renvoie true, une transformation par défaut est appliquée. Les Predicats et Transformers sont passés au constructeurs soit via une Map dont les clés sont les Predicats et les valeurs les Transformers (le Transformer par défaut a une clé null), soit via deux tableaux (le Transformer par défaut est un troisième paramètre).

IV.B. Predicate

IV.B.1. Implémentations utilisables directement

• EqualPredicate, IdentityPredicate : Les constructeurs de ces deux classes prennent un objet en paramètre. L'évaluation renvoie true si et seulement si l'objet passé à evaluate est egal au précédent (comparaison equals) ou identique (==) ;
• FalsePredicate, TruePredicate : L'évaluation renvoie toujours false ou toujours true, respectivement ;
• NullPredicate, NotNullPredicate : L'évaluation renvoie true selon que l'objet évalué est null ou non, respectivement ;
• ExceptionPredicate : L'évaluation soulève toujours une FunctorException ;
• InstanceOf : Le constructeur prend un objet de type Class, l'évaluation renvoie true si l'objet évalué est une instance de la classe passée au constructeur ;
• UniquePredicate : L'évaluation renvoie true si l'élément n'a pas déjà été évalué auparavant 
• TransformerPredicate est particulier, son constructeur prend en paramètre un Transformer qui renvoie une instance de Boolean et c'est le résultat de ce transformer qui est renvoyé.

IV.B.2. Décorateurs

• AnyPredicate décore un tableau de Predicates, l'évaluation renvoie true dès que l'un des Predicates décorés renvoie true. OrPredicate est l'équivalent mais le constructeur ne prend que deux Predicates ;
• AllPredicate décore un tableau de Predicats, l'évaluation renvoie true uniquement si tous les Predicats sont vérifiés. AndPredicate est l'équivalent mais le constructeur ne prend que deux Predicats ;
• NullIsTruePredicate, NullIsFalsePredicate et NullIsExceptionPredicate permettent de décorer un Predicat afin de paramétrer son comportement lorsqu'un élement null est évalué, comme leur nom l'indique, ils renverront true, false ou soulevèront une FunctorException, respectivement ;
• NonePredicate décore un tableau de Predicats, l'évaluation renvoie true uniquement si aucun des Predicats ne renvoie true ;
• NotPredicate décore un Predicat, l'évaluation renvoie l'inverse de celle du Predicat décoré ;
• OnePredicate décore un tableau de Predicats, l'évaluation renvoie true uniquement si un seul des Prédicats est vérifié (équivalent d'un ou exclusif) ;
• TransformedPredicate décore un Predicat et prend un Transformer en paramètre, celui-ci est appliqué à l'objet avant qu'il soit évalué par le Predicate décoré.

IV.C. Factory

• ConstantFactory : renvoie toujours l'objet qui a été passé au constructeur ;
• ExceptionFactory : l'appel à create soulève toujours une FunctorException ;
• InstantiateFactory : lors de l'appel à create, une nouvelle instance de la classe passée au constructeur est créée en appelant un constructeur qui prend en paramètres les différentes entités passées au constructeur de la Factory ;
• PrototypeFactory est utilisée pour obtenir une Factory qui renvoie des instances crées par duplication. Pour cela, la méthode getInstance prend un objet en paramètre (le prototype), c'est cet objet qui sera dupliqué lors de l'appel à create. Pour cela, le prototype doit diposer d'une méthode clone publique, d'un constructeur par copie public ou étendre l'interface java.io.Serializable. Selon ce qui est disponible, la Factory renvoyée par getInstance sera une PrototypeCloneFactory, une InstantiateFactory ou une PrototypeSerializationFactory.

V. Bag

• add(Object o, int nb) : Ajoute nb copies de l'objet dans le Bag, si le nombre à ajouter n'est pas précisé, n'ajoute qu'une seule copie. Si l'objet n'existait pas déjà dans le Bag renvoie true, false sinon. Ce n'est pas conforme aux spécifications de Collection ;
• containsAll(java.util.Collection c) : Renvoie true si le Bag contient tous les objets contenus dans c. Si un objet est présent n fois dans c, il doit l'être au moins n fois dans le Bag pour que la fonction renvoie true. Ce n'est pas conforme aux spécifications de Collection ;
• iterator() : Renvoie un itérateur qui parcourt toutes les copies contenues dans le Bag
• remove(Object o, int nb) : Retire nb copies de l'objet indiqué ou toutes les occurences si nb n'est pas précisé (Ce qui n'est pas conforme aux spécifications de Collection) ;
• removeAll(java.util.Collection c)/retainAll(java.util.Collection c) : Respectivement, supprime ou ne conserve que les éléments contenus dans c (si un élément est présent n fois dans c, il sera supprimé ou conservé n fois exactement). Ce n'est pas conforme aux spécifications de Collection ;
• size() : Renvoie le nombre d'éléments contenus dans le Bag, tient compte des objets identiques (ie. si un objet est présent plusieurs fois, il compte plusieurs fois).

• getCount(Object o) : Renvoie le nombre d'occurences de l'objet o dans le Bag ;
• uniqueSet() : Renvoie un java.util.Set qui ne contient qu'un exemplaire de chaque élément du Bag.

VI. BidiMap

• getKey(Object valeur) : renvoie la clé associée à la valeur passée en paramètre ou null si la clé n'existe pas ;
• inverseBidiMap() : les valeurs deviennent les clés et les clés les valeurs ;
• removeValue(Object valeur) : supprime la paire clé-valeur associée à la valeur.

VII. Buffer

• get() : renvoie le prochain objet, sans le supprimer ;
• remove() : renvoie et supprime le prochain objet.

• UnboundedFifoBuffer : file redimensionnée à la demande, au fur et à mesure des ajouts. L'accès et la suppresion se font en temps constant, l'ajout également sauf dans le cas du redimensionnement ;
• BoundedFifoBuffer : la taille de la file est définie une fois pour toute lors de la déclaration (32 par défaut). Lorsque la file est pleine (la méthode isFull permet de savoir si c'est le cas), toute tentative d'ajout soulève une BufferOverFlowException. La contrepartie est que les ajouts se font également en temps constant. Il est interdit d'ajouter des valeurs null au Buffer ;
• CircularFifoBuffer : type particulier de BoundedFifoBuffer, lorsque l'on ajoute un élément à un Buffer déjà plein, la première valeur est écrasée.

VIII. List

IX. Map

• CaseInsensitiveMap : Effectue une recherche par clé sans tenir compte de la casse (la méthode toString de la clé est utilisée) ;
• IdentityMap : Map dans laquelle la comparaison des clés se fait avec l'opérateur == au lieu de la méthode equals ;
• Flat3Map : Map optimisée pour contenir trois éléments ou moins. Les performances sont entre 0 et 10% meilleures qu'une HashMap pour les gets et quatre fois plus pour les puts avec moins de
  trois élements. Au-delà de trois éléments, les performances sont 5% moins bonnes ;
• LRUMap : Map de taille fixe (par défaut 100 éléments). Lorsqu'un élément est ajouté alors que la Map est pleine, l'élément qui n'a pas été utilisé depuis le plus longtemps (Least Recently Used) est supprimé. Seules les opérations put et get mettent à jour l'utilisation d'un élément.
• MultiKeyMap : Map dans laquelle les objets sont identifiés par un ensemble de clés. Il est possible de passer les objets constituant la clé directement à put ou à get (jusqu'à cinq objets) ou d'utiliser la classe MultiKey qui permet de créer une clé composée d'un nombre arbitraire d'objets (les méthodes put et get avec respectivement deux et un paramètre n'accepte qu'une instance de cette classe en tant que clé) ;
• SingletonMap : Map conçue pour ne contenir qu'une seule paire clé/valeur, toute tentative de suppression se solde par une UnsupportedOperationException. La méthode put n'est autorisée que si elle concerne la clé déjà présente ;
• StaticBucketMap : Map destinée aux environnements multi-threads, les méthodes sont synchronisées tout en minimisant l'impact sur les performances. La contrepartie est que les méthodes putAll et retainAll ne sont pas atomiques et se comportent de façon aléatoire lorsqu'elles sont utilisées en concurrence ;
• BeanMap : Cette Map prend un objet en constructeur (censé être un Bean). Les appels à get et put sont en fait relayés vers les méthodes getNomClé et setNomClé du Bean.

• CompositeMap : permet d'offir une vue unifiée de plusieurs Maps passées au constructeur ou à la méthode addComposited. Le constructeur peut prendre en plus une implémentation de CompositeMap.MapMutator qui définit le comportement à adopter lors de l'ajout d'une valeur ou lors de la présence d'une collision dans les clés des différentes Maps décorées ;
• ListOrderedMap : L'ordre de parcours de la Map décorée via un Iterator se fait dans l'ordre d'ajout.

X. Set

• CompositeSet : comme pour CompositeMap, offre une vue unifiée de plusieurs Set. Afin de gérer les collisions, une implémentation de CompositeSet.SetMutator doit être passée en paramètre, si ce n'est pas le cas, les opérations d'ajout soulèveront une UnsupportedOperationException. La méthode remove supprime le premier élément qu'elle trouve qui correspond à l'objet qu'on lui passe en paramètre ;
• ListOrderedSet : décorateur assurant que l'ordre d'ajout des éléments est utilisé pour l'itération ;
• MapBackedSet : permet de gérer une Map comme un Set. Les objets du Set sont les clés de la Map. Permet par exemple de créer un WeakSet à partir d'une WeakHashMap.

XI. Autres

XII. Remerciements

XIII. Téléchargements

• Les commons collections sont disponibles sur le site du projet Jakarta ;
• L'article au format HTML zippé (mirroir) ;
• L'article au format PDF (mirroir).