CompositeMap


1   /*
2    *  Copyright 2003-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.apache.commons.collections.map;
17  
18  import java.util.Collection  ;
19  import java.util.Iterator  ;
20  import java.util.Map  ;
21  import java.util.Set  ;
22  
23  import org.apache.commons.collections.CollectionUtils;
24  import org.apache.commons.collections.collection.CompositeCollection;
25  import org.apache.commons.collections.set.CompositeSet;
26  
27  /**
28   * Decorates a map of other maps to provide a single unified view.
29   * <p>
30   * Changes made to this map will actually be made on the decorated map.
31   * Add and remove operations require the use of a pluggable strategy. If no
32   * strategy is provided then add and remove are unsupported.
33   *
34   * @since Commons Collections 3.0
35   * @version $Revision: 1.7 $ $Date: 2004/02/18 01:13:19 $
36   *
37   * @author Brian McCallister
38   */
39  public class CompositeMap implements Map   {
40  
41      /** Array of all maps in the composite */
42      private Map  [] composite;
43  
44      /** Handle mutation operations */
45      private MapMutator mutator;
46  
47      /**
48       * Create a new, empty, CompositeMap.
49       */
50      public CompositeMap() {
51          this(new Map  []{}, null);
52      }
53  
54      /**
55       * Create a new CompositeMap with two composited Map instances.
56       * 
57       * @param one  the first Map to be composited
58       * @param two  the second Map to be composited
59       * @throws IllegalArgumentException if there is a key collision
60       */
61      public CompositeMap(Map   one, Map   two) {
62          this(new Map  []{one, two}, null);
63      }
64  
65      /**
66       * Create a new CompositeMap with two composited Map instances.
67       * 
68       * @param one  the first Map to be composited
69       * @param two  the second Map to be composited
70       * @param mutator  MapMutator to be used for mutation operations
71       */
72      public CompositeMap(Map   one, Map   two, MapMutator mutator) {
73          this(new Map  []{one, two}, mutator);
74      }
75  
76      /**
77       * Create a new CompositeMap which composites all of the Map instances in the
78       * argument. It copies the argument array, it does not use it directly.
79       * 
80       * @param composite  the Maps to be composited
81       * @throws IllegalArgumentException if there is a key collision
82       */
83      public CompositeMap(Map  [] composite) {
84          this(composite, null);
85      }
86  
87      /**
88       * Create a new CompositeMap which composites all of the Map instances in the
89       * argument. It copies the argument array, it does not use it directly.
90       * 
91       * @param composite  Maps to be composited
92       * @param mutator  MapMutator to be used for mutation operations
93       */
94      public CompositeMap(Map  [] composite, MapMutator mutator) {
95          this.mutator = mutator;
96          this.composite = new Map  [0];
97          for (int i = composite.length - 1; i >= 0; --i) {
98              this.addComposited(composite[i]);
99          }
100     }
101 
102     //-----------------------------------------------------------------------
103     /**
104      * Specify the MapMutator to be used by mutation operations.
105      * 
106      * @param mutator  the MapMutator to be used for mutation delegation
107      */
108     public void setMutator(MapMutator mutator) {
109         this.mutator = mutator;
110     }
111     
112     /**
113      * Add an additional Map to the composite.
114      *
115      * @param map  the Map to be added to the composite
116      * @throws IllegalArgumentException if there is a key collision and there is no
117      *         MapMutator set to handle it.
118      */
119     public synchronized void addComposited(Map   map) throws IllegalArgumentException   {
120         for (int i = composite.length - 1; i >= 0; --i) {
121             Collection   intersect = CollectionUtils.intersection(this.composite[i].keySet(), map.keySet());
122             if (intersect.size() != 0) {
123                 if (this.mutator == null) {
124                     throw new IllegalArgumentException  ("Key collision adding Map to CompositeMap");
125                 }
126                 else {
127                     this.mutator.resolveCollision(this, this.composite[i], map, intersect);
128                 }
129             }
130         }
131         Map  [] temp = new Map  [this.composite.length + 1];
132         System.arraycopy(this.composite, 0, temp, 0, this.composite.length);
133         temp[temp.length - 1] = map;
134         this.composite = temp;
135     }
136     
137     /**
138      * Remove a Map from the composite.
139      *
140      * @param map  the Map to be removed from the composite
141      * @return The removed Map or <code>null</code> if map is not in the composite
142      */
143     public synchronized Map   removeComposited(Map   map) {
144         int size = this.composite.length;
145         for (int i = 0; i < size; ++i) {
146             if (this.composite[i].equals(map)) {
147                 Map  [] temp = new Map  [size - 1];
148                 System.arraycopy(this.composite, 0, temp, 0, i);
149                 System.arraycopy(this.composite, i + 1, temp, i, size - i - 1);
150                 this.composite = temp;
151                 return map;
152             }
153         }
154         return null;
155     }
156 
157     //-----------------------------------------------------------------------    
158     /**
159      * Calls <code>clear()</code> on all composited Maps.
160      *
161      * @throws UnsupportedOperationException if any of the composited Maps do not support clear()
162      */
163     public void clear() {
164         for (int i = this.composite.length - 1; i >= 0; --i) {
165             this.composite[i].clear();
166         }
167     }
168     
169     /**
170      * Returns <tt>true</tt> if this map contains a mapping for the specified
171      * key.  More formally, returns <tt>true</tt> if and only if
172      * this map contains at a mapping for a key <tt>k</tt> such that
173      * <tt>(key==null ? k==null : key.equals(k))</tt>.  (There can be
174      * at most one such mapping.)
175      *
176      * @param key  key whose presence in this map is to be tested.
177      * @return <tt>true</tt> if this map contains a mapping for the specified
178      *         key.
179      *
180      * @throws ClassCastException if the key is of an inappropriate type for
181      *        this map (optional).
182      * @throws NullPointerException if the key is <tt>null</tt> and this map
183      *            does not not permit <tt>null</tt> keys (optional).
184      */
185     public boolean containsKey(Object   key) {
186         for (int i = this.composite.length - 1; i >= 0; --i) {
187             if (this.composite[i].containsKey(key)) {
188                 return true;
189             }
190         }
191         return false;
192     }
193     
194     /**
195      * Returns <tt>true</tt> if this map maps one or more keys to the
196      * specified value.  More formally, returns <tt>true</tt> if and only if
197      * this map contains at least one mapping to a value <tt>v</tt> such that
198      * <tt>(value==null ? v==null : value.equals(v))</tt>.  This operation
199      * will probably require time linear in the map size for most
200      * implementations of the <tt>Map</tt> interface.
201      *
202      * @param value value whose presence in this map is to be tested.
203      * @return <tt>true</tt> if this map maps one or more keys to the
204      *         specified value.
205      * @throws ClassCastException if the value is of an inappropriate type for
206      *        this map (optional).
207      * @throws NullPointerException if the value is <tt>null</tt> and this map
208      *            does not not permit <tt>null</tt> values (optional).
209      */
210     public boolean containsValue(Object   value) {
211         for (int i = this.composite.length - 1; i >= 0; --i) {
212             if (this.composite[i].containsValue(value)) {
213                 return true;
214             }
215         }
216         return false;
217     }
218     
219     /**
220      * Returns a set view of the mappings contained in this map.  Each element
221      * in the returned set is a <code>Map.Entry</code>.  The set is backed by the
222      * map, so changes to the map are reflected in the set, and vice-versa.
223      * If the map is modified while an iteration over the set is in progress,
224      * the results of the iteration are undefined.  The set supports element
225      * removal, which removes the corresponding mapping from the map, via the
226      * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, <tt>removeAll</tt>,
227      * <tt>retainAll</tt> and <tt>clear</tt> operations.  It does not support
228      * the <tt>add</tt> or <tt>addAll</tt> operations.
229      * <p>
230      * This implementation returns a <code>CompositeSet</code> which
231      * composites the entry sets from all of the composited maps.
232      *
233      * @see CompositeSet
234      * @return a set view of the mappings contained in this map.
235      */
236     public Set   entrySet() {
237         CompositeSet entries = new CompositeSet();
238         for (int i = this.composite.length - 1; i >= 0; --i) {
239             entries.addComposited(this.composite[i].entrySet());
240         }
241         return entries;
242     }
243     
244     /**
245      * Returns the value to which this map maps the specified key.  Returns
246      * <tt>null</tt> if the map contains no mapping for this key.  A return
247      * value of <tt>null</tt> does not <i>necessarily</i> indicate that the
248      * map contains no mapping for the key; it's also possible that the map
249      * explicitly maps the key to <tt>null</tt>.  The <tt>containsKey</tt>
250      * operation may be used to distinguish these two cases.
251      *
252      * <p>More formally, if this map contains a mapping from a key
253      * <tt>k</tt> to a value <tt>v</tt> such that <tt>(key==null ? k==null :
254      * key.equals(k))</tt>, then this method returns <tt>v</tt>; otherwise
255      * it returns <tt>null</tt>.  (There can be at most one such mapping.)
256      *
257      * @param key key whose associated value is to be returned.
258      * @return the value to which this map maps the specified key, or
259      *         <tt>null</tt> if the map contains no mapping for this key.
260      *
261      * @throws ClassCastException if the key is of an inappropriate type for
262      *        this map (optional).
263      * @throws NullPointerException key is <tt>null</tt> and this map does not
264      *        not permit <tt>null</tt> keys (optional).
265      *
266      * @see #containsKey(Object)
267      */
268     public Object   get(Object   key) {
269         for (int i = this.composite.length - 1; i >= 0; --i) {
270             if (this.composite[i].containsKey(key)) {
271                 return this.composite[i].get(key);
272             }
273         }
274         return null;
275     }
276     
277     /**
278      * Returns <tt>true</tt> if this map contains no key-value mappings.
279      *
280      * @return <tt>true</tt> if this map contains no key-value mappings.
281      */
282     public boolean isEmpty() {
283         for (int i = this.composite.length - 1; i >= 0; --i) {
284             if (!this.composite[i].isEmpty()) {
285                 return false;
286             }
287         }
288         return true;
289     }
290     
291     /**
292      * Returns a set view of the keys contained in this map.  The set is
293      * backed by the map, so changes to the map are reflected in the set, and
294      * vice-versa.  If the map is modified while an iteration over the set is
295      * in progress, the results of the iteration are undefined.  The set
296      * supports element removal, which removes the corresponding mapping from
297      * the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
298      * <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt> operations.
299      * It does not support the add or <tt>addAll</tt> operations.
300      * <p>
301      * This implementation returns a <code>CompositeSet</code> which
302      * composites the key sets from all of the composited maps.
303      *
304      * @return a set view of the keys contained in this map.
305      */
306     public Set   keySet() {
307         CompositeSet keys = new CompositeSet();
308         for (int i = this.composite.length - 1; i >= 0; --i) {
309             keys.addComposited(this.composite[i].keySet());
310         }
311         return keys;
312     }
313     
314     /**
315      * Associates the specified value with the specified key in this map
316      * (optional operation).  If the map previously contained a mapping for
317      * this key, the old value is replaced by the specified value.  (A map
318      * <tt>m</tt> is said to contain a mapping for a key <tt>k</tt> if and only
319      * if {@link #containsKey(Object) m.containsKey(k)} would return
320      * <tt>true</tt>.))
321      *
322      * @param key key with which the specified value is to be associated.
323      * @param value value to be associated with the specified key.
324      * @return previous value associated with specified key, or <tt>null</tt>
325      *         if there was no mapping for key.  A <tt>null</tt> return can
326      *         also indicate that the map previously associated <tt>null</tt>
327      *         with the specified key, if the implementation supports
328      *         <tt>null</tt> values.
329      *
330      * @throws UnsupportedOperationException if no MapMutator has been specified
331      * @throws ClassCastException if the class of the specified key or value
332      *            prevents it from being stored in this map.
333      * @throws IllegalArgumentException if some aspect of this key or value
334      *            prevents it from being stored in this map.
335      * @throws NullPointerException this map does not permit <tt>null</tt>
336      *            keys or values, and the specified key or value is
337      *            <tt>null</tt>.
338      */
339     public Object   put(Object   key, Object   value) {
340         if (this.mutator == null) {
341             throw new UnsupportedOperationException  ("No mutator specified");
342         }
343         return this.mutator.put(this, this.composite, key, value);
344     }
345     
346     /**
347      * Copies all of the mappings from the specified map to this map
348      * (optional operation).  The effect of this call is equivalent to that
349      * of calling {@link #put(Object,Object) put(k, v)} on this map once
350      * for each mapping from key <tt>k</tt> to value <tt>v</tt> in the
351      * specified map.  The behavior of this operation is unspecified if the
352      * specified map is modified while the operation is in progress.
353      *
354      * @param map Mappings to be stored in this map.
355      *
356      * @throws UnsupportedOperationException if the <tt>putAll</tt> method is
357      *        not supported by this map.
358      *
359      * @throws ClassCastException if the class of a key or value in the
360      *            specified map prevents it from being stored in this map.
361      *
362      * @throws IllegalArgumentException some aspect of a key or value in the
363      *            specified map prevents it from being stored in this map.
364      * @throws NullPointerException the specified map is <tt>null</tt>, or if
365      *         this map does not permit <tt>null</tt> keys or values, and the
366      *         specified map contains <tt>null</tt> keys or values.
367      */
368     public void putAll(Map   map) {
369         if (this.mutator == null) {
370             throw new UnsupportedOperationException  ("No mutator specified");
371         }
372         this.mutator.putAll(this, this.composite, map);
373     }
374     
375     /**
376      * Removes the mapping for this key from this map if it is present
377      * (optional operation).   More formally, if this map contains a mapping
378      * from key <tt>k</tt> to value <tt>v</tt> such that
379      * <code>(key==null ?  k==null : key.equals(k))</code>, that mapping
380      * is removed.  (The map can contain at most one such mapping.)
381      *
382      * <p>Returns the value to which the map previously associated the key, or
383      * <tt>null</tt> if the map contained no mapping for this key.  (A
384      * <tt>null</tt> return can also indicate that the map previously
385      * associated <tt>null</tt> with the specified key if the implementation
386      * supports <tt>null</tt> values.)  The map will not contain a mapping for
387      * the specified  key once the call returns.
388      *
389      * @param key key whose mapping is to be removed from the map.
390      * @return previous value associated with specified key, or <tt>null</tt>
391      *         if there was no mapping for key.
392      *
393      * @throws ClassCastException if the key is of an inappropriate type for
394      *        the composited map (optional).
395      * @throws NullPointerException if the key is <tt>null</tt> and the composited map
396      *            does not not permit <tt>null</tt> keys (optional).
397      * @throws UnsupportedOperationException if the <tt>remove</tt> method is
398      *         not supported by the composited map containing the key
399      */
400     public Object   remove(Object   key) {
401         for (int i = this.composite.length - 1; i >= 0; --i) {
402             if (this.composite[i].containsKey(key)) {
403                 return this.composite[i].remove(key);
404             }
405         }
406         return null;
407     }
408     
409     /**
410      * Returns the number of key-value mappings in this map.  If the
411      * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
412      * <tt>Integer.MAX_VALUE</tt>.
413      *
414      * @return the number of key-value mappings in this map.
415      */
416     public int size() {
417         int size = 0;
418         for (int i = this.composite.length - 1; i >= 0; --i) {
419             size += this.composite[i].size();
420         }
421         return size;
422     }
423     
424     /**
425      * Returns a collection view of the values contained in this map.  The
426      * collection is backed by the map, so changes to the map are reflected in
427      * the collection, and vice-versa.  If the map is modified while an
428      * iteration over the collection is in progress, the results of the
429      * iteration are undefined.  The collection supports element removal,
430      * which removes the corresponding mapping from the map, via the
431      * <tt>Iterator.remove</tt>, <tt>Collection.remove</tt>,
432      * <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt> operations.
433      * It does not support the add or <tt>addAll</tt> operations.
434      *
435      * @return a collection view of the values contained in this map.
436      */
437     public Collection   values() {
438         CompositeCollection keys = new CompositeCollection();
439         for (int i = this.composite.length - 1; i >= 0; --i) {
440             keys.addComposited(this.composite[i].values());
441         }
442         return keys;
443     }
444     
445     /**
446      * Checks if this Map equals another as per the Map specification.
447      * 
448      * @param obj  the object to compare to
449      * @return true if the maps are equal
450      */
451     public boolean equals(Object   obj) {
452         if (obj instanceof Map  ) {
453             Map   map = (Map  ) obj;
454             return (this.entrySet().equals(map.entrySet()));
455         }
456         return false;
457     }
458     
459     /**
460      * Gets a hash code for the Map as per the Map specification.
461      */
462     public int hashCode() {
463         int code = 0;
464         for (Iterator   i = this.entrySet().iterator(); i.hasNext();) {
465             code += i.next().hashCode();
466         }
467         return code;
468     }
469     
470     /**
471      * This interface allows definition for all of the indeterminate
472      * mutators in a CompositeMap, as well as providing a hook for
473      * callbacks on key collisions.
474      */
475     public static interface MapMutator {
476         /**
477          * Called when adding a new Composited Map results in a
478          * key collision.
479          *
480          * @param composite  the CompositeMap with the collision
481          * @param existing  the Map already in the composite which contains the
482          *        offending key
483          * @param added  the Map being added
484          * @param intersect  the intersection of the keysets of the existing and added maps
485          */
486         public void resolveCollision(
487             CompositeMap composite, Map   existing, Map   added, Collection   intersect);
488         
489         /**
490          * Called when the CompositeMap.put() method is invoked.
491          *
492          * @param map  the CompositeMap which is being modified
493          * @param composited  array of Maps in the CompositeMap being modified
494          * @param key  key with which the specified value is to be associated.
495          * @param value  value to be associated with the specified key.
496          * @return previous value associated with specified key, or <tt>null</tt>
497          *         if there was no mapping for key.  A <tt>null</tt> return can
498          *         also indicate that the map previously associated <tt>null</tt>
499          *         with the specified key, if the implementation supports
500          *         <tt>null</tt> values.
501          *
502          * @throws UnsupportedOperationException if not defined
503          * @throws ClassCastException if the class of the specified key or value
504          *            prevents it from being stored in this map.
505          * @throws IllegalArgumentException if some aspect of this key or value
506          *            prevents it from being stored in this map.
507          * @throws NullPointerException this map does not permit <tt>null</tt>
508          *            keys or values, and the specified key or value is
509          *            <tt>null</tt>.
510          */
511         public Object   put(CompositeMap map, Map  [] composited, Object   key, Object   value);
512         
513         /**
514          * Called when the CompositeMap.putAll() method is invoked.
515          *
516          * @param map  the CompositeMap which is being modified
517          * @param composited  array of Maps in the CompositeMap being modified
518          * @param mapToAdd  Mappings to be stored in this CompositeMap
519          *
520          * @throws UnsupportedOperationException if not defined
521          * @throws ClassCastException if the class of the specified key or value
522          *            prevents it from being stored in this map.
523          * @throws IllegalArgumentException if some aspect of this key or value
524          *            prevents it from being stored in this map.
525          * @throws NullPointerException this map does not permit <tt>null</tt>
526          *            keys or values, and the specified key or value is
527          *            <tt>null</tt>.
528          */
529         public void putAll(CompositeMap map, Map  [] composited, Map   mapToAdd);
530     }
531 }
532
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags