diff -r bf24e33c7919 -r 05676cfd40b5 jdk/src/java.management/share/classes/javax/management/openmbean/TabularDataSupport.java --- a/jdk/src/java.management/share/classes/javax/management/openmbean/TabularDataSupport.java Thu Aug 06 13:20:13 2015 +0300 +++ b/jdk/src/java.management/share/classes/javax/management/openmbean/TabularDataSupport.java Thu Aug 06 13:59:10 2015 +0300 @@ -51,8 +51,9 @@ /** - * The TabularDataSupport class is the open data class which implements the TabularData - * and the Map interfaces, and which is internally based on a hash map data structure. + * The {@code TabularDataSupport} class is the open data + * class which implements the {@code TabularData} + * and the {@code Map} interfaces, and which is internally based on a hash map data structure. * * @since 1.5 */ @@ -102,13 +103,15 @@ /** - * Creates an empty TabularDataSupport instance whose open-type is tabularType, - * and whose underlying HashMap has a default initial capacity (101) and default load factor (0.75). + * Creates an empty {@code TabularDataSupport} instance + * whose open-type is tabularType, + * and whose underlying {@code HashMap} has a default + * initial capacity (101) and default load factor (0.75). *

- * This constructor simply calls this(tabularType, 101, 0.75f); + * This constructor simply calls {@code this(tabularType, 101, 0.75f);} * - * @param tabularType the tabular type describing this TabularData instance; - * cannot be null. + * @param tabularType the tabular type describing this + * {@code TabularData} instance; cannot be null. * * @throws IllegalArgumentException if the tabular type is null. */ @@ -118,10 +121,10 @@ } /** - * Creates an empty TabularDataSupport instance whose open-type is tabularType, - * and whose underlying HashMap has the specified initial capacity and load factor. + * Creates an empty {@code TabularDataSupport} instance whose open-type is tabularType, + * and whose underlying {@code HashMap} has the specified initial capacity and load factor. * - * @param tabularType the tabular type describing this TabularData instance; + * @param tabularType the tabular type describing this {@code TabularData} instance; * cannot be null. * * @param initialCapacity the initial capacity of the HashMap. @@ -167,7 +170,7 @@ /** - * Returns the tabular type describing this TabularData instance. + * Returns the tabular type describing this {@code TabularData} instance. */ public TabularType getTabularType() { @@ -175,21 +178,22 @@ } /** - * Calculates the index that would be used in this TabularData instance to refer to the specified - * composite data value parameter if it were added to this instance. + * Calculates the index that would be used in this {@code TabularData} instance to refer + * to the specified composite data value parameter if it were added to this instance. * This method checks for the type validity of the specified value, - * but does not check if the calculated index is already used to refer to a value in this TabularData instance. + * but does not check if the calculated index is already used + * to refer to a value in this {@code TabularData} instance. * * @param value the composite data value whose index in this - * TabularData instance is to be calculated; + * {@code TabularData} instance is to be calculated; * must be of the same composite type as this instance's row type; * must not be null. * - * @return the index that the specified value would have in this TabularData instance. + * @return the index that the specified value would have in this {@code TabularData} instance. * - * @throws NullPointerException if value is null. + * @throws NullPointerException if value is {@code null}. * - * @throws InvalidOpenTypeException if value does not conform to this TabularData instance's + * @throws InvalidOpenTypeException if value does not conform to this {@code TabularData} instance's * row type definition. */ public Object[] calculateIndex(CompositeData value) { @@ -210,14 +214,14 @@ /** - * Returns true if and only if this TabularData instance contains a CompositeData value + * Returns {@code true} if and only if this {@code TabularData} instance contains a {@code CompositeData} value * (ie a row) whose index is the specified key. If key cannot be cast to a one dimension array - * of Object instances, this method simply returns false; otherwise it returns the result of the call to - * this.containsKey((Object[]) key). + * of Object instances, this method simply returns {@code false}; otherwise it returns the result of the call to + * {@code this.containsKey((Object[]) key)}. * - * @param key the index value whose presence in this TabularData instance is to be tested. + * @param key the index value whose presence in this {@code TabularData} instance is to be tested. * - * @return true if this TabularData indexes a row value with the specified key. + * @return {@code true} if this {@code TabularData} indexes a row value with the specified key. */ public boolean containsKey(Object key) { @@ -234,13 +238,13 @@ } /** - * Returns true if and only if this TabularData instance contains a CompositeData value - * (ie a row) whose index is the specified key. If key is null or does not conform to - * this TabularData instance's TabularType definition, this method simply returns false. + * Returns {@code true} if and only if this {@code TabularData} instance contains a {@code CompositeData} value + * (ie a row) whose index is the specified key. If key is {@code null} or does not conform to + * this {@code TabularData} instance's {@code TabularType} definition, this method simply returns {@code false}. * - * @param key the index value whose presence in this TabularData instance is to be tested. + * @param key the index value whose presence in this {@code TabularData} instance is to be tested. * - * @return true if this TabularData indexes a row value with the specified key. + * @return {@code true} if this {@code TabularData} indexes a row value with the specified key. */ public boolean containsKey(Object[] key) { @@ -248,13 +252,13 @@ } /** - * Returns true if and only if this TabularData instance contains the specified - * CompositeData value. If value is null or does not conform to - * this TabularData instance's row type definition, this method simply returns false. + * Returns {@code true} if and only if this {@code TabularData} instance contains the specified + * {@code CompositeData} value. If value is {@code null} or does not conform to + * this {@code TabularData} instance's row type definition, this method simply returns {@code false}. * - * @param value the row value whose presence in this TabularData instance is to be tested. + * @param value the row value whose presence in this {@code TabularData} instance is to be tested. * - * @return true if this TabularData instance contains the specified row value. + * @return {@code true} if this {@code TabularData} instance contains the specified row value. */ public boolean containsValue(CompositeData value) { @@ -262,12 +266,12 @@ } /** - * Returns true if and only if this TabularData instance contains the specified + * Returns {@code true} if and only if this {@code TabularData} instance contains the specified * value. * - * @param value the row value whose presence in this TabularData instance is to be tested. + * @param value the row value whose presence in this {@code TabularData} instance is to be tested. * - * @return true if this TabularData instance contains the specified row value. + * @return {@code true} if this {@code TabularData} instance contains the specified row value. */ public boolean containsValue(Object value) { @@ -275,12 +279,13 @@ } /** - * This method simply calls get((Object[]) key). + * This method simply calls {@code get((Object[]) key)}. * - * @throws NullPointerException if the key is null - * @throws ClassCastException if the key is not of the type Object[] - * @throws InvalidKeyException if the key does not conform to this TabularData instance's - * TabularType definition + * @throws NullPointerException if the key is {@code null} + * @throws ClassCastException if the key is not of the type {@code Object[]} + * @throws InvalidKeyException if the key does not conform + * to this {@code TabularData} instance's + * {@code TabularType} definition */ public Object get(Object key) { @@ -288,20 +293,21 @@ } /** - * Returns the CompositeData value whose index is - * key, or null if there is no value mapping - * to key, in this TabularData instance. + * Returns the {@code CompositeData} value whose index is + * key, or {@code null} if there is no value mapping + * to key, in this {@code TabularData} instance. * * @param key the index of the value to get in this - * TabularData instance; * must be valid with this - * TabularData instance's row type definition; * must not + * {@code TabularData} instance; must be valid with this + * {@code TabularData} instance's row type definition; must not * be null. * * @return the value corresponding to key. * - * @throws NullPointerException if the key is null - * @throws InvalidKeyException if the key does not conform to this TabularData instance's - * TabularType type definition. + * @throws NullPointerException if the key is {@code null} + * @throws InvalidKeyException if the key does not conform + * to this {@code TabularData} instance's + * {@code TabularType} type definition. */ public CompositeData get(Object[] key) { @@ -322,23 +328,23 @@ /** - * This method simply calls put((CompositeData) value) and - * therefore ignores its key parameter which can be null. + * This method simply calls {@code put((CompositeData) value)} and + * therefore ignores its key parameter which can be {@code null}. * * @param key an ignored parameter. * @param value the {@link CompositeData} to put. * * @return the value which is put * - * @throws NullPointerException if the value is null + * @throws NullPointerException if the value is {@code null} * @throws ClassCastException if the value is not of - * the type CompositeData + * the type {@code CompositeData} * @throws InvalidOpenTypeException if the value does - * not conform to this TabularData instance's - * TabularType definition + * not conform to this {@code TabularData} instance's + * {@code TabularType} definition * @throws KeyAlreadyExistsException if the key for the * value parameter, calculated according to this - * TabularData instance's TabularType definition + * {@code TabularData} instance's {@code TabularType} definition * already maps to an existing value */ public Object put(Object key, Object value) { @@ -363,17 +369,17 @@ } /** - * This method simply calls remove((Object[]) key). + * This method simply calls {@code remove((Object[]) key)}. * - * @param key an Object[] representing the key to remove. + * @param key an {@code Object[]} representing the key to remove. * - * @return previous value associated with specified key, or null + * @return previous value associated with specified key, or {@code null} * if there was no mapping for key. * - * @throws NullPointerException if the key is null - * @throws ClassCastException if the key is not of the type Object[] - * @throws InvalidKeyException if the key does not conform to this TabularData instance's - * TabularType definition + * @throws NullPointerException if the key is {@code null} + * @throws ClassCastException if the key is not of the type {@code Object[]} + * @throws InvalidKeyException if the key does not conform to this {@code TabularData} instance's + * {@code TabularType} definition */ public Object remove(Object key) { @@ -381,19 +387,19 @@ } /** - * Removes the CompositeData value whose index is key from this TabularData instance, - * and returns the removed value, or returns null if there is no value whose index is key. + * Removes the {@code CompositeData} value whose index is key from this {@code TabularData} instance, + * and returns the removed value, or returns {@code null} if there is no value whose index is key. * - * @param key the index of the value to get in this TabularData instance; - * must be valid with this TabularData instance's row type definition; + * @param key the index of the value to get in this {@code TabularData} instance; + * must be valid with this {@code TabularData} instance's row type definition; * must not be null. * - * @return previous value associated with specified key, or null + * @return previous value associated with specified key, or {@code null} * if there was no mapping for key. * - * @throws NullPointerException if the key is null - * @throws InvalidKeyException if the key does not conform to this TabularData instance's - * TabularType definition + * @throws NullPointerException if the key is {@code null} + * @throws InvalidKeyException if the key does not conform to this {@code TabularData} instance's + * {@code TabularType} definition */ public CompositeData remove(Object[] key) { @@ -414,30 +420,30 @@ /** * Add all the values contained in the specified map t - * to this TabularData instance. This method converts + * to this {@code TabularData} instance. This method converts * the collection of values contained in this map into an array of - * CompositeData values, if possible, and then call the - * method putAll(CompositeData[]). Note that the keys + * {@code CompositeData} values, if possible, and then call the + * method {@code putAll(CompositeData[])}. Note that the keys * used in the specified map t are ignored. This method * allows, for example to add the content of another - * TabularData instance with the same row type (but + * {@code TabularData} instance with the same row type (but * possibly different index names) into this instance. * * @param t the map whose values are to be added as new rows to - * this TabularData instance; if t is - * null or empty, this method returns without doing + * this {@code TabularData} instance; if t is + * {@code null} or empty, this method returns without doing * anything. * * @throws NullPointerException if a value in t is - * null. + * {@code null}. * @throws ClassCastException if a value in t is not an - * instance of CompositeData. + * instance of {@code CompositeData}. * @throws InvalidOpenTypeException if a value in t - * does not conform to this TabularData instance's row + * does not conform to this {@code TabularData} instance's row * type definition. * @throws KeyAlreadyExistsException if the index for a value in * t, calculated according to this - * TabularData instance's TabularType definition + * {@code TabularData} instance's {@code TabularType} definition * already maps to an existing value in this instance, or two * values in t have the same index. */ @@ -449,14 +455,14 @@ return; } - // Convert the values in t into an array of CompositeData + // Convert the values in t into an array of {@code CompositeData} // CompositeData[] values; try { values = t.values().toArray(new CompositeData[t.size()]); } catch (java.lang.ArrayStoreException e) { - throw new ClassCastException("Map argument t contains values which are not instances of CompositeData"); + throw new ClassCastException("Map argument t contains values which are not instances of {@code CompositeData}"); } // Add the array of values @@ -466,30 +472,30 @@ /** * Add all the elements in values to this - * TabularData instance. If any element in + * {@code TabularData} instance. If any element in * values does not satisfy the constraints defined in - * {@link #put(CompositeData) put}, or if any two + * {@link #put(CompositeData) put}, or if any two * elements in values have the same index calculated - * according to this TabularData instance's - * TabularType definition, then an exception describing + * according to this {@code TabularData} instance's + * {@code TabularType} definition, then an exception describing * the failure is thrown and no element of values is - * added, thus leaving this TabularData instance + * added, thus leaving this {@code TabularData} instance * unchanged. * * @param values the array of composite data values to be added as - * new rows to this TabularData instance; if - * values is null or empty, this method + * new rows to this {@code TabularData} instance; if + * values is {@code null} or empty, this method * returns without doing anything. * * @throws NullPointerException if an element of values - * is null + * is {@code null} * @throws InvalidOpenTypeException if an element of * values does not conform to this - * TabularData instance's row type definition (ie its - * TabularType definition) + * {@code TabularData} instance's row type definition (ie its + * {@code TabularType} definition) * @throws KeyAlreadyExistsException if the index for an element * of values, calculated according to this - * TabularData instance's TabularType definition + * {@code TabularData} instance's {@code TabularType} definition * already maps to an existing value in this instance, or two * elements of values have the same index */ @@ -529,7 +535,7 @@ } /** - * Removes all rows from this TabularDataSupport instance. + * Removes all rows from this {@code TabularDataSupport} instance. */ public void clear() { @@ -541,9 +547,9 @@ /* *** Informational methods from java.util.Map *** */ /** - * Returns the number of rows in this TabularDataSupport instance. + * Returns the number of rows in this {@code TabularDataSupport} instance. * - * @return the number of rows in this TabularDataSupport instance. + * @return the number of rows in this {@code TabularDataSupport} instance. */ public int size() { @@ -551,9 +557,9 @@ } /** - * Returns true if this TabularDataSupport instance contains no rows. + * Returns {@code true} if this {@code TabularDataSupport} instance contains no rows. * - * @return true if this TabularDataSupport instance contains no rows. + * @return {@code true} if this {@code TabularDataSupport} instance contains no rows. */ public boolean isEmpty() { @@ -656,9 +662,10 @@ /** - * Returns a clone of this TabularDataSupport instance: - * the clone is obtained by calling super.clone(), and then cloning the underlying map. - * 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. + * Returns a clone of this {@code TabularDataSupport} instance: + * the clone is obtained by calling {@code super.clone()}, and then cloning the underlying map. + * 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. */ /* We cannot use covariance here and return TabularDataSupport because this would fail with existing code that subclassed @@ -677,21 +684,21 @@ /** - * Compares the specified obj parameter with this TabularDataSupport instance for equality. + * Compares the specified obj parameter with this {@code TabularDataSupport} instance for equality. *

- * Returns true if and only if all of the following statements are true: + * Returns {@code true} if and only if all of the following statements are true: *

- * This ensures that this equals method works properly for obj parameters which are - * different implementations of the TabularData interface. + * This ensures that this {@code equals} method works properly for obj parameters which are + * different implementations of the {@code TabularData} interface. *
  - * @param obj the object to be compared for equality with this TabularDataSupport instance; + * @param obj the object to be compared for equality with this {@code TabularDataSupport} instance; * - * @return true if the specified object is equal to this TabularDataSupport instance. + * @return {@code true} if the specified object is equal to this {@code TabularDataSupport} instance. */ public boolean equals(Object obj) { @@ -738,22 +745,22 @@ } /** - * Returns the hash code value for this TabularDataSupport instance. + * Returns the hash code value for this {@code TabularDataSupport} instance. *

- * The hash code of a TabularDataSupport instance is the sum of the hash codes - * of all elements of information used in equals comparisons + * The hash code of a {@code TabularDataSupport} instance is the sum of the hash codes + * of all elements of information used in {@code equals} comparisons * (ie: its tabular type and its content, where the content is defined as all the CompositeData values). *

- * This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() - * for any two TabularDataSupport instances t1 and t2, + * This ensures that {@code t1.equals(t2)} implies that {@code t1.hashCode()==t2.hashCode()} + * for any two {@code TabularDataSupport} instances {@code t1} and {@code t2}, * as required by the general contract of the method * {@link Object#hashCode() Object.hashCode()}. *

- * However, note that another instance of a class implementing the TabularData interface - * may be equal to this TabularDataSupport instance as defined by {@link #equals}, + * However, note that another instance of a class implementing the {@code TabularData} interface + * may be equal to this {@code TabularDataSupport} instance as defined by {@link #equals}, * but may have a different hash code if it is calculated differently. * - * @return the hash code value for this TabularDataSupport instance + * @return the hash code value for this {@code TabularDataSupport} instance */ public int hashCode() { @@ -768,14 +775,15 @@ } /** - * Returns a string representation of this TabularDataSupport instance. + * Returns a string representation of this {@code TabularDataSupport} instance. *

- * The string representation consists of the name of this class (ie javax.management.openmbean.TabularDataSupport), + * The string representation consists of the name of this class + * (ie {@code javax.management.openmbean.TabularDataSupport}), * the string representation of the tabular type of this instance, and the string representation of the contents * (ie list the key=value mappings as returned by a call to - * dataMap.{@link java.util.HashMap#toString() toString()}). + * {@code dataMap.}{@link java.util.HashMap#toString() toString()}). * - * @return a string representation of this TabularDataSupport instance + * @return a string representation of this {@code TabularDataSupport} instance */ public String toString() { @@ -796,14 +804,17 @@ /** - * Returns the index for value, assuming value is valid for this TabularData instance + * Returns the index for value, assuming value is valid for this {@code TabularData} instance * (ie value is not null, and its composite type is equal to row type). * - * The index is a List, and not an array, so that an index.equals(otherIndex) call will actually compare contents, + * The index is a List, and not an array, so that an + * index.equals(otherIndex) call will actually compare contents, * not just the objects references as is done for an array object. * - * The returned List is unmodifiable so that once a row has been put into the dataMap, its index cannot be modified, - * for example by a user that would attempt to modify an index contained in the Set returned by keySet(). + * The returned List is unmodifiable so that once a row has been put + * into the dataMap, its index cannot be modified, + * for example by a user that would attempt to modify an + * index contained in the Set returned by keySet(). */ private List internalCalculateIndex(CompositeData value) { @@ -811,7 +822,7 @@ } /** - * Checks if the specified key is valid for this TabularData instance. + * Checks if the specified key is valid for this {@code TabularData} instance. * * @throws NullPointerException * @throws InvalidOpenTypeException @@ -848,7 +859,7 @@ } /** - * Checks the specified value's type is valid for this TabularData instance + * Checks the specified value's type is valid for this {@code TabularData} instance * (ie value is not null, and its composite type is equal to row type). * * @throws NullPointerException @@ -872,7 +883,7 @@ } /** - * Checks if the specified value can be put (ie added) in this TabularData instance + * Checks if the specified value can be put (ie added) in this {@code TabularData} instance * (ie value is not null, its composite type is equal to row type, and its index is not already used), * and returns the index calculated for this value. *