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