1 /*
   2  * Copyright (c) 2004, 2015, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.management;
  27 
  28 import com.sun.jmx.mbeanserver.Util;
  29 import java.io.InvalidObjectException;
  30 import java.lang.reflect.Array;
  31 import java.util.Arrays;
  32 import java.util.Comparator;
  33 import java.util.Map;
  34 import java.util.SortedMap;
  35 import java.util.TreeMap;
  36 
  37 /**
  38  * An immutable descriptor.
  39  * @since 1.6
  40  */
  41 public class ImmutableDescriptor implements Descriptor {
  42     private static final long serialVersionUID = 8853308591080540165L;
  43 
  44     /**
  45      * The names of the fields in this ImmutableDescriptor with their
  46      * original case.  The names must be in alphabetical order as determined
  47      * by {@link String#CASE_INSENSITIVE_ORDER}.
  48      */
  49     private final String[] names;
  50     /**
  51      * The values of the fields in this ImmutableDescriptor.  The
  52      * elements in this array match the corresponding elements in the
  53      * {@code names} array.
  54      */
  55     private final Object[] values;
  56 
  57     private transient int hashCode = -1;
  58 
  59     /**
  60      * An empty descriptor.
  61      */
  62     public static final ImmutableDescriptor EMPTY_DESCRIPTOR =
  63             new ImmutableDescriptor();
  64 
  65     /**
  66      * Construct a descriptor containing the given fields and values.
  67      *
  68      * @param fieldNames the field names
  69      * @param fieldValues the field values
  70      * @throws IllegalArgumentException if either array is null, or
  71      * if the arrays have different sizes, or
  72      * if a field name is null or empty, or if the same field name
  73      * appears more than once.
  74      */
  75     public ImmutableDescriptor(String[] fieldNames, Object[] fieldValues) {
  76         this(makeMap(fieldNames, fieldValues));
  77     }
  78 
  79     /**
  80      * Construct a descriptor containing the given fields.  Each String
  81      * must be of the form {@code fieldName=fieldValue}.  The field name
  82      * ends at the first {@code =} character; for example if the String
  83      * is {@code a=b=c} then the field name is {@code a} and its value
  84      * is {@code b=c}.
  85      *
  86      * @param fields the field names
  87      * @throws IllegalArgumentException if the parameter is null, or
  88      * if a field name is empty, or if the same field name appears
  89      * more than once, or if one of the strings does not contain
  90      * an {@code =} character.
  91      */
  92     public ImmutableDescriptor(String... fields) {
  93         this(makeMap(fields));
  94     }
  95 
  96     /**
  97      * <p>Construct a descriptor where the names and values of the fields
  98      * are the keys and values of the given Map.</p>
  99      *
 100      * @param fields the field names and values
 101      * @throws IllegalArgumentException if the parameter is null, or
 102      * if a field name is null or empty, or if the same field name appears
 103      * more than once (which can happen because field names are not case
 104      * sensitive).
 105      */
 106     public ImmutableDescriptor(Map<String, ?> fields) {
 107         if (fields == null)
 108             throw new IllegalArgumentException("Null Map");
 109         SortedMap<String, Object> map =
 110                 new TreeMap<String, Object>(String.CASE_INSENSITIVE_ORDER);
 111         for (Map.Entry<String, ?> entry : fields.entrySet()) {
 112             String name = entry.getKey();
 113             if (name == null || name.equals(""))
 114                 throw new IllegalArgumentException("Empty or null field name");
 115             if (map.containsKey(name))
 116                 throw new IllegalArgumentException("Duplicate name: " + name);
 117             map.put(name, entry.getValue());
 118         }
 119         int size = map.size();
 120         this.names = map.keySet().toArray(new String[size]);
 121         this.values = map.values().toArray(new Object[size]);
 122     }
 123 
 124     /**
 125      * This method can replace a deserialized instance of this
 126      * class with another instance.  For example, it might replace
 127      * a deserialized empty ImmutableDescriptor with
 128      * {@link #EMPTY_DESCRIPTOR}.
 129      *
 130      * @return the replacement object, which may be {@code this}.
 131      *
 132      * @throws InvalidObjectException if the read object has invalid fields.
 133      */
 134     private Object readResolve() throws InvalidObjectException {
 135 
 136         boolean bad = false;
 137         if (names == null || values == null || names.length != values.length)
 138             bad = true;
 139         if (!bad) {
 140             if (names.length == 0 && getClass() == ImmutableDescriptor.class)
 141                 return EMPTY_DESCRIPTOR;
 142             final Comparator<String> compare = String.CASE_INSENSITIVE_ORDER;
 143             String lastName = ""; // also catches illegal null name
 144             for (int i = 0; i < names.length; i++) {
 145                 if (names[i] == null ||
 146                         compare.compare(lastName, names[i]) >= 0) {
 147                     bad = true;
 148                     break;
 149                 }
 150                 lastName = names[i];
 151             }
 152         }
 153         if (bad)
 154             throw new InvalidObjectException("Bad names or values");
 155 
 156         return this;
 157     }
 158 
 159     private static SortedMap<String, ?> makeMap(String[] fieldNames,
 160                                                 Object[] fieldValues) {
 161         if (fieldNames == null || fieldValues == null)
 162             throw new IllegalArgumentException("Null array parameter");
 163         if (fieldNames.length != fieldValues.length)
 164             throw new IllegalArgumentException("Different size arrays");
 165         SortedMap<String, Object> map =
 166                 new TreeMap<String, Object>(String.CASE_INSENSITIVE_ORDER);
 167         for (int i = 0; i < fieldNames.length; i++) {
 168             String name = fieldNames[i];
 169             if (name == null || name.equals(""))
 170                 throw new IllegalArgumentException("Empty or null field name");
 171             Object old = map.put(name, fieldValues[i]);
 172             if (old != null) {
 173                 throw new IllegalArgumentException("Duplicate field name: " +
 174                                                    name);
 175             }
 176         }
 177         return map;
 178     }
 179 
 180     private static SortedMap<String, ?> makeMap(String[] fields) {
 181         if (fields == null)
 182             throw new IllegalArgumentException("Null fields parameter");
 183         String[] fieldNames = new String[fields.length];
 184         String[] fieldValues = new String[fields.length];
 185         for (int i = 0; i < fields.length; i++) {
 186             String field = fields[i];
 187             int eq = field.indexOf('=');
 188             if (eq < 0) {
 189                 throw new IllegalArgumentException("Missing = character: " +
 190                                                    field);
 191             }
 192             fieldNames[i] = field.substring(0, eq);
 193             // makeMap will catch the case where the name is empty
 194             fieldValues[i] = field.substring(eq + 1);
 195         }
 196         return makeMap(fieldNames, fieldValues);
 197     }
 198 
 199     /**
 200      * <p>Return an {@code ImmutableDescriptor} whose contents are the union of
 201      * the given descriptors.  Every field name that appears in any of
 202      * the descriptors will appear in the result with the
 203      * value that it has when the method is called.  Subsequent changes
 204      * to any of the descriptors do not affect the ImmutableDescriptor
 205      * returned here.</p>
 206      *
 207      * <p>In the simplest case, there is only one descriptor and the
 208      * returned {@code ImmutableDescriptor} is a copy of its fields at the
 209      * time this method is called:</p>
 210      *
 211      * <pre>
 212      * Descriptor d = something();
 213      * ImmutableDescriptor copy = ImmutableDescriptor.union(d);
 214      * </pre>
 215      *
 216      * @param descriptors the descriptors to be combined.  Any of the
 217      * descriptors can be null, in which case it is skipped.
 218      *
 219      * @return an {@code ImmutableDescriptor} that is the union of the given
 220      * descriptors.  The returned object may be identical to one of the
 221      * input descriptors if it is an ImmutableDescriptor that contains all of
 222      * the required fields.
 223      *
 224      * @throws IllegalArgumentException if two Descriptors contain the
 225      * same field name with different associated values.  Primitive array
 226      * values are considered the same if they are of the same type with
 227      * the same elements.  Object array values are considered the same if
 228      * {@link Arrays#deepEquals(Object[],Object[])} returns true.
 229      */
 230     public static ImmutableDescriptor union(Descriptor... descriptors) {
 231         // Optimize the case where exactly one Descriptor is non-Empty
 232         // and it is immutable - we can just return it.
 233         int index = findNonEmpty(descriptors, 0);
 234         if (index < 0)
 235             return EMPTY_DESCRIPTOR;
 236         if (descriptors[index] instanceof ImmutableDescriptor
 237                 && findNonEmpty(descriptors, index + 1) < 0)
 238             return (ImmutableDescriptor) descriptors[index];
 239 
 240         Map<String, Object> map =
 241             new TreeMap<String, Object>(String.CASE_INSENSITIVE_ORDER);
 242         ImmutableDescriptor biggestImmutable = EMPTY_DESCRIPTOR;
 243         for (Descriptor d : descriptors) {
 244             if (d != null) {
 245                 String[] names;
 246                 if (d instanceof ImmutableDescriptor) {
 247                     ImmutableDescriptor id = (ImmutableDescriptor) d;
 248                     names = id.names;
 249                     if (id.getClass() == ImmutableDescriptor.class
 250                             && names.length > biggestImmutable.names.length)
 251                         biggestImmutable = id;
 252                 } else
 253                     names = d.getFieldNames();
 254                 for (String n : names) {
 255                     Object v = d.getFieldValue(n);
 256                     Object old = map.put(n, v);
 257                     if (old != null) {
 258                         boolean equal;
 259                         if (old.getClass().isArray()) {
 260                             equal = Arrays.deepEquals(new Object[] {old},
 261                                                       new Object[] {v});
 262                         } else
 263                             equal = old.equals(v);
 264                         if (!equal) {
 265                             final String msg =
 266                                 "Inconsistent values for descriptor field " +
 267                                 n + ": " + old + " :: " + v;
 268                             throw new IllegalArgumentException(msg);
 269                         }
 270                     }
 271                 }
 272             }
 273         }
 274         if (biggestImmutable.names.length == map.size())
 275             return biggestImmutable;
 276         return new ImmutableDescriptor(map);
 277     }
 278 
 279     private static boolean isEmpty(Descriptor d) {
 280         if (d == null)
 281             return true;
 282         else if (d instanceof ImmutableDescriptor)
 283             return ((ImmutableDescriptor) d).names.length == 0;
 284         else
 285             return (d.getFieldNames().length == 0);
 286     }
 287 
 288     private static int findNonEmpty(Descriptor[] ds, int start) {
 289         for (int i = start; i < ds.length; i++) {
 290             if (!isEmpty(ds[i]))
 291                 return i;
 292         }
 293         return -1;
 294     }
 295 
 296     private int fieldIndex(String name) {
 297         return Arrays.binarySearch(names, name, String.CASE_INSENSITIVE_ORDER);
 298     }
 299 
 300     public final Object getFieldValue(String fieldName) {
 301         checkIllegalFieldName(fieldName);
 302         int i = fieldIndex(fieldName);
 303         if (i < 0)
 304             return null;
 305         Object v = values[i];
 306         if (v == null || !v.getClass().isArray())
 307             return v;
 308         if (v instanceof Object[])
 309             return ((Object[]) v).clone();
 310         // clone the primitive array, could use an 8-way if/else here
 311         int len = Array.getLength(v);
 312         Object a = Array.newInstance(v.getClass().getComponentType(), len);
 313         System.arraycopy(v, 0, a, 0, len);
 314         return a;
 315     }
 316 
 317     public final String[] getFields() {
 318         String[] result = new String[names.length];
 319         for (int i = 0; i < result.length; i++) {
 320             Object value = values[i];
 321             if (value == null)
 322                 value = "";
 323             else if (!(value instanceof String))
 324                 value = "(" + value + ")";
 325             result[i] = names[i] + "=" + value;
 326         }
 327         return result;
 328     }
 329 
 330     public final Object[] getFieldValues(String... fieldNames) {
 331         if (fieldNames == null)
 332             return values.clone();
 333         Object[] result = new Object[fieldNames.length];
 334         for (int i = 0; i < fieldNames.length; i++) {
 335             String name = fieldNames[i];
 336             if (name != null && !name.equals(""))
 337                 result[i] = getFieldValue(name);
 338         }
 339         return result;
 340     }
 341 
 342     public final String[] getFieldNames() {
 343         return names.clone();
 344     }
 345 
 346     /**
 347      * Compares this descriptor to the given object.  The objects are equal if
 348      * the given object is also a Descriptor, and if the two Descriptors have
 349      * the same field names (possibly differing in case) and the same
 350      * associated values.  The respective values for a field in the two
 351      * Descriptors are equal if the following conditions hold:
 352      *
 353      * <ul>
 354      * <li>If one value is null then the other must be too.</li>
 355      * <li>If one value is a primitive array then the other must be a primitive
 356      * array of the same type with the same elements.</li>
 357      * <li>If one value is an object array then the other must be too and
 358      * {@link Arrays#deepEquals(Object[],Object[])} must return true.</li>
 359      * <li>Otherwise {@link Object#equals(Object)} must return true.</li>
 360      * </ul>
 361      *
 362      * @param o the object to compare with.
 363      *
 364      * @return {@code true} if the objects are the same; {@code false}
 365      * otherwise.
 366      *
 367      */
 368     // Note: this Javadoc is copied from javax.management.Descriptor
 369     //       due to 6369229.
 370     @Override
 371     public boolean equals(Object o) {
 372         if (o == this)
 373             return true;
 374         if (!(o instanceof Descriptor))
 375             return false;
 376         String[] onames;
 377         if (o instanceof ImmutableDescriptor) {
 378             onames = ((ImmutableDescriptor) o).names;
 379         } else {
 380             onames = ((Descriptor) o).getFieldNames();
 381             Arrays.sort(onames, String.CASE_INSENSITIVE_ORDER);
 382         }
 383         if (names.length != onames.length)
 384             return false;
 385         for (int i = 0; i < names.length; i++) {
 386             if (!names[i].equalsIgnoreCase(onames[i]))
 387                 return false;
 388         }
 389         Object[] ovalues;
 390         if (o instanceof ImmutableDescriptor)
 391             ovalues = ((ImmutableDescriptor) o).values;
 392         else
 393             ovalues = ((Descriptor) o).getFieldValues(onames);
 394         return Arrays.deepEquals(values, ovalues);
 395     }
 396 
 397     /**
 398      * <p>Returns the hash code value for this descriptor.  The hash
 399      * code is computed as the sum of the hash codes for each field in
 400      * the descriptor.  The hash code of a field with name {@code n}
 401      * and value {@code v} is {@code n.toLowerCase().hashCode() ^ h}.
 402      * Here {@code h} is the hash code of {@code v}, computed as
 403      * follows:</p>
 404      *
 405      * <ul>
 406      * <li>If {@code v} is null then {@code h} is 0.</li>
 407      * <li>If {@code v} is a primitive array then {@code h} is computed using
 408      * the appropriate overloading of {@code java.util.Arrays.hashCode}.</li>
 409      * <li>If {@code v} is an object array then {@code h} is computed using
 410      * {@link Arrays#deepHashCode(Object[])}.</li>
 411      * <li>Otherwise {@code h} is {@code v.hashCode()}.</li>
 412      * </ul>
 413      *
 414      * @return A hash code value for this object.
 415      *
 416      */
 417     // Note: this Javadoc is copied from javax.management.Descriptor
 418     //       due to 6369229.
 419     @Override
 420     public int hashCode() {
 421         if (hashCode == -1) {
 422             hashCode = Util.hashCode(names, values);
 423         }
 424         return hashCode;
 425     }
 426 
 427     @Override
 428     public String toString() {
 429         StringBuilder sb = new StringBuilder("{");
 430         for (int i = 0; i < names.length; i++) {
 431             if (i > 0)
 432                 sb.append(", ");
 433             sb.append(names[i]).append("=");
 434             Object v = values[i];
 435             if (v != null && v.getClass().isArray()) {
 436                 String s = Arrays.deepToString(new Object[] {v});
 437                 s = s.substring(1, s.length() - 1); // remove [...]
 438                 v = s;
 439             }
 440             sb.append(String.valueOf(v));
 441         }
 442         return sb.append("}").toString();
 443     }
 444 
 445     /**
 446      * Returns true if all of the fields have legal values given their
 447      * names.  This method always returns true, but a subclass can
 448      * override it to return false when appropriate.
 449      *
 450      * @return true if the values are legal.
 451      *
 452      * @exception RuntimeOperationsException if the validity checking fails.
 453      * The method returns false if the descriptor is not valid, but throws
 454      * this exception if the attempt to determine validity fails.
 455      */
 456     public boolean isValid() {
 457         return true;
 458     }
 459 
 460     /**
 461      * <p>Returns a descriptor which is equal to this descriptor.
 462      * Changes to the returned descriptor will have no effect on this
 463      * descriptor, and vice versa.</p>
 464      *
 465      * <p>This method returns the object on which it is called.
 466      * A subclass can override it
 467      * to return another object provided the contract is respected.
 468      *
 469      * @exception RuntimeOperationsException for illegal value for field Names
 470      * or field Values.
 471      * If the descriptor construction fails for any reason, this exception will
 472      * be thrown.
 473      */
 474     @Override
 475     public Descriptor clone() {
 476         return this;
 477     }
 478 
 479     /**
 480      * This operation is unsupported since this class is immutable.  If
 481      * this call would change a mutable descriptor with the same contents,
 482      * then a {@link RuntimeOperationsException} wrapping an
 483      * {@link UnsupportedOperationException} is thrown.  Otherwise,
 484      * the behavior is the same as it would be for a mutable descriptor:
 485      * either an exception is thrown because of illegal parameters, or
 486      * there is no effect.
 487      */
 488     public final void setFields(String[] fieldNames, Object[] fieldValues)
 489         throws RuntimeOperationsException {
 490         if (fieldNames == null || fieldValues == null)
 491             illegal("Null argument");
 492         if (fieldNames.length != fieldValues.length)
 493             illegal("Different array sizes");
 494         for (int i = 0; i < fieldNames.length; i++)
 495             checkIllegalFieldName(fieldNames[i]);
 496         for (int i = 0; i < fieldNames.length; i++)
 497             setField(fieldNames[i], fieldValues[i]);
 498     }
 499 
 500     /**
 501      * This operation is unsupported since this class is immutable.  If
 502      * this call would change a mutable descriptor with the same contents,
 503      * then a {@link RuntimeOperationsException} wrapping an
 504      * {@link UnsupportedOperationException} is thrown.  Otherwise,
 505      * the behavior is the same as it would be for a mutable descriptor:
 506      * either an exception is thrown because of illegal parameters, or
 507      * there is no effect.
 508      */
 509     public final void setField(String fieldName, Object fieldValue)
 510         throws RuntimeOperationsException {
 511         checkIllegalFieldName(fieldName);
 512         int i = fieldIndex(fieldName);
 513         if (i < 0)
 514             unsupported();
 515         Object value = values[i];
 516         if ((value == null) ?
 517                 (fieldValue != null) :
 518                 !value.equals(fieldValue))
 519             unsupported();
 520     }
 521 
 522     /**
 523      * Removes a field from the descriptor.
 524      *
 525      * @param fieldName String name of the field to be removed.
 526      * If the field name is illegal or the field is not found,
 527      * no exception is thrown.
 528      *
 529      * @exception RuntimeOperationsException if a field of the given name
 530      * exists and the descriptor is immutable.  The wrapped exception will
 531      * be an {@link UnsupportedOperationException}.
 532      */
 533     public final void removeField(String fieldName) {
 534         if (fieldName != null && fieldIndex(fieldName) >= 0)
 535             unsupported();
 536     }
 537 
 538     static Descriptor nonNullDescriptor(Descriptor d) {
 539         if (d == null)
 540             return EMPTY_DESCRIPTOR;
 541         else
 542             return d;
 543     }
 544 
 545     private static void checkIllegalFieldName(String name) {
 546         if (name == null || name.equals(""))
 547             illegal("Null or empty field name");
 548     }
 549 
 550     private static void unsupported() {
 551         UnsupportedOperationException uoe =
 552             new UnsupportedOperationException("Descriptor is read-only");
 553         throw new RuntimeOperationsException(uoe);
 554     }
 555 
 556     private static void illegal(String message) {
 557         IllegalArgumentException iae = new IllegalArgumentException(message);
 558         throw new RuntimeOperationsException(iae);
 559     }
 560 }