1 /*

     2  * Copyright 2000-2007 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 

    27 package javax.management.openmbean;

    28 

    29 

    30 // java import

    31 //

    32 import java.io.IOException;

    33 import java.io.ObjectInputStream;

    34 import java.io.Serializable;

    35 import java.util.ArrayList;

    36 import java.util.Arrays;

    37 import java.util.Collection;

    38 import java.util.Collections;

    39 import java.util.HashMap;

    40 import java.util.Iterator;

    41 import java.util.List;

    42 import java.util.Map;

    43 import java.util.Set;

    44 

    45 // jmx import

    46 //

    47 

    48 

    49 /**

    50  * The <tt>TabularDataSupport</tt> class is the <i>open data</i> class which implements the <tt>TabularData</tt>

    51  * and the <tt>Map</tt> interfaces, and which is internally based on a hash map data structure.

    52  *

    53  * @since 1.5

    54  */

    55 /* It would make much more sense to implement

    56    Map<List<?>,CompositeData> here, but unfortunately we cannot for

    57    compatibility reasons.  If we did that, then we would have to

    58    define e.g.

    59    CompositeData remove(Object)

    60    instead of

    61    Object remove(Object).

    62 

    63    That would mean that if any existing code subclassed

    64    TabularDataSupport and overrode

    65    Object remove(Object),

    66    it would (a) no longer compile and (b) not actually override

    67    CompositeData remove(Object)

    68    in binaries compiled before the change.

    69 */

    70 public class TabularDataSupport

    71     implements TabularData, Map<Object,Object>,

    72                Cloneable, Serializable {

    73 

    74 

    75     /* Serial version */

    76     static final long serialVersionUID = 5720150593236309827L;

    77 

    78 

    79     /**

    80      * @serial This tabular data instance's contents: a {@link HashMap}

    81      */

    82     private Map<Object,CompositeData> dataMap;

    83 

    84     /**

    85      * @serial This tabular data instance's tabular type

    86      */

    87     private TabularType tabularType;

    88 

    89     /**

    90      * The array of item names that define the index used for rows (convenience field)

    91      */

    92     private transient String[] indexNamesArray;

    93 

    94 

    95 

    96     /* *** Constructors *** */

    97 

    98 

    99     /**

   100      * Creates an empty <tt>TabularDataSupport</tt> instance whose open-type is <var>tabularType</var>,

   101      * and whose underlying <tt>HashMap</tt> has a default initial capacity (101) and default load factor (0.75).

   102      * <p>

   103      * This constructor simply calls <tt>this(tabularType, 101, 0.75f);</tt>

   104      *

   105      * @param  tabularType               the <i>tabular type</i> describing this <tt>TabularData</tt> instance;

   106      *                                   cannot be null.

   107      *

   108      * @throws IllegalArgumentException  if the tabular type is null.

   109      */

   110     public TabularDataSupport(TabularType tabularType) {

   111 

   112         this(tabularType, 101, 0.75f);

   113     }

   114 

   115     /**

   116      * Creates an empty <tt>TabularDataSupport</tt> instance whose open-type is <var>tabularType</var>,

   117      * and whose underlying <tt>HashMap</tt> has the specified initial capacity and load factor.

   118      *

   119      * @param  tabularType               the <i>tabular type</i> describing this <tt>TabularData</tt> instance;

   120      *                           cannot be null.

   121      *

   122      * @param  initialCapacity   the initial capacity of the HashMap.

   123      *

   124      * @param  loadFactor        the load factor of the HashMap

   125      *

   126      * @throws IllegalArgumentException  if the initial capacity is less than zero,

   127      *                                   or the load factor is nonpositive,

   128      *                                   or the tabular type is null.

   129      */

   130     public TabularDataSupport(TabularType tabularType, int initialCapacity, float loadFactor) {

   131 

   132         // Check tabularType is not null

   133         //

   134         if (tabularType == null) {

   135             throw new IllegalArgumentException("Argument tabularType cannot be null.");

   136         }

   137 

   138         // Initialize this.tabularType (and indexNamesArray for convenience)

   139         //

   140         this.tabularType = tabularType;

   141         List<String> tmpNames = tabularType.getIndexNames();

   142         this.indexNamesArray = tmpNames.toArray(new String[tmpNames.size()]);

   143 

   144         // Construct the empty contents HashMap

   145         //

   146         this.dataMap =

   147             new HashMap<Object,CompositeData>(initialCapacity, loadFactor);

   148     }

   149 

   150 

   151 

   152 

   153     /* *** TabularData specific information methods *** */

   154 

   155 

   156     /**

   157      * Returns the <i>tabular type</i> describing this <tt>TabularData</tt> instance.

   158      */

   159     public TabularType getTabularType() {

   160 

   161         return tabularType;

   162     }

   163 

   164     /**

   165      * Calculates the index that would be used in this <tt>TabularData</tt> instance to refer to the specified

   166      * composite data <var>value</var> parameter if it were added to this instance.

   167      * This method checks for the type validity of the specified <var>value</var>,

   168      * but does not check if the calculated index is already used to refer to a value in this <tt>TabularData</tt> instance.

   169      *

   170      * @param  value                      the composite data value whose index in this

   171      *                                    <tt>TabularData</tt> instance is to be calculated;

   172      *                                    must be of the same composite type as this instance's row type;

   173      *                                    must not be null.

   174      *

   175      * @return the index that the specified <var>value</var> would have in this <tt>TabularData</tt> instance.

   176      *

   177      * @throws NullPointerException       if <var>value</var> is <tt>null</tt>.

   178      *

   179      * @throws InvalidOpenTypeException   if <var>value</var> does not conform to this <tt>TabularData</tt> instance's

   180      *                                    row type definition.

   181      */

   182     public Object[] calculateIndex(CompositeData value) {

   183 

   184         // Check value is valid

   185         //

   186         checkValueType(value);

   187 

   188         // Return its calculated index

   189         //

   190         return internalCalculateIndex(value).toArray();

   191     }

   192 

   193 

   194 

   195 

   196     /* *** Content information query methods *** */

   197 

   198 

   199     /**

   200      * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains a <tt>CompositeData</tt> value

   201      * (ie a row) whose index is the specified <var>key</var>. If <var>key</var> cannot be cast to a one dimension array

   202      * of Object instances, this method simply returns <tt>false</tt>; otherwise it returns the the result of the call to

   203      * <tt>this.containsKey((Object[]) key)</tt>.

   204      *

   205      * @param  key  the index value whose presence in this <tt>TabularData</tt> instance is to be tested.

   206      *

   207      * @return  <tt>true</tt> if this <tt>TabularData</tt> indexes a row value with the specified key.

   208      */

   209     public boolean containsKey(Object key) {

   210 

   211         // if key is not an array of Object instances, return false

   212         //

   213         Object[] k;

   214         try {

   215             k = (Object[]) key;

   216         } catch (ClassCastException e) {

   217             return false;

   218         }

   219 

   220         return  this.containsKey(k);

   221     }

   222 

   223     /**

   224      * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains a <tt>CompositeData</tt> value

   225      * (ie a row) whose index is the specified <var>key</var>. If <var>key</var> is <tt>null</tt> or does not conform to

   226      * this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition, this method simply returns <tt>false</tt>.

   227      *

   228      * @param  key  the index value whose presence in this <tt>TabularData</tt> instance is to be tested.

   229      *

   230      * @return  <tt>true</tt> if this <tt>TabularData</tt> indexes a row value with the specified key.

   231      */

   232     public boolean containsKey(Object[] key) {

   233 

   234         return  ( key == null ? false : dataMap.containsKey(Arrays.asList(key)));

   235     }

   236 

   237     /**

   238      * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains the specified

   239      * <tt>CompositeData</tt> value. If <var>value</var> is <tt>null</tt> or does not conform to

   240      * this <tt>TabularData</tt> instance's row type definition, this method simply returns <tt>false</tt>.

   241      *

   242      * @param  value  the row value whose presence in this <tt>TabularData</tt> instance is to be tested.

   243      *

   244      * @return  <tt>true</tt> if this <tt>TabularData</tt> instance contains the specified row value.

   245      */

   246     public boolean containsValue(CompositeData value) {

   247 

   248         return dataMap.containsValue(value);

   249     }

   250 

   251     /**

   252      * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains the specified

   253      * value.

   254      *

   255      * @param  value  the row value whose presence in this <tt>TabularData</tt> instance is to be tested.

   256      *

   257      * @return  <tt>true</tt> if this <tt>TabularData</tt> instance contains the specified row value.

   258      */

   259     public boolean containsValue(Object value) {

   260 

   261         return dataMap.containsValue(value);

   262     }

   263 

   264     /**

   265      * This method simply calls <tt>get((Object[]) key)</tt>.

   266      *

   267      * @throws NullPointerException  if the <var>key</var> is <tt>null</tt>

   268      * @throws ClassCastException    if the <var>key</var> is not of the type <tt>Object[]</tt>

   269      * @throws InvalidKeyException   if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's

   270      *                               <tt>TabularType</tt> definition

   271      */

   272     public Object get(Object key) {

   273 

   274         return get((Object[]) key);

   275     }

   276 

   277     /**

   278      * Returns the <tt>CompositeData</tt> value whose index is

   279      * <var>key</var>, or <tt>null</tt> if there is no value mapping

   280      * to <var>key</var>, in this <tt>TabularData</tt> instance.

   281      *

   282      * @param key the index of the value to get in this

   283      * <tt>TabularData</tt> instance; * must be valid with this

   284      * <tt>TabularData</tt> instance's row type definition; * must not

   285      * be null.

   286      *

   287      * @return the value corresponding to <var>key</var>.

   288      *

   289      * @throws NullPointerException  if the <var>key</var> is <tt>null</tt>

   290      * @throws InvalidKeyException   if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's

   291      *                               <tt>TabularType</tt> type definition.

   292      */

   293     public CompositeData get(Object[] key) {

   294 

   295         // Check key is not null and valid with tabularType

   296         // (throws NullPointerException, InvalidKeyException)

   297         //

   298         checkKeyType(key);

   299 

   300         // Return the mapping stored in the parent HashMap

   301         //

   302         return dataMap.get(Arrays.asList(key));

   303     }

   304 

   305 

   306 

   307 

   308     /* *** Content modification operations (one element at a time) *** */

   309 

   310 

   311     /**

   312      * This method simply calls <tt>put((CompositeData) value)</tt> and

   313      * therefore ignores its <var>key</var> parameter which can be <tt>null</tt>.

   314      *

   315      * @param key an ignored parameter.

   316      * @param value the {@link CompositeData} to put.

   317      *

   318      * @return the value which is put

   319      *

   320      * @throws NullPointerException  if the <var>value</var> is <tt>null</tt>

   321      * @throws ClassCastException if the <var>value</var> is not of

   322      * the type <tt>CompositeData</tt>

   323      * @throws InvalidOpenTypeException if the <var>value</var> does

   324      * not conform to this <tt>TabularData</tt> instance's

   325      * <tt>TabularType</tt> definition

   326      * @throws KeyAlreadyExistsException if the key for the

   327      * <var>value</var> parameter, calculated according to this

   328      * <tt>TabularData</tt> instance's <tt>TabularType</tt> definition

   329      * already maps to an existing value

   330      */

   331     public Object put(Object key, Object value) {

   332         internalPut((CompositeData) value);

   333         return value; // should be return internalPut(...); (5090566)

   334     }

   335 

   336     public void put(CompositeData value) {

   337         internalPut(value);

   338     }

   339 

   340     private CompositeData internalPut(CompositeData value) {

   341         // Check value is not null, value's type is the same as this instance's row type,

   342         // and calculate the value's index according to this instance's tabularType and

   343         // check it is not already used for a mapping in the parent HashMap

   344         //

   345         List<?> index = checkValueAndIndex(value);

   346 

   347         // store the (key, value) mapping in the dataMap HashMap

   348         //

   349         return dataMap.put(index, value);

   350     }

   351 

   352     /**

   353      * This method simply calls <tt>remove((Object[]) key)</tt>.

   354      *

   355      * @param key an <tt>Object[]</tt> representing the key to remove.

   356      *

   357      * @return previous value associated with specified key, or <tt>null</tt>

   358      *         if there was no mapping for key.

   359      *

   360      * @throws NullPointerException  if the <var>key</var> is <tt>null</tt>

   361      * @throws ClassCastException    if the <var>key</var> is not of the type <tt>Object[]</tt>

   362      * @throws InvalidKeyException   if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's

   363      *                               <tt>TabularType</tt> definition

   364      */

   365     public Object remove(Object key) {

   366 

   367         return remove((Object[]) key);

   368     }

   369 

   370     /**

   371      * Removes the <tt>CompositeData</tt> value whose index is <var>key</var> from this <tt>TabularData</tt> instance,

   372      * and returns the removed value, or returns <tt>null</tt> if there is no value whose index is <var>key</var>.

   373      *

   374      * @param  key  the index of the value to get in this <tt>TabularData</tt> instance;

   375      *              must be valid with this <tt>TabularData</tt> instance's row type definition;

   376      *              must not be null.

   377      *

   378      * @return previous value associated with specified key, or <tt>null</tt>

   379      *         if there was no mapping for key.

   380      *

   381      * @throws NullPointerException  if the <var>key</var> is <tt>null</tt>

   382      * @throws InvalidKeyException   if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's

   383      *                               <tt>TabularType</tt> definition

   384      */

   385     public CompositeData remove(Object[] key) {

   386 

   387         // Check key is not null and valid with tabularType

   388         // (throws NullPointerException, InvalidKeyException)

   389         //

   390         checkKeyType(key);

   391 

   392         // Removes the (key, value) mapping in the parent HashMap

   393         //

   394         return dataMap.remove(Arrays.asList(key));

   395     }

   396 

   397 

   398 

   399     /* ***   Content modification bulk operations   *** */

   400 

   401 

   402     /**

   403      * Add all the values contained in the specified map <var>t</var>

   404      * to this <tt>TabularData</tt> instance.  This method converts

   405      * the collection of values contained in this map into an array of

   406      * <tt>CompositeData</tt> values, if possible, and then call the

   407      * method <tt>putAll(CompositeData[])</tt>. Note that the keys

   408      * used in the specified map <var>t</var> are ignored. This method

   409      * allows, for example to add the content of another

   410      * <tt>TabularData</tt> instance with the same row type (but

   411      * possibly different index names) into this instance.

   412      *

   413      * @param t the map whose values are to be added as new rows to

   414      * this <tt>TabularData</tt> instance; if <var>t</var> is

   415      * <tt>null</tt> or empty, this method returns without doing

   416      * anything.

   417      *

   418      * @throws NullPointerException if a value in <var>t</var> is

   419      * <tt>null</tt>.

   420      * @throws ClassCastException if a value in <var>t</var> is not an

   421      * instance of <tt>CompositeData</tt>.

   422      * @throws InvalidOpenTypeException if a value in <var>t</var>

   423      * does not conform to this <tt>TabularData</tt> instance's row

   424      * type definition.

   425      * @throws KeyAlreadyExistsException if the index for a value in

   426      * <var>t</var>, calculated according to this

   427      * <tt>TabularData</tt> instance's <tt>TabularType</tt> definition

   428      * already maps to an existing value in this instance, or two

   429      * values in <var>t</var> have the same index.

   430      */

   431     public void putAll(Map<?,?> t) {

   432 

   433         // if t is null or empty, just return

   434         //

   435         if ( (t == null) || (t.size() == 0) ) {

   436             return;

   437         }

   438 

   439         // Convert the values in t into an array of <tt>CompositeData</tt>

   440         //

   441         CompositeData[] values;

   442         try {

   443             values =

   444                 t.values().toArray(new CompositeData[t.size()]);

   445         } catch (java.lang.ArrayStoreException e) {

   446             throw new ClassCastException("Map argument t contains values which are not instances of <tt>CompositeData</tt>");

   447         }

   448 

   449         // Add the array of values

   450         //

   451         putAll(values);

   452     }

   453 

   454     /**

   455      * Add all the elements in <var>values</var> to this

   456      * <tt>TabularData</tt> instance.  If any element in

   457      * <var>values</var> does not satisfy the constraints defined in

   458      * {@link #put(CompositeData) <tt>put</tt>}, or if any two

   459      * elements in <var>values</var> have the same index calculated

   460      * according to this <tt>TabularData</tt> instance's

   461      * <tt>TabularType</tt> definition, then an exception describing

   462      * the failure is thrown and no element of <var>values</var> is

   463      * added, thus leaving this <tt>TabularData</tt> instance

   464      * unchanged.

   465      *

   466      * @param values the array of composite data values to be added as

   467      * new rows to this <tt>TabularData</tt> instance; if

   468      * <var>values</var> is <tt>null</tt> or empty, this method

   469      * returns without doing anything.

   470      *

   471      * @throws NullPointerException if an element of <var>values</var>

   472      * is <tt>null</tt>

   473      * @throws InvalidOpenTypeException if an element of

   474      * <var>values</var> does not conform to this

   475      * <tt>TabularData</tt> instance's row type definition (ie its

   476      * <tt>TabularType</tt> definition)

   477      * @throws KeyAlreadyExistsException if the index for an element

   478      * of <var>values</var>, calculated according to this

   479      * <tt>TabularData</tt> instance's <tt>TabularType</tt> definition

   480      * already maps to an existing value in this instance, or two

   481      * elements of <var>values</var> have the same index

   482      */

   483     public void putAll(CompositeData[] values) {

   484 

   485         // if values is null or empty, just return

   486         //

   487         if ( (values == null) || (values.length == 0) ) {

   488             return;

   489         }

   490 

   491         // create the list of indexes corresponding to each value

   492         List<List<?>> indexes =

   493             new ArrayList<List<?>>(values.length + 1);

   494 

   495         // Check all elements in values and build index list

   496         //

   497         List<?> index;

   498         for (int i=0; i<values.length; i++) {

   499             // check value and calculate index

   500             index = checkValueAndIndex(values[i]);

   501             // check index is different of those previously calculated

   502             if (indexes.contains(index)) {

   503                 throw new KeyAlreadyExistsException("Argument elements values["+ i +"] and values["+ indexes.indexOf(index) +

   504                                                     "] have the same indexes, "+

   505                                                     "calculated according to this TabularData instance's tabularType.");

   506             }

   507             // add to index list

   508             indexes.add(index);

   509         }

   510 

   511         // store all (index, value) mappings in the dataMap HashMap

   512         //

   513         for (int i=0; i<values.length; i++) {

   514             dataMap.put(indexes.get(i), values[i]);

   515         }

   516     }

   517 

   518     /**

   519      * Removes all rows from this <code>TabularDataSupport</code> instance.

   520      */

   521     public void clear() {

   522 

   523         dataMap.clear();

   524     }

   525 

   526 

   527 

   528     /* ***  Informational methods from java.util.Map  *** */

   529 

   530     /**

   531      * Returns the number of rows in this <code>TabularDataSupport</code> instance.

   532      *

   533      * @return the number of rows in this <code>TabularDataSupport</code> instance.

   534      */

   535     public int size() {

   536 

   537         return dataMap.size();

   538     }

   539 

   540     /**

   541      * Returns <tt>true</tt> if this <code>TabularDataSupport</code> instance contains no rows.

   542      *

   543      * @return <tt>true</tt> if this <code>TabularDataSupport</code> instance contains no rows.

   544      */

   545     public boolean isEmpty() {

   546 

   547         return (this.size() == 0);

   548     }

   549 

   550 

   551 

   552     /* ***  Collection views from java.util.Map  *** */

   553 

   554     /**

   555      * Returns a set view of the keys contained in the underlying map of this

   556      * {@code TabularDataSupport} instance used to index the rows.

   557      * Each key contained in this {@code Set} is an unmodifiable {@code List<?>}

   558      * so the returned set view is a {@code Set<List<?>>} but is declared as a

   559      * {@code Set<Object>} for compatibility reasons.

   560      * The set is backed by the underlying map of this

   561      * {@code TabularDataSupport} instance, so changes to the

   562      * {@code TabularDataSupport} instance are reflected in the

   563      * set, and vice-versa.

   564      *

   565      * The set supports element removal, which removes the corresponding

   566      * row from this {@code TabularDataSupport} instance, via the

   567      * {@link Iterator#remove}, {@link Set#remove}, {@link Set#removeAll},

   568      * {@link Set#retainAll}, and {@link Set#clear} operations. It does

   569      *  not support the {@link Set#add} or {@link Set#addAll} operations.

   570      *

   571      * @return a set view ({@code Set<List<?>>}) of the keys used to index

   572      * the rows of this {@code TabularDataSupport} instance.

   573      */

   574     public Set<Object> keySet() {

   575 

   576         return dataMap.keySet() ;

   577     }

   578 

   579     /**

   580      * Returns a collection view of the rows contained in this

   581      * {@code TabularDataSupport} instance. The returned {@code Collection}

   582      * is a {@code Collection<CompositeData>} but is declared as a

   583      * {@code Collection<Object>} for compatibility reasons.

   584      * The returned collection can be used to iterate over the values.

   585      * The collection is backed by the underlying map, so changes to the

   586      * {@code TabularDataSupport} instance are reflected in the collection,

   587      * and vice-versa.

   588      *

   589      * The collection supports element removal, which removes the corresponding

   590      * index to row mapping from this {@code TabularDataSupport} instance, via

   591      * the {@link Iterator#remove}, {@link Collection#remove},

   592      * {@link Collection#removeAll}, {@link Collection#retainAll},

   593      * and {@link Collection#clear} operations. It does not support

   594      * the {@link Collection#add} or {@link Collection#addAll} operations.

   595      *

   596      * @return a collection view ({@code Collection<CompositeData>}) of

   597      * the values contained in this {@code TabularDataSupport} instance.

   598      */

   599     @SuppressWarnings("unchecked")  // historical confusion about the return type

   600     public Collection<Object> values() {

   601 

   602         return (Collection) dataMap.values() ;

   603     }

   604 

   605 

   606     /**

   607      * Returns a collection view of the index to row mappings

   608      * contained in this {@code TabularDataSupport} instance.

   609      * Each element in the returned collection is

   610      * a {@code Map.Entry<List<?>,CompositeData>} but

   611      * is declared as a {@code Map.Entry<Object,Object>}

   612      * for compatibility reasons. Each of the map entry

   613      * keys is an unmodifiable {@code List<?>}.

   614      * The collection is backed by the underlying map of this

   615      * {@code TabularDataSupport} instance, so changes to the

   616      * {@code TabularDataSupport} instance are reflected in

   617      * the collection, and vice-versa.

   618      * The collection supports element removal, which removes

   619      * the corresponding mapping from the map, via the

   620      * {@link Iterator#remove}, {@link Collection#remove},

   621      * {@link Collection#removeAll}, {@link Collection#retainAll},

   622      * and {@link Collection#clear} operations. It does not support

   623      * the {@link Collection#add} or {@link Collection#addAll}

   624      * operations.

   625      * <p>

   626      * <b>IMPORTANT NOTICE</b>: Do not use the {@code setValue} method of the

   627      * {@code Map.Entry} elements contained in the returned collection view.

   628      * Doing so would corrupt the index to row mappings contained in this

   629      * {@code TabularDataSupport} instance.

   630      *

   631      * @return a collection view ({@code Set<Map.Entry<List<?>,CompositeData>>})

   632      * of the mappings contained in this map.

   633      * @see java.util.Map.Entry

   634      */

   635     @SuppressWarnings("unchecked")  // historical confusion about the return type

   636     public Set<Map.Entry<Object,Object>> entrySet() {

   637 

   638         return (Set) dataMap.entrySet();

   639     }

   640 

   641 

   642     /* ***  Commodity methods from java.lang.Object  *** */

   643 

   644 

   645     /**

   646      * Returns a clone of this <code>TabularDataSupport</code> instance:

   647      * the clone is obtained by calling <tt>super.clone()</tt>, and then cloning the underlying map.

   648      * Only a shallow clone of the underlying map is made, i.e. no cloning of the indexes and row values is made as they are immutable.

   649      */

   650     /* We cannot use covariance here and return TabularDataSupport

   651        because this would fail with existing code that subclassed

   652        TabularDataSupport and overrode Object clone().  It would not

   653        override the new clone().  */

   654     public Object clone() {

   655         try {

   656             TabularDataSupport c = (TabularDataSupport) super.clone();

   657             c.dataMap = new HashMap<Object,CompositeData>(c.dataMap);

   658             return c;

   659         }

   660         catch (CloneNotSupportedException e) {

   661             throw new InternalError(e.toString());

   662         }

   663     }

   664 

   665 

   666     /**

   667      * Compares the specified <var>obj</var> parameter with this <code>TabularDataSupport</code> instance for equality.

   668      * <p>

   669      * Returns <tt>true</tt> if and only if all of the following statements are true:

   670      * <ul>

   671      * <li><var>obj</var> is non null,</li>

   672      * <li><var>obj</var> also implements the <code>TabularData</code> interface,</li>

   673      * <li>their tabular types are equal</li>

   674      * <li>their contents (ie all CompositeData values) are equal.</li>

   675      * </ul>

   676      * This ensures that this <tt>equals</tt> method works properly for <var>obj</var> parameters which are

   677      * different implementations of the <code>TabularData</code> interface.

   678      * <br>&nbsp;

   679      * @param  obj  the object to be compared for equality with this <code>TabularDataSupport</code> instance;

   680      *

   681      * @return  <code>true</code> if the specified object is equal to this <code>TabularDataSupport</code> instance.

   682      */

   683     public boolean equals(Object obj) {

   684 

   685         // if obj is null, return false

   686         //

   687         if (obj == null) {

   688             return false;

   689         }

   690 

   691         // if obj is not a TabularData, return false

   692         //

   693         TabularData other;

   694         try {

   695             other = (TabularData) obj;

   696         } catch (ClassCastException e) {

   697             return false;

   698         }

   699 

   700         // Now, really test for equality between this TabularData implementation and the other:

   701         //

   702 

   703         // their tabularType should be equal

   704         if ( ! this.getTabularType().equals(other.getTabularType()) ) {

   705             return false;

   706         }

   707 

   708         // their contents should be equal:

   709         // . same size

   710         // . values in this instance are in the other (we know there are no duplicate elements possible)

   711         // (row values comparison is enough, because keys are calculated according to tabularType)

   712 

   713         if (this.size() != other.size()) {

   714             return false;

   715         }

   716         for (Iterator iter = this.values().iterator(); iter.hasNext();  ) {

   717             CompositeData value = (CompositeData) iter.next();

   718             if ( ! other.containsValue(value) ) {

   719                 return false;

   720             }

   721         }

   722 

   723         // All tests for equality were successfull

   724         //

   725         return true;

   726     }

   727 

   728     /**

   729      * Returns the hash code value for this <code>TabularDataSupport</code> instance.

   730      * <p>

   731      * The hash code of a <code>TabularDataSupport</code> instance is the sum of the hash codes

   732      * of all elements of information used in <code>equals</code> comparisons

   733      * (ie: its <i>tabular type</i> and its content, where the content is defined as all the CompositeData values).

   734      * <p>

   735      * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code>

   736      * for any two <code>TabularDataSupport</code> instances <code>t1</code> and <code>t2</code>,

   737      * as required by the general contract of the method

   738      * {@link Object#hashCode() Object.hashCode()}.

   739      * <p>

   740      * However, note that another instance of a class implementing the <code>TabularData</code> interface

   741      * may be equal to this <code>TabularDataSupport</code> instance as defined by {@link #equals},

   742      * but may have a different hash code if it is calculated differently.

   743      *

   744      * @return  the hash code value for this <code>TabularDataSupport</code> instance

   745      */

   746    public int hashCode() {

   747 

   748         int result = 0;

   749 

   750         result += this.tabularType.hashCode();

   751         for (Iterator iter = this.values().iterator(); iter.hasNext();  ) {

   752             result += ((CompositeData)iter.next()).hashCode();

   753         }

   754 

   755         return result;

   756 

   757     }

   758 

   759     /**

   760      * Returns a string representation of this <code>TabularDataSupport</code> instance.

   761      * <p>

   762      * The string representation consists of the name of this class (ie <code>javax.management.openmbean.TabularDataSupport</code>),

   763      * the string representation of the tabular type of this instance, and the string representation of the contents

   764      * (ie list the key=value mappings as returned by a call to

   765      * <tt>dataMap.</tt>{@link java.util.HashMap#toString() toString()}).

   766      *

   767      * @return  a string representation of this <code>TabularDataSupport</code> instance

   768      */

   769     public String toString() {

   770 

   771         return new StringBuilder()

   772             .append(this.getClass().getName())

   773             .append("(tabularType=")

   774             .append(tabularType.toString())

   775             .append(",contents=")

   776             .append(dataMap.toString())

   777             .append(")")

   778             .toString();

   779     }

   780 

   781 

   782 

   783 

   784     /* *** TabularDataSupport internal utility methods *** */

   785 

   786 

   787     /**

   788      * Returns the index for value, assuming value is valid for this <tt>TabularData</tt> instance

   789      * (ie value is not null, and its composite type is equal to row type).

   790      *

   791      * The index is a List, and not an array, so that an index.equals(otherIndex) call will actually compare contents,

   792      * not just the objects references as is done for an array object.

   793      *

   794      * The returned List is unmodifiable so that once a row has been put into the dataMap, its index cannot be modified,

   795      * for example by a user that would attempt to modify an index contained in the Set returned by keySet().

   796      */

   797     private List<?> internalCalculateIndex(CompositeData value) {

   798 

   799         return Collections.unmodifiableList(Arrays.asList(value.getAll(this.indexNamesArray)));

   800     }

   801 

   802     /**

   803      * Checks if the specified key is valid for this <tt>TabularData</tt> instance.

   804      *

   805      * @throws  NullPointerException

   806      * @throws  InvalidOpenTypeException

   807      */

   808     private void checkKeyType(Object[] key) {

   809 

   810         // Check key is neither null nor empty

   811         //

   812         if ( (key == null) || (key.length == 0) ) {

   813             throw new NullPointerException("Argument key cannot be null or empty.");

   814         }

   815 

   816         /* Now check key is valid with tabularType index and row type definitions: */

   817 

   818         // key[] should have the size expected for an index

   819         //

   820         if (key.length != this.indexNamesArray.length) {

   821             throw new InvalidKeyException("Argument key's length="+ key.length +

   822                                           " is different from the number of item values, which is "+ indexNamesArray.length +

   823                                           ", specified for the indexing rows in this TabularData instance.");

   824         }

   825 

   826         // each element in key[] should be a value for its corresponding open type specified in rowType

   827         //

   828         OpenType<?> keyElementType;

   829         for (int i=0; i<key.length; i++) {

   830             keyElementType = tabularType.getRowType().getType(this.indexNamesArray[i]);

   831             if ( (key[i] != null) && (! keyElementType.isValue(key[i])) ) {

   832                 throw new InvalidKeyException("Argument element key["+ i +"] is not a value for the open type expected for "+

   833                                               "this element of the index, whose name is \""+ indexNamesArray[i] +

   834                                               "\" and whose open type is "+ keyElementType);

   835             }

   836         }

   837     }

   838 

   839     /**

   840      * Checks the specified value's type is valid for this <tt>TabularData</tt> instance

   841      * (ie value is not null, and its composite type is equal to row type).

   842      *

   843      * @throws  NullPointerException

   844      * @throws  InvalidOpenTypeException

   845      */

   846     private void checkValueType(CompositeData value) {

   847 

   848         // Check value is not null

   849         //

   850         if (value == null) {

   851             throw new NullPointerException("Argument value cannot be null.");

   852         }

   853 

   854         // if value's type is not the same as this instance's row type, throw InvalidOpenTypeException

   855         //

   856         if (!tabularType.getRowType().isValue(value)) {

   857             throw new InvalidOpenTypeException("Argument value's composite type ["+ value.getCompositeType() +

   858                                                "] is not assignable to "+

   859                                                "this TabularData instance's row type ["+ tabularType.getRowType() +"].");

   860         }

   861     }

   862 

   863     /**

   864      * Checks if the specified value can be put (ie added) in this <tt>TabularData</tt> instance

   865      * (ie value is not null, its composite type is equal to row type, and its index is not already used),

   866      * and returns the index calculated for this value.

   867      *

   868      * The index is a List, and not an array, so that an index.equals(otherIndex) call will actually compare contents,

   869      * not just the objects references as is done for an array object.

   870      *

   871      * @throws  NullPointerException

   872      * @throws  InvalidOpenTypeException

   873      * @throws  KeyAlreadyExistsException

   874      */

   875     private List<?> checkValueAndIndex(CompositeData value) {

   876 

   877         // Check value is valid

   878         //

   879         checkValueType(value);

   880 

   881         // Calculate value's index according to this instance's tabularType

   882         // and check it is not already used for a mapping in the parent HashMap

   883         //

   884         List<?> index = internalCalculateIndex(value);

   885 

   886         if (dataMap.containsKey(index)) {

   887             throw new KeyAlreadyExistsException("Argument value's index, calculated according to this TabularData "+

   888                                                 "instance's tabularType, already refers to a value in this table.");

   889         }

   890 

   891         // The check is OK, so return the index

   892         //

   893         return index;

   894     }

   895 

   896     /**

   897      * Deserializes a {@link TabularDataSupport} from an {@link ObjectInputStream}.

   898      */

   899     private void readObject(ObjectInputStream in)

   900             throws IOException, ClassNotFoundException {

   901       in.defaultReadObject();

   902       List<String> tmpNames = tabularType.getIndexNames();

   903       indexNamesArray = tmpNames.toArray(new String[tmpNames.size()]);

   904     }

   905 }