001    /* TabularDataSupport.java -- Tables of composite data structures.
002       Copyright (C) 2006, 2007 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.management.openmbean;
039    
040    import java.io.Serializable;
041    
042    import java.util.ArrayList;
043    import java.util.Collection;
044    import java.util.HashMap;
045    import java.util.Iterator;
046    import java.util.List;
047    import java.util.Map;
048    import java.util.Set;
049    
050    /**
051     * Provides an implementation of the {@link TabularData}
052     * interface using a {@link java.util.HashMap}.
053     *
054     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
055     * @since 1.5
056     */
057    public class TabularDataSupport
058      implements TabularData, Serializable, Cloneable, Map<Object,Object>
059    {
060    
061      /**
062       * Compatible with JDK 1.5
063       */
064      private static final long serialVersionUID = 5720150593236309827L;
065    
066      /**
067       * Mapping of rows to column values.
068       *
069       * @serial the map of rows to column values.
070       */
071      private Map<Object,Object> dataMap;
072    
073      /**
074       * The tabular type which represents this tabular data instance.
075       *
076       * @serial the type information for this instance.
077       */
078      private TabularType tabularType;
079    
080      /**
081       * Constructs a new empty {@link TabularDataSupport} with the
082       * specified type.  The type may not be null.  This constructor
083       * simply calls the other, with the default initial capacity of
084       * <code>101</code> and default load factor of <code>0.75</code>.
085       *
086       * @param type the tabular type of this tabular data instance.
087       * @throws IllegalArgumentException if <code>type</code> is
088       *                                  <code>null</code>.
089       */
090      public TabularDataSupport(TabularType type)
091      {
092        this(type, 101, 0.75f);
093      }
094    
095      /**
096       * Constructs a new empty {@link TabularDataSupport} with the
097       * specified type and the supplied initial capacity and load factor
098       * being used for the underlying {@link java.util.HashMap}.  The
099       * type may not be null and the initial capacity and load factor
100       * must be positive.
101       *
102       * @param type the tabular type of this tabular data instance.
103       * @param cap the initial capacity of the underlying map.
104       * @param lf the load factor of the underlying map.
105       * @throws IllegalArgumentException if <code>type</code> is
106       *                                  <code>null</code>, or
107       *                                  <code>cap</code> or
108       *                                  <code>lf</code> are
109       *                                  negative.
110       */
111      public TabularDataSupport(TabularType type, int cap, float lf)
112      {
113        if (type == null)
114          throw new IllegalArgumentException("The type may not be null.");
115        tabularType = type;
116        dataMap = new HashMap<Object,Object>(cap, lf);
117      }
118       
119      /**
120       * Calculates the index the specified {@link CompositeData} value
121       * would have, if it was to be added to this {@link TabularData}
122       * instance.  This method includes a check that the type of the
123       * given value is the same as the row type of this instance, but not
124       * a check for existing instances of the given value.  The value
125       * must also not be <code>null</code>.  Possible indices are
126       * selected by the {@link TabularType#getIndexNames()} method of
127       * this instance's tabular type.  The returned indices are the
128       * values of the fields in the supplied {@link CompositeData}
129       * instance that match the names given in the {@link TabularType}.
130       * 
131       * @param val the {@link CompositeData} value whose index should
132       *            be calculated.
133       * @return the index the value would take on, if it were to be added.
134       * @throws NullPointerException if the value is <code>null</code>.
135       * @throws InvalidOpenTypeException if the value does not match the
136       *                                  row type of this instance.
137       */
138      public Object[] calculateIndex(CompositeData val)
139      {
140        if (!(val.getCompositeType().equals(tabularType.getRowType())))
141          throw new InvalidOpenTypeException("The type of the given value " +
142                                             "does not match the row type " +
143                                             "of this instance.");
144        List indexNames = tabularType.getIndexNames();
145        List matchingIndicies = new ArrayList(indexNames.size());
146        Iterator it = indexNames.iterator();
147        while (it.hasNext())
148          {
149            String name = (String) it.next();
150            matchingIndicies.add(val.get(name));
151          }
152        return matchingIndicies.toArray();
153      }
154    
155      /**
156       * Removes all {@link CompositeData} values from the table.
157       */
158      public void clear()
159      {
160        dataMap.clear();
161      }
162    
163      /**
164       * Returns a shallow clone of the information, as obtained by the
165       * {@link Object} implementation of {@link Object#clone()}.  The map
166       * is also cloned, but it still references the same objects.
167       *
168       * @return a shallow clone of this {@link TabularDataSupport}.
169       */
170      public Object clone()
171      {
172        TabularDataSupport clone = null;
173        try
174          {
175            clone = (TabularDataSupport) super.clone();
176            clone.setMap((HashMap) ((HashMap) dataMap).clone());
177          }
178        catch (CloneNotSupportedException e)
179          {
180            /* This won't happen as we implement Cloneable */
181          }
182        return clone;
183      }
184    
185      /**
186       * Returns true iff this instance of the {@link TabularData} class
187       * contains a {@link CompositeData} value at the specified index.
188       * The method returns <code>false</code> if the given key can
189       * not be cast to an {@link java.lang.Object} array; otherwise
190       * it returns the result of {@link #containsKey(java.lang.Object[])}.
191       *
192       *
193       * @param key the key to test for.
194       * @return true if the key maps to a {@link CompositeData} value.
195       */
196      public boolean containsKey(Object key)
197      {
198        if (key instanceof Object[])
199          return containsKey((Object[]) key);
200        else
201          return false;
202      }
203    
204      /**
205       * Returns true iff this instance of the {@link TabularData} class
206       * contains a {@link CompositeData} value at the specified index.
207       * In any other circumstance, including if the given key
208       * is <code>null</code> or of the incorrect type, according to
209       * the {@link TabularType} of this instance, this method returns
210       * false.
211       *
212       * @param key the key to test for.
213       * @return true if the key maps to a {@link CompositeData} value.
214       */
215      public boolean containsKey(Object[] key)
216      {
217        if (key == null)
218          return false;
219        if (!(isKeyValid(key)))
220          return false;
221        return dataMap.containsKey(key);
222      }
223    
224      /**
225       * Returns true iff this instance of the {@link TabularData} class
226       * contains the specified {@link CompositeData} value.  If the given
227       * value is not an instance of {@link CompositeData}, this method
228       * simply returns false.
229       *
230       * @param val the value to test for.
231       * @return true if the value exists.
232       */
233      public boolean containsValue(Object val)
234      {
235        if (val instanceof CompositeData)
236          return containsValue((CompositeData) val);
237        else
238          return false;
239      }
240    
241      /**
242       * Returns true iff this instance of the {@link TabularData} class
243       * contains the specified {@link CompositeData} value.
244       * In any other circumstance, including if the given value
245       * is <code>null</code> or of the incorrect type, according to
246       * the {@link TabularType} of this instance, this method returns
247       * false.
248       *
249       * @param val the value to test for.
250       * @return true if the value exists.
251       */
252      public boolean containsValue(CompositeData val)
253      {
254        if (val == null)
255          return false;
256        if (!(val.getCompositeType().equals(tabularType.getRowType())))
257          return false;
258        return dataMap.containsValue(val);
259      }
260    
261      /**
262       * <p>
263       * Returns a set view of the mappings in this Map.  Each element in the
264       * set is a Map.Entry.  The set is backed by the map, so that changes in
265       * one show up in the other.  Modifications made while an iterator is
266       * in progress cause undefined behavior.  If the set supports removal,
267       * these methods remove the underlying mapping from the map:
268       * <code>Iterator.remove</code>, <code>Set.remove</code>,
269       * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
270       * Element addition, via <code>add</code> or <code>addAll</code>, is
271       * not supported via this set.
272       * </p>
273       * <p>
274       * <strong>Note</strong>: using the
275       * {@link java.util.Map.Entry#setValue(Object) will cause corruption of
276       * the index to row mappings.
277       * </p>
278       *
279       * @return the set view of all mapping entries
280       * @see java.util.Map.Entry
281       */
282      public Set<Map.Entry<Object,Object>> entrySet()
283      {
284        return dataMap.entrySet();
285      }
286    
287      /**
288       * Compares the specified object with this object for equality.
289       * The object is judged equivalent if it is non-null, and also
290       * an instance of {@link TabularData} with the same row type,
291       * and {@link CompositeData} values.  The two compared instances may
292       * be equivalent even if they represent different implementations
293       * of {@link TabularData}.
294       *
295       * @param obj the object to compare for equality.
296       * @return true if <code>obj</code> is equal to <code>this</code>.
297       */
298      public boolean equals(Object obj)
299      {
300        if (!(obj instanceof TabularData))
301          return false;
302        TabularData data = (TabularData) obj;
303        return tabularType.equals(data.getTabularType()) &&
304          dataMap.values().equals(data.values());
305      }
306    
307      /**
308       * Retrieves the value for the specified key by simply
309       * calling <code>get((Object[]) key)</code>.
310       *
311       * @param key the key whose value should be returned.
312       * @return the matching {@link CompositeData} value, or
313       *         <code>null</code> if one does not exist.
314       * @throws NullPointerException if the key is <code>null</code>.
315       * @throws ClassCastException if the key is not an instance
316       *                            of <code>Object[]</code>.
317       * @throws InvalidKeyException if the key does not match
318       *                             the {@link TabularType} of this
319       *                             instance.
320       */
321      public Object get(Object key)
322      {
323        return get((Object[]) key);
324      }
325    
326      /**
327       * Retrieves the {@link CompositeData} value for the specified
328       * key, or <code>null</code> if no such mapping exists.
329       *
330       * @param key the key whose value should be returned.
331       * @return the matching {@link CompositeData} value, or
332       *         <code>null</code> if one does not exist.
333       * @throws NullPointerException if the key is <code>null</code>.
334       * @throws InvalidKeyException if the key does not match
335       *                             the {@link TabularType} of this
336       *                             instance.
337       */
338      public CompositeData get(Object[] key)
339      {
340        if (!(isKeyValid(key)))
341          throw new InvalidKeyException("The key does not match the " +
342                                        "tabular type of this instance.");
343        return (CompositeData) dataMap.get(key);
344      }
345    
346      /**
347       * Returns the tabular type which corresponds to this instance
348       * of {@link TabularData}.
349       *
350       * @return the tabular type for this instance.
351       */
352      public TabularType getTabularType()
353      {
354        return tabularType;
355      }
356    
357      /**
358       * Returns the hash code of the composite data type.  This is
359       * computed as the sum of the hash codes of each value, together
360       * with the hash code of the tabular type.  These are the same
361       * elements of the type that are compared as part of the {@link
362       * #equals(java.lang.Object)} method, thus ensuring that the
363       * hashcode is compatible with the equality test.
364       *
365       * @return the hash code of this instance.
366       */
367      public int hashCode()
368      {
369        return tabularType.hashCode() + dataMap.values().hashCode();
370      }
371    
372      /**
373       * Returns true if this {@link TabularData} instance
374       * contains no {@link CompositeData} values.
375       * 
376       * @return true if the instance is devoid of rows.
377       */
378      public boolean isEmpty()
379      {
380        return dataMap.isEmpty();
381      }
382    
383      /**
384       * Returns true if the given key is valid for the
385       * @link{TabularType} of this instance.
386       *
387       * @return true if the key is valid.
388       * @throws NullPointerException if <code>key</code>
389       *                              is null.
390       */
391      private boolean isKeyValid(Object[] key)
392      {
393        Iterator it = tabularType.getIndexNames().iterator();
394        CompositeType rowType = tabularType.getRowType();
395        for (int a = 0; it.hasNext(); ++a)
396          {
397            OpenType type = rowType.getType((String) it.next());
398            if (!(type.isValue(key[a])))
399              return false;
400          }
401        return true;
402      }
403    
404      /**
405       * Returns a set view of the keys in this Map.  The set is backed by the
406       * map, so that changes in one show up in the other.  Modifications made
407       * while an iterator is in progress cause undefined behavior.  If the set
408       * supports removal, these methods remove the underlying mapping from
409       * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
410       * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
411       * Element addition, via <code>add</code> or <code>addAll</code>, is
412       * not supported via this set.
413       *
414       * @return the set view of all keys
415       */
416      public Set<Object> keySet()
417      {
418        return dataMap.keySet();
419      }
420    
421      /**
422       * Adds the specified {@link CompositeData} value to the
423       * table.  The value must be non-null, of the same type
424       * as the row type of this instance, and must not have
425       * the same index as an existing value.  The index is
426       * calculated using the index names of the
427       * {@link TabularType} for this instance.
428       * 
429       * @param val the {@link CompositeData} value to add.
430       * @throws NullPointerException if <code>val</code> is
431       *                              <code>null</code>.
432       * @throws InvalidOpenTypeException if the type of the
433       *                                  given value does not
434       *                                  match the row type.
435       * @throws KeyAlreadyExistsException if the value has the
436       *                                   same calculated index
437       *                                   as an existing value.
438       */
439      public void put(CompositeData val)
440      {
441        Object[] key = calculateIndex(val);
442        if (dataMap.containsKey(key))
443          throw new KeyAlreadyExistsException("A value with this index " +
444                                              "already exists.");
445        dataMap.put(key, val);
446      }
447    
448      /**
449       * Adds the specified {@link CompositeData} value to the
450       * table, ignoring the supplied key, by simply calling
451       * <code>put((CompositeData) val)</code>.
452       *
453       * @param key ignored.
454       * @param val the {@link CompositeData} value to add.
455       * @return the {@link CompositeData} value.
456       * @throws NullPointerException if <code>val</code> is
457       *                              <code>null</code>.
458       * @throws InvalidOpenTypeException if the type of the
459       *                                  given value does not
460       *                                  match the row type.
461       * @throws KeyAlreadyExistsException if the value has the
462       *                                   same calculated index
463       *                                   as an existing value.
464       */
465      public Object put(Object key, Object val)
466      {
467        put((CompositeData) val);
468        return val;
469      }
470    
471      /**
472       * Adds each of the specified {@link CompositeData} values
473       * to the table.  Each element of the array must meet the
474       * conditions given for the {@link #put(CompositeData)}
475       * method.  In addition, the index of each value in the
476       * array must be distinct from the index of the other
477       * values in the array, as well as from the existing values
478       * in the table.  The operation should be atomic; if one
479       * value can not be added, then none of the values should
480       * be.  If the array is <code>null</code> or empty, the
481       * method simply returns.
482       * 
483       * @param vals the {@link CompositeData} values to add.
484       * @throws NullPointerException if a value from the array is
485       *                              <code>null</code>.
486       * @throws InvalidOpenTypeException if the type of a
487       *                                  given value does not
488       *                                  match the row type.
489       * @throws KeyAlreadyExistsException if a value has the
490       *                                   same calculated index
491       *                                   as an existing value or
492       *                                   of one of the other
493       *                                   specified values.
494       */
495      public void putAll(CompositeData[] vals)
496      {
497        if (vals == null || vals.length == 0)
498          return;
499        Map mapToAdd = new HashMap(vals.length);
500        for (int a = 0; a < vals.length; ++a)
501          {
502            Object[] key = calculateIndex(vals[a]);
503            if (dataMap.containsKey(key))
504              throw new KeyAlreadyExistsException("Element " + a + ": A " +
505                                                  "value with this index " +
506                                                  "already exists.");
507            mapToAdd.put(key, vals[a]);
508          }
509        dataMap.putAll(mapToAdd);
510      }
511    
512      /**
513       * Converts each value from the specified map to a member of an
514       * array of {@link CompositeData} values and adds them using {@link
515       * #put(CompositeData[])}, if possible.  As in {@link
516       * #put(Object,Object)}, the keys are simply ignored.  This method
517       * is useful for adding the {@link CompositeData} values from a
518       * different {@link TabularData} instance, which uses the same
519       * {@link TabularType} but a different selection of index names, to
520       * this one.  If the map is <code>null</code> or empty, the method
521       * simply returns.
522       *
523       * @param m the map to add.  Only the values are used and must
524       *          all be instances of {@link CompositeData}.
525       * @throws NullPointerException if a value from the map is
526       *                              <code>null</code>.
527       * @throws ClassCastException if a value from the map is not
528       *                            an instance of {@link CompositeData}.
529       * @throws InvalidOpenTypeException if the type of the
530       *                                  given value does not
531       *                                  match the row type.
532       * @throws KeyAlreadyExistsException if the value has the
533       *                                   same calculated index
534       *                                   as an existing value or
535       *                                   of one of the other
536       *                                   specified values.
537       */
538      public void putAll(Map<?,?> m)
539      {
540        if (m == null || m.size() == 0)
541          return;
542        Collection vals = m.values();
543        CompositeData[] data = new CompositeData[vals.size()];
544        Iterator it = vals.iterator();
545        for (int a = 0; it.hasNext(); ++a)
546          {
547            data[a] = (CompositeData) it.next();
548          }
549        putAll(data);
550      }
551    
552      /**
553       * Removes the value for the specified key by simply
554       * calling <code>remove((Object[]) key)</code>.
555       *
556       * @param key the key whose value should be removed.
557       * @return the removed value, or <code>null</code> if
558       *         there is no value for the given key.
559       * @throws NullPointerException if the key is <code>null</code>.
560       * @throws ClassCastException if the key is not an instance
561       *                            of <code>Object[]</code>.
562       * @throws InvalidOpenTypeException if the key does not match
563       *                                  the {@link TabularType} of this
564       *                                  instance.
565       */
566      public Object remove(Object key)
567      {
568        return remove((Object[]) key);
569      }
570    
571      /**
572       * Removes the {@link CompositeData} value located at the
573       * specified index.  <code>null</code> is returned if the
574       * value does not exist.  Otherwise, the removed value is
575       * returned.
576       *
577       * @param key the key of the value to remove.
578       * @return the removed value, or <code>null</code> if
579       *         there is no value for the given key.
580       * @throws NullPointerException if the key is <code>null</code>.
581       * @throws InvalidOpenTypeException if the key does not match
582       *                                  the {@link TabularType} of this
583       *                                  instance.
584       */
585      public CompositeData remove(Object[] key)
586      {
587        if (!(isKeyValid(key)))
588          throw new InvalidKeyException("The key does not match the " +
589                                        "tabular type of this instance.");
590        return (CompositeData) dataMap.remove(key);
591      }
592    
593      /**
594       * Package-private method to set the internal {@link java.util.Map}
595       * instance (used in cloning).
596       *
597       * @param map the new map used.
598       */
599      void setMap(Map map)
600      {
601        dataMap = map;
602      }
603    
604      /**
605       * Returns the number of {@link CompositeData} values or rows
606       * in the table.
607       *
608       * @return the number of rows in the table.
609       */
610      public int size()
611      {
612        return dataMap.size();
613      }
614    
615      /**
616       * Returns a textual representation of this instance.  This
617       * is constructed using the class name
618       * (<code>javax.management.openmbean.TabularDataSupport</code>)
619       * and the result of calling <code>toString()</code> on the
620       * tabular type and underlying hash map instance.
621       *
622       * @return a {@link java.lang.String} representation of the
623       *         object.
624       */
625      public String toString()
626      {
627        return getClass().getName()
628          + "[tabularType=" + tabularType 
629          + ",dataMap=" + dataMap
630          + "]";
631      }
632     
633      /**
634       * Returns a collection (or bag) view of the values in this Map.  The
635       * collection is backed by the map, so that changes in one show up in
636       * the other.  Modifications made while an iterator is in progress cause
637       * undefined behavior.  If the collection supports removal, these methods
638       * remove the underlying mapping from the map: <code>Iterator.remove</code>,
639       * <code>Collection.remove</code>, <code>removeAll</code>,
640       * <code>retainAll</code>, and <code>clear</code>. Element addition, via
641       * <code>add</code> or <code>addAll</code>, is not supported via this
642       * collection.
643       *
644       * @return the collection view of all values
645       */
646      public Collection<Object> values()
647      {
648        return dataMap.values();
649      }
650    
651    }
652