1 /*
2 * Copyright (c) 2000, 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
27 package javax.management.openmbean;
28
29
30 // java import
31 //
32 import java.util.Set;
33 import javax.management.Descriptor;
34 import javax.management.DescriptorRead; // for Javadoc
35 import javax.management.ImmutableDescriptor;
36 import javax.management.MBeanParameterInfo;
37
38 // OpenMBeanAttributeInfoSupport and this class are very similar
39 // but can't easily be refactored because there's no multiple inheritance.
40 // The best we can do for refactoring is to put a bunch of static methods
41 // in OpenMBeanAttributeInfoSupport and import them here.
42 import static javax.management.openmbean.OpenMBeanAttributeInfoSupport.*;
43
44 /**
45 * Describes a parameter used in one or more operations or
46 * constructors of an open MBean.
47 *
48 *
49 * @since 1.5
50 */
51 public class OpenMBeanParameterInfoSupport
52 extends MBeanParameterInfo
53 implements OpenMBeanParameterInfo {
54
55 /* Serial version */
56 static final long serialVersionUID = -7235016873758443122L;
57
58 /**
59 * @serial The open mbean parameter's <i>open type</i>
60 */
61 private OpenType<?> openType;
62
63 /**
64 * @serial The open mbean parameter's default value
65 */
66 private Object defaultValue = null;
67
68 /**
69 * @serial The open mbean parameter's legal values. This {@link
70 * Set} is unmodifiable
71 */
72 private Set<?> legalValues = null; // to be constructed unmodifiable
73
74 /**
75 * @serial The open mbean parameter's min value
76 */
77 private Comparable<?> minValue = null;
78
79 /**
80 * @serial The open mbean parameter's max value
81 */
82 private Comparable<?> maxValue = null;
83
84
85 // As this instance is immutable, these two values need only
86 // be calculated once.
87 private transient Integer myHashCode = null; // As this instance is immutable, these two values
88 private transient String myToString = null; // need only be calculated once.
89
90
91 /**
92 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
93 * which describes the parameter used in one or more operations or
94 * constructors of a class of open MBeans, with the specified
95 * {@code name}, {@code openType} and {@code description}.
96 *
97 * @param name cannot be a null or empty string.
98 *
99 * @param description cannot be a null or empty string.
100 *
101 * @param openType cannot be null.
102 *
103 * @throws IllegalArgumentException if {@code name} or {@code
104 * description} are null or empty string, or {@code openType} is
105 * null.
106 */
107 public OpenMBeanParameterInfoSupport(String name,
108 String description,
109 OpenType<?> openType) {
110 this(name, description, openType, (Descriptor) null);
111 }
112
113 /**
114 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
115 * which describes the parameter used in one or more operations or
116 * constructors of a class of open MBeans, with the specified
117 * {@code name}, {@code openType}, {@code description},
118 * and {@code descriptor}.
119 *
120 * <p>The {@code descriptor} can contain entries that will define
121 * the values returned by certain methods of this class, as
122 * explained in the <a href="package-summary.html#constraints">
123 * package description</a>.
124 *
125 * @param name cannot be a null or empty string.
126 *
127 * @param description cannot be a null or empty string.
128 *
129 * @param openType cannot be null.
130 *
131 * @param descriptor The descriptor for the parameter. This may be null
132 * which is equivalent to an empty descriptor.
133 *
134 * @throws IllegalArgumentException if {@code name} or {@code
135 * description} are null or empty string, or {@code openType} is
136 * null, or the descriptor entries are invalid as described in the
137 * <a href="package-summary.html#constraints">package
138 * description</a>.
139 *
140 * @since 1.6
141 */
142 public OpenMBeanParameterInfoSupport(String name,
143 String description,
144 OpenType<?> openType,
145 Descriptor descriptor) {
146
147
148 // Construct parent's state
149 //
150 super(name,
151 (openType==null) ? null : openType.getClassName(),
152 description,
153 ImmutableDescriptor.union(descriptor,(openType==null)?null:
154 openType.getDescriptor()));
155
156 // Initialize this instance's specific state
157 //
158 this.openType = openType;
159
160 descriptor = getDescriptor(); // replace null by empty
161 this.defaultValue = valueFrom(descriptor, "defaultValue", openType);
162 this.legalValues = valuesFrom(descriptor, "legalValues", openType);
163 this.minValue = comparableValueFrom(descriptor, "minValue", openType);
164 this.maxValue = comparableValueFrom(descriptor, "maxValue", openType);
165
166 try {
167 check(this);
168 } catch (OpenDataException e) {
169 throw new IllegalArgumentException(e.getMessage(), e);
170 }
171 }
172
173
174 /**
175 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
176 * which describes the parameter used in one or more operations or
177 * constructors of a class of open MBeans, with the specified
178 * {@code name}, {@code openType}, {@code description} and {@code
179 * defaultValue}.
180 *
181 * @param name cannot be a null or empty string.
182 *
183 * @param description cannot be a null or empty string.
184 *
185 * @param openType cannot be null.
186 *
187 * @param defaultValue must be a valid value for the {@code
188 * openType} specified for this parameter; default value not
189 * supported for {@code ArrayType} and {@code TabularType}; can be
190 * null, in which case it means that no default value is set.
191 *
192 * @param <T> allows the compiler to check that the {@code defaultValue},
193 * if non-null, has the correct Java type for the given {@code openType}.
194 *
195 * @throws IllegalArgumentException if {@code name} or {@code
196 * description} are null or empty string, or {@code openType} is
197 * null.
198 *
199 * @throws OpenDataException if {@code defaultValue} is not a
200 * valid value for the specified {@code openType}, or {@code
201 * defaultValue} is non null and {@code openType} is an {@code
202 * ArrayType} or a {@code TabularType}.
203 */
204 public <T> OpenMBeanParameterInfoSupport(String name,
205 String description,
206 OpenType<T> openType,
207 T defaultValue)
208 throws OpenDataException {
209 this(name, description, openType, defaultValue, (T[]) null);
210 }
211
212 /**
213 * <p>Constructs an {@code OpenMBeanParameterInfoSupport} instance,
214 * which describes the parameter used in one or more operations or
215 * constructors of a class of open MBeans, with the specified
216 * {@code name}, {@code openType}, {@code description}, {@code
217 * defaultValue} and {@code legalValues}.</p>
218 *
219 * <p>The contents of {@code legalValues} are copied, so subsequent
220 * modifications of the array referenced by {@code legalValues}
221 * have no impact on this {@code OpenMBeanParameterInfoSupport}
222 * instance.</p>
223 *
224 * @param name cannot be a null or empty string.
225 *
226 * @param description cannot be a null or empty string.
227 *
228 * @param openType cannot be null.
229 *
230 * @param defaultValue must be a valid value for the {@code
231 * openType} specified for this parameter; default value not
232 * supported for {@code ArrayType} and {@code TabularType}; can be
233 * null, in which case it means that no default value is set.
234 *
235 * @param legalValues each contained value must be valid for the
236 * {@code openType} specified for this parameter; legal values not
237 * supported for {@code ArrayType} and {@code TabularType}; can be
238 * null or empty.
239 *
240 * @param <T> allows the compiler to check that the {@code
241 * defaultValue} and {@code legalValues}, if non-null, have the
242 * correct Java type for the given {@code openType}.
243 *
244 * @throws IllegalArgumentException if {@code name} or {@code
245 * description} are null or empty string, or {@code openType} is
246 * null.
247 *
248 * @throws OpenDataException if {@code defaultValue} is not a
249 * valid value for the specified {@code openType}, or one value in
250 * {@code legalValues} is not valid for the specified {@code
251 * openType}, or {@code defaultValue} is non null and {@code
252 * openType} is an {@code ArrayType} or a {@code TabularType}, or
253 * {@code legalValues} is non null and non empty and {@code
254 * openType} is an {@code ArrayType} or a {@code TabularType}, or
255 * {@code legalValues} is non null and non empty and {@code
256 * defaultValue} is not contained in {@code legalValues}.
257 */
258 public <T> OpenMBeanParameterInfoSupport(String name,
259 String description,
260 OpenType<T> openType,
261 T defaultValue,
262 T[] legalValues)
263 throws OpenDataException {
264 this(name, description, openType,
265 defaultValue, legalValues, null, null);
266 }
267
268
269 /**
270 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
271 * which describes the parameter used in one or more operations or
272 * constructors of a class of open MBeans, with the specified
273 * {@code name}, {@code openType}, {@code description}, {@code
274 * defaultValue}, {@code minValue} and {@code maxValue}.
275 *
276 * It is possible to specify minimal and maximal values only for
277 * an open type whose values are {@code Comparable}.
278 *
279 * @param name cannot be a null or empty string.
280 *
281 * @param description cannot be a null or empty string.
282 *
283 * @param openType cannot be null.
284 *
285 * @param defaultValue must be a valid value for the {@code
286 * openType} specified for this parameter; default value not
287 * supported for {@code ArrayType} and {@code TabularType}; can be
288 * null, in which case it means that no default value is set.
289 *
290 * @param minValue must be valid for the {@code openType}
291 * specified for this parameter; can be null, in which case it
292 * means that no minimal value is set.
293 *
294 * @param maxValue must be valid for the {@code openType}
295 * specified for this parameter; can be null, in which case it
296 * means that no maximal value is set.
297 *
298 * @param <T> allows the compiler to check that the {@code
299 * defaultValue}, {@code minValue}, and {@code maxValue}, if
300 * non-null, have the correct Java type for the given {@code
301 * openType}.
302 *
303 * @throws IllegalArgumentException if {@code name} or {@code
304 * description} are null or empty string, or {@code openType} is
305 * null.
306 *
307 * @throws OpenDataException if {@code defaultValue}, {@code
308 * minValue} or {@code maxValue} is not a valid value for the
309 * specified {@code openType}, or {@code defaultValue} is non null
310 * and {@code openType} is an {@code ArrayType} or a {@code
311 * TabularType}, or both {@code minValue} and {@code maxValue} are
312 * non-null and {@code minValue.compareTo(maxValue) > 0} is {@code
313 * true}, or both {@code defaultValue} and {@code minValue} are
314 * non-null and {@code minValue.compareTo(defaultValue) > 0} is
315 * {@code true}, or both {@code defaultValue} and {@code maxValue}
316 * are non-null and {@code defaultValue.compareTo(maxValue) > 0}
317 * is {@code true}.
318 */
319 public <T> OpenMBeanParameterInfoSupport(String name,
320 String description,
321 OpenType<T> openType,
322 T defaultValue,
323 Comparable<T> minValue,
324 Comparable<T> maxValue)
325 throws OpenDataException {
326 this(name, description, openType,
327 defaultValue, null, minValue, maxValue);
328 }
329
330 private <T> OpenMBeanParameterInfoSupport(String name,
331 String description,
332 OpenType<T> openType,
333 T defaultValue,
334 T[] legalValues,
335 Comparable<T> minValue,
336 Comparable<T> maxValue)
337 throws OpenDataException {
338 super(name,
339 (openType == null) ? null : openType.getClassName(),
340 description,
341 makeDescriptor(openType,
342 defaultValue, legalValues, minValue, maxValue));
343
344 this.openType = openType;
345
346 Descriptor d = getDescriptor();
347 this.defaultValue = defaultValue;
348 this.minValue = minValue;
349 this.maxValue = maxValue;
350 // We already converted the array into an unmodifiable Set
351 // in the descriptor.
352 this.legalValues = (Set<?>) d.getFieldValue("legalValues");
353
354 check(this);
355 }
356
357 /**
358 * An object serialized in a version of the API before Descriptors were
359 * added to this class will have an empty or null Descriptor.
360 * For consistency with our
361 * behavior in this version, we must replace the object with one
362 * where the Descriptors reflect the same values of openType, defaultValue,
363 * etc.
364 **/
365 private Object readResolve() {
366 if (getDescriptor().getFieldNames().length == 0) {
367 // This noise allows us to avoid "unchecked" warnings without
368 // having to suppress them explicitly.
369 OpenType<Object> xopenType = cast(openType);
370 Set<Object> xlegalValues = cast(legalValues);
371 Comparable<Object> xminValue = cast(minValue);
372 Comparable<Object> xmaxValue = cast(maxValue);
373 return new OpenMBeanParameterInfoSupport(
374 name, description, openType,
375 makeDescriptor(xopenType, defaultValue, xlegalValues,
376 xminValue, xmaxValue));
377 } else
378 return this;
379 }
380
381 /**
382 * Returns the open type for the values of the parameter described
383 * by this {@code OpenMBeanParameterInfoSupport} instance.
384 */
385 public OpenType<?> getOpenType() {
386 return openType;
387 }
388
389 /**
390 * Returns the default value for the parameter described by this
391 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
392 * or {@code null} otherwise.
393 */
394 public Object getDefaultValue() {
395
396 // Special case for ArrayType and TabularType
397 // [JF] TODO: clone it so that it cannot be altered,
398 // [JF] TODO: if we decide to support defaultValue as an array itself.
399 // [JF] As of today (oct 2000) it is not supported so
400 // defaultValue is null for arrays. Nothing to do.
401
402 return defaultValue;
403 }
404
405 /**
406 * Returns an unmodifiable Set of legal values for the parameter
407 * described by this {@code OpenMBeanParameterInfoSupport}
408 * instance, if specified, or {@code null} otherwise.
409 */
410 public Set<?> getLegalValues() {
411
412 // Special case for ArrayType and TabularType
413 // [JF] TODO: clone values so that they cannot be altered,
414 // [JF] TODO: if we decide to support LegalValues as an array itself.
415 // [JF] As of today (oct 2000) it is not supported so
416 // legalValues is null for arrays. Nothing to do.
417
418 // Returns our legalValues Set (set was constructed unmodifiable)
419 return (legalValues);
420 }
421
422 /**
423 * Returns the minimal value for the parameter described by this
424 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
425 * or {@code null} otherwise.
426 */
427 public Comparable<?> getMinValue() {
428
429 // Note: only comparable values have a minValue, so that's not
430 // the case of arrays and tabulars (always null).
431
432 return minValue;
433 }
434
435 /**
436 * Returns the maximal value for the parameter described by this
437 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
438 * or {@code null} otherwise.
439 */
440 public Comparable<?> getMaxValue() {
441
442 // Note: only comparable values have a maxValue, so that's not
443 // the case of arrays and tabulars (always null).
444
445 return maxValue;
446 }
447
448 /**
449 * Returns {@code true} if this {@code
450 * OpenMBeanParameterInfoSupport} instance specifies a non-null
451 * default value for the described parameter, {@code false}
452 * otherwise.
453 */
454 public boolean hasDefaultValue() {
455
456 return (defaultValue != null);
457 }
458
459 /**
460 * Returns {@code true} if this {@code
461 * OpenMBeanParameterInfoSupport} instance specifies a non-null
462 * set of legal values for the described parameter, {@code false}
463 * otherwise.
464 */
465 public boolean hasLegalValues() {
466
467 return (legalValues != null);
468 }
469
470 /**
471 * Returns {@code true} if this {@code
472 * OpenMBeanParameterInfoSupport} instance specifies a non-null
473 * minimal value for the described parameter, {@code false}
474 * otherwise.
475 */
476 public boolean hasMinValue() {
477
478 return (minValue != null);
479 }
480
481 /**
482 * Returns {@code true} if this {@code
483 * OpenMBeanParameterInfoSupport} instance specifies a non-null
484 * maximal value for the described parameter, {@code false}
485 * otherwise.
486 */
487 public boolean hasMaxValue() {
488
489 return (maxValue != null);
490 }
491
492
493 /**
494 * Tests whether {@code obj} is a valid value for the parameter
495 * described by this {@code OpenMBeanParameterInfo} instance.
496 *
497 * @param obj the object to be tested.
498 *
499 * @return {@code true} if {@code obj} is a valid value
500 * for the parameter described by this
501 * {@code OpenMBeanParameterInfo} instance,
502 * {@code false} otherwise.
503 */
504 public boolean isValue(Object obj) {
505 return OpenMBeanAttributeInfoSupport.isValue(this, obj);
506 // compiler bug? should be able to omit class name here
507 // also below in toString and hashCode
508 }
509
510
511 /* *** Commodity methods from java.lang.Object *** */
512
513
514 /**
515 * <p>Compares the specified {@code obj} parameter with this {@code
516 * OpenMBeanParameterInfoSupport} instance for equality.</p>
517 *
518 * <p>Returns {@code true} if and only if all of the following
519 * statements are true:
520 *
521 * <ul>
522 * <li>{@code obj} is non null,</li>
523 * <li>{@code obj} also implements the {@code OpenMBeanParameterInfo}
524 * interface,</li>
525 * <li>their names are equal</li>
526 * <li>their open types are equal</li>
527 * <li>their default, min, max and legal values are equal.</li>
528 * </ul>
529 * This ensures that this {@code equals} method works properly for
530 * {@code obj} parameters which are different implementations of
531 * the {@code OpenMBeanParameterInfo} interface.
532 *
533 * <p>If {@code obj} also implements {@link DescriptorRead}, then its
534 * {@link DescriptorRead#getDescriptor() getDescriptor()} method must
535 * also return the same value as for this object.</p>
536 *
537 * @param obj the object to be compared for equality with this
538 * {@code OpenMBeanParameterInfoSupport} instance.
539 *
540 * @return {@code true} if the specified object is equal to this
541 * {@code OpenMBeanParameterInfoSupport} instance.
542 */
543 public boolean equals(Object obj) {
544 if (!(obj instanceof OpenMBeanParameterInfo))
545 return false;
546
547 OpenMBeanParameterInfo other = (OpenMBeanParameterInfo) obj;
548
549 return equal(this, other);
550 }
551
552 /**
553 * <p>Returns the hash code value for this {@code
554 * OpenMBeanParameterInfoSupport} instance.</p>
555 *
556 * <p>The hash code of an {@code OpenMBeanParameterInfoSupport}
557 * instance is the sum of the hash codes of all elements of
558 * information used in {@code equals} comparisons (ie: its name,
559 * its <i>open type</i>, its default, min, max and legal
560 * values, and its Descriptor).
561 *
562 * <p>This ensures that {@code t1.equals(t2)} implies that {@code
563 * t1.hashCode()==t2.hashCode()} for any two {@code
564 * OpenMBeanParameterInfoSupport} instances {@code t1} and {@code
565 * t2}, as required by the general contract of the method {@link
566 * Object#hashCode() Object.hashCode()}.
567 *
568 * <p>However, note that another instance of a class implementing
569 * the {@code OpenMBeanParameterInfo} interface may be equal to
570 * this {@code OpenMBeanParameterInfoSupport} instance as defined
571 * by {@link #equals(java.lang.Object)}, but may have a different
572 * hash code if it is calculated differently.
573 *
574 * <p>As {@code OpenMBeanParameterInfoSupport} instances are
575 * immutable, the hash code for this instance is calculated once,
576 * on the first call to {@code hashCode}, and then the same value
577 * is returned for subsequent calls.
578 *
579 * @return the hash code value for this {@code
580 * OpenMBeanParameterInfoSupport} instance
581 */
582 public int hashCode() {
583
584 // Calculate the hash code value if it has not yet been done
585 // (ie 1st call to hashCode())
586 //
587 if (myHashCode == null)
588 myHashCode = OpenMBeanAttributeInfoSupport.hashCode(this);
589
590 // return always the same hash code for this instance (immutable)
591 //
592 return myHashCode.intValue();
593 }
594
595 /**
596 * Returns a string representation of this
597 * {@code OpenMBeanParameterInfoSupport} instance.
598 * <p>
599 * The string representation consists of the name of this class (i.e.
600 * {@code javax.management.openmbean.OpenMBeanParameterInfoSupport}),
601 * the string representation of the name and open type of the described
602 * parameter, the string representation of its default, min, max and legal
603 * values and the string representation of its descriptor.
604 * <p>
605 * As {@code OpenMBeanParameterInfoSupport} instances are immutable,
606 * the string representation for this instance is calculated once,
607 * on the first call to {@code toString}, and then the same value
608 * is returned for subsequent calls.
609 *
610 * @return a string representation of this
611 * {@code OpenMBeanParameterInfoSupport} instance.
612 */
613 public String toString() {
614
615 // Calculate the string value if it has not yet been done (ie
616 // 1st call to toString())
617 //
618 if (myToString == null)
619 myToString = OpenMBeanAttributeInfoSupport.toString(this);
620
621 // return always the same string representation for this
622 // instance (immutable)
623 //
624 return myToString;
625 }
626
627 }
628