001 /*
002 * Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management.openmbean;
027
028 // java import
029 //
030 import java.util.Set;
031 import javax.management.Descriptor;
032 import javax.management.DescriptorRead; // for Javadoc
033 import javax.management.ImmutableDescriptor;
034 import javax.management.MBeanParameterInfo;
035
036 // OpenMBeanAttributeInfoSupport and this class are very similar
037 // but can't easily be refactored because there's no multiple inheritance.
038 // The best we can do for refactoring is to put a bunch of static methods
039 // in OpenMBeanAttributeInfoSupport and import them here.
040 import static javax.management.openmbean.OpenMBeanAttributeInfoSupport.*;
041
042 /**
043 * Describes a parameter used in one or more operations or
044 * constructors of an open MBean.
045 *
046 *
047 * @since 1.5
048 */
049 public class OpenMBeanParameterInfoSupport extends MBeanParameterInfo
050 implements OpenMBeanParameterInfo {
051
052 /* Serial version */
053 static final long serialVersionUID = -7235016873758443122L;
054
055 /**
056 * @serial The open mbean parameter's <i>open type</i>
057 */
058 private OpenType<?> openType;
059
060 /**
061 * @serial The open mbean parameter's default value
062 */
063 private Object defaultValue = null;
064
065 /**
066 * @serial The open mbean parameter's legal values. This {@link
067 * Set} is unmodifiable
068 */
069 private Set<?> legalValues = null; // to be constructed unmodifiable
070
071 /**
072 * @serial The open mbean parameter's min value
073 */
074 private Comparable minValue = null;
075
076 /**
077 * @serial The open mbean parameter's max value
078 */
079 private Comparable maxValue = null;
080
081 // As this instance is immutable, these two values need only
082 // be calculated once.
083 private transient Integer myHashCode = null; // As this instance is immutable, these two values
084 private transient String myToString = null; // need only be calculated once.
085
086 /**
087 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
088 * which describes the parameter used in one or more operations or
089 * constructors of a class of open MBeans, with the specified
090 * {@code name}, {@code openType} and {@code description}.
091 *
092 * @param name cannot be a null or empty string.
093 *
094 * @param description cannot be a null or empty string.
095 *
096 * @param openType cannot be null.
097 *
098 * @throws IllegalArgumentException if {@code name} or {@code
099 * description} are null or empty string, or {@code openType} is
100 * null.
101 */
102 public OpenMBeanParameterInfoSupport(String name,
103 String description, OpenType<?> openType) {
104 this (name, description, openType, (Descriptor) null);
105 }
106
107 /**
108 * <p>Constructs an {@code OpenMBeanParameterInfoSupport} instance,
109 * which describes the parameter used in one or more operations or
110 * constructors of a class of open MBeans, with the specified
111 * {@code name}, {@code openType}, {@code description},
112 * and {@code descriptor}.</p>
113 *
114 * <p>The {@code descriptor} can contain entries that will define
115 * the values returned by certain methods of this class, as
116 * explained in the {@link <a href="package-summary.html#constraints">
117 * package description</a>}.
118 *
119 * @param name cannot be a null or empty string.
120 *
121 * @param description cannot be a null or empty string.
122 *
123 * @param openType cannot be null.
124 *
125 * @param descriptor The descriptor for the parameter. This may be null
126 * which is equivalent to an empty descriptor.
127 *
128 * @throws IllegalArgumentException if {@code name} or {@code
129 * description} are null or empty string, or {@code openType} is
130 * null, or the descriptor entries are invalid as described in the
131 * {@link <a href="package-summary.html#constraints">package
132 * description</a>}.
133 *
134 * @since 1.6
135 */
136 public OpenMBeanParameterInfoSupport(String name,
137 String description, OpenType<?> openType,
138 Descriptor descriptor) {
139
140 // Construct parent's state
141 //
142 super (name,
143 (openType == null) ? null : openType.getClassName(),
144 description, ImmutableDescriptor.union(descriptor,
145 (openType == null) ? null : openType
146 .getDescriptor()));
147
148 // Initialize this instance's specific state
149 //
150 this .openType = openType;
151
152 descriptor = getDescriptor(); // replace null by empty
153 this .defaultValue = valueFrom(descriptor, "defaultValue",
154 openType);
155 this .legalValues = valuesFrom(descriptor, "legalValues",
156 openType);
157 this .minValue = comparableValueFrom(descriptor, "minValue",
158 openType);
159 this .maxValue = comparableValueFrom(descriptor, "maxValue",
160 openType);
161
162 try {
163 check(this );
164 } catch (OpenDataException e) {
165 throw new IllegalArgumentException(e.getMessage(), e);
166 }
167 }
168
169 /**
170 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
171 * which describes the parameter used in one or more operations or
172 * constructors of a class of open MBeans, with the specified
173 * {@code name}, {@code openType}, {@code description} and {@code
174 * defaultValue}.
175 *
176 * @param name cannot be a null or empty string.
177 *
178 * @param description cannot be a null or empty string.
179 *
180 * @param openType cannot be null.
181 *
182 * @param defaultValue must be a valid value for the {@code
183 * openType} specified for this parameter; default value not
184 * supported for {@code ArrayType} and {@code TabularType}; can be
185 * null, in which case it means that no default value is set.
186 *
187 * @param <T> allows the compiler to check that the {@code defaultValue},
188 * if non-null, has the correct Java type for the given {@code openType}.
189 *
190 * @throws IllegalArgumentException if {@code name} or {@code
191 * description} are null or empty string, or {@code openType} is
192 * null.
193 *
194 * @throws OpenDataException if {@code defaultValue} is not a
195 * valid value for the specified {@code openType}, or {@code
196 * defaultValue} is non null and {@code openType} is an {@code
197 * ArrayType} or a {@code TabularType}.
198 */
199 public <T> OpenMBeanParameterInfoSupport(String name,
200 String description, OpenType<T> openType, T defaultValue)
201 throws OpenDataException {
202 this (name, description, openType, defaultValue, (T[]) null);
203 }
204
205 /**
206 * <p>Constructs an {@code OpenMBeanParameterInfoSupport} instance,
207 * which describes the parameter used in one or more operations or
208 * constructors of a class of open MBeans, with the specified
209 * {@code name}, {@code openType}, {@code description}, {@code
210 * defaultValue} and {@code legalValues}.</p>
211 *
212 * <p>The contents of {@code legalValues} are copied, so subsequent
213 * modifications of the array referenced by {@code legalValues}
214 * have no impact on this {@code OpenMBeanParameterInfoSupport}
215 * instance.</p>
216 *
217 * @param name cannot be a null or empty string.
218 *
219 * @param description cannot be a null or empty string.
220 *
221 * @param openType cannot be null.
222 *
223 * @param defaultValue must be a valid value for the {@code
224 * openType} specified for this parameter; default value not
225 * supported for {@code ArrayType} and {@code TabularType}; can be
226 * null, in which case it means that no default value is set.
227 *
228 * @param legalValues each contained value must be valid for the
229 * {@code openType} specified for this parameter; legal values not
230 * supported for {@code ArrayType} and {@code TabularType}; can be
231 * null or empty.
232 *
233 * @param <T> allows the compiler to check that the {@code
234 * defaultValue} and {@code legalValues}, if non-null, have the
235 * correct Java type for the given {@code openType}.
236 *
237 * @throws IllegalArgumentException if {@code name} or {@code
238 * description} are null or empty string, or {@code openType} is
239 * null.
240 *
241 * @throws OpenDataException if {@code defaultValue} is not a
242 * valid value for the specified {@code openType}, or one value in
243 * {@code legalValues} is not valid for the specified {@code
244 * openType}, or {@code defaultValue} is non null and {@code
245 * openType} is an {@code ArrayType} or a {@code TabularType}, or
246 * {@code legalValues} is non null and non empty and {@code
247 * openType} is an {@code ArrayType} or a {@code TabularType}, or
248 * {@code legalValues} is non null and non empty and {@code
249 * defaultValue} is not contained in {@code legalValues}.
250 */
251 public <T> OpenMBeanParameterInfoSupport(String name,
252 String description, OpenType<T> openType, T defaultValue,
253 T[] legalValues) throws OpenDataException {
254 this (name, description, openType, defaultValue, legalValues,
255 null, null);
256 }
257
258 /**
259 * Constructs an {@code OpenMBeanParameterInfoSupport} instance,
260 * which describes the parameter used in one or more operations or
261 * constructors of a class of open MBeans, with the specified
262 * {@code name}, {@code openType}, {@code description}, {@code
263 * defaultValue}, {@code minValue} and {@code maxValue}.
264 *
265 * It is possible to specify minimal and maximal values only for
266 * an open type whose values are {@code Comparable}.
267 *
268 * @param name cannot be a null or empty string.
269 *
270 * @param description cannot be a null or empty string.
271 *
272 * @param openType cannot be null.
273 *
274 * @param defaultValue must be a valid value for the {@code
275 * openType} specified for this parameter; default value not
276 * supported for {@code ArrayType} and {@code TabularType}; can be
277 * null, in which case it means that no default value is set.
278 *
279 * @param minValue must be valid for the {@code openType}
280 * specified for this parameter; can be null, in which case it
281 * means that no minimal value is set.
282 *
283 * @param maxValue must be valid for the {@code openType}
284 * specified for this parameter; can be null, in which case it
285 * means that no maximal value is set.
286 *
287 * @param <T> allows the compiler to check that the {@code
288 * defaultValue}, {@code minValue}, and {@code maxValue}, if
289 * non-null, have the correct Java type for the given {@code
290 * openType}.
291 *
292 * @throws IllegalArgumentException if {@code name} or {@code
293 * description} are null or empty string, or {@code openType} is
294 * null.
295 *
296 * @throws OpenDataException if {@code defaultValue}, {@code
297 * minValue} or {@code maxValue} is not a valid value for the
298 * specified {@code openType}, or {@code defaultValue} is non null
299 * and {@code openType} is an {@code ArrayType} or a {@code
300 * TabularType}, or both {@code minValue} and {@code maxValue} are
301 * non-null and {@code minValue.compareTo(maxValue) > 0} is {@code
302 * true}, or both {@code defaultValue} and {@code minValue} are
303 * non-null and {@code minValue.compareTo(defaultValue) > 0} is
304 * {@code true}, or both {@code defaultValue} and {@code maxValue}
305 * are non-null and {@code defaultValue.compareTo(maxValue) > 0}
306 * is {@code true}.
307 */
308 public <T> OpenMBeanParameterInfoSupport(String name,
309 String description, OpenType<T> openType, T defaultValue,
310 Comparable<T> minValue, Comparable<T> maxValue)
311 throws OpenDataException {
312 this (name, description, openType, defaultValue, null, minValue,
313 maxValue);
314 }
315
316 private <T> OpenMBeanParameterInfoSupport(String name,
317 String description, OpenType<T> openType, T defaultValue,
318 T[] legalValues, Comparable<T> minValue,
319 Comparable<T> maxValue) throws OpenDataException {
320 super (name,
321 (openType == null) ? null : openType.getClassName(),
322 description, makeDescriptor(openType, defaultValue,
323 legalValues, minValue, maxValue));
324
325 this .openType = openType;
326
327 Descriptor d = getDescriptor();
328 this .defaultValue = defaultValue;
329 this .minValue = minValue;
330 this .maxValue = maxValue;
331 // We already converted the array into an unmodifiable Set
332 // in the descriptor.
333 this .legalValues = (Set<?>) d.getFieldValue("legalValues");
334
335 check(this );
336 }
337
338 /**
339 * An object serialized in a version of the API before Descriptors were
340 * added to this class will have an empty or null Descriptor.
341 * For consistency with our
342 * behavior in this version, we must replace the object with one
343 * where the Descriptors reflect the same values of openType, defaultValue,
344 * etc.
345 **/
346 private Object readResolve() {
347 if (getDescriptor().getFieldNames().length == 0) {
348 // This noise allows us to avoid "unchecked" warnings without
349 // having to suppress them explicitly.
350 OpenType<Object> xopenType = cast(openType);
351 Set<Object> xlegalValues = cast(legalValues);
352 Comparable<Object> xminValue = cast(minValue);
353 Comparable<Object> xmaxValue = cast(maxValue);
354 return new OpenMBeanParameterInfoSupport(name, description,
355 openType, makeDescriptor(xopenType, defaultValue,
356 xlegalValues, xminValue, xmaxValue));
357 } else
358 return this ;
359 }
360
361 /**
362 * Returns the open type for the values of the parameter described
363 * by this {@code OpenMBeanParameterInfoSupport} instance.
364 */
365 public OpenType<?> getOpenType() {
366 return openType;
367 }
368
369 /**
370 * Returns the default value for the parameter described by this
371 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
372 * or {@code null} otherwise.
373 */
374 public Object getDefaultValue() {
375
376 // Special case for ArrayType and TabularType
377 // [JF] TODO: clone it so that it cannot be altered,
378 // [JF] TODO: if we decide to support defaultValue as an array itself.
379 // [JF] As of today (oct 2000) it is not supported so
380 // defaultValue is null for arrays. Nothing to do.
381
382 return defaultValue;
383 }
384
385 /**
386 * Returns an unmodifiable Set of legal values for the parameter
387 * described by this {@code OpenMBeanParameterInfoSupport}
388 * instance, if specified, or {@code null} otherwise.
389 */
390 public Set<?> getLegalValues() {
391
392 // Special case for ArrayType and TabularType
393 // [JF] TODO: clone values so that they cannot be altered,
394 // [JF] TODO: if we decide to support LegalValues as an array itself.
395 // [JF] As of today (oct 2000) it is not supported so
396 // legalValues is null for arrays. Nothing to do.
397
398 // Returns our legalValues Set (set was constructed unmodifiable)
399 return (legalValues);
400 }
401
402 /**
403 * Returns the minimal value for the parameter described by this
404 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
405 * or {@code null} otherwise.
406 */
407 public Comparable<?> getMinValue() {
408
409 // Note: only comparable values have a minValue, so that's not
410 // the case of arrays and tabulars (always null).
411
412 return minValue;
413 }
414
415 /**
416 * Returns the maximal value for the parameter described by this
417 * {@code OpenMBeanParameterInfoSupport} instance, if specified,
418 * or {@code null} otherwise.
419 */
420 public Comparable<?> getMaxValue() {
421
422 // Note: only comparable values have a maxValue, so that's not
423 // the case of arrays and tabulars (always null).
424
425 return maxValue;
426 }
427
428 /**
429 * Returns {@code true} if this {@code
430 * OpenMBeanParameterInfoSupport} instance specifies a non-null
431 * default value for the described parameter, {@code false}
432 * otherwise.
433 */
434 public boolean hasDefaultValue() {
435
436 return (defaultValue != null);
437 }
438
439 /**
440 * Returns {@code true} if this {@code
441 * OpenMBeanParameterInfoSupport} instance specifies a non-null
442 * set of legal values for the described parameter, {@code false}
443 * otherwise.
444 */
445 public boolean hasLegalValues() {
446
447 return (legalValues != null);
448 }
449
450 /**
451 * Returns {@code true} if this {@code
452 * OpenMBeanParameterInfoSupport} instance specifies a non-null
453 * minimal value for the described parameter, {@code false}
454 * otherwise.
455 */
456 public boolean hasMinValue() {
457
458 return (minValue != null);
459 }
460
461 /**
462 * Returns {@code true} if this {@code
463 * OpenMBeanParameterInfoSupport} instance specifies a non-null
464 * maximal value for the described parameter, {@code false}
465 * otherwise.
466 */
467 public boolean hasMaxValue() {
468
469 return (maxValue != null);
470 }
471
472 /**
473 * Tests whether {@code obj} is a valid value for the parameter
474 * described by this {@code OpenMBeanParameterInfo} instance.
475 *
476 * @param obj the object to be tested.
477 *
478 * @return {@code true} if {@code obj} is a valid value
479 * for the parameter described by this
480 * {@code OpenMBeanParameterInfo} instance,
481 * {@code false} otherwise.
482 */
483 public boolean isValue(Object obj) {
484 return OpenMBeanAttributeInfoSupport.isValue(this , obj);
485 // compiler bug? should be able to omit class name here
486 // also below in toString and hashCode
487 }
488
489 /* *** Commodity methods from java.lang.Object *** */
490
491 /**
492 * <p>Compares the specified {@code obj} parameter with this {@code
493 * OpenMBeanParameterInfoSupport} instance for equality.</p>
494 *
495 * <p>Returns {@code true} if and only if all of the following
496 * statements are true:
497 *
498 * <ul>
499 * <li>{@code obj} is non null,</li>
500 * <li>{@code obj} also implements the {@code OpenMBeanParameterInfo}
501 * interface,</li>
502 * <li>their names are equal</li>
503 * <li>their open types are equal</li>
504 * <li>their default, min, max and legal values are equal.</li>
505 * </ul>
506 * This ensures that this {@code equals} method works properly for
507 * {@code obj} parameters which are different implementations of
508 * the {@code OpenMBeanParameterInfo} interface.
509 *
510 * <p>If {@code obj} also implements {@link DescriptorRead}, then its
511 * {@link DescriptorRead#getDescriptor() getDescriptor()} method must
512 * also return the same value as for this object.</p>
513 *
514 * @param obj the object to be compared for equality with this
515 * {@code OpenMBeanParameterInfoSupport} instance.
516 *
517 * @return {@code true} if the specified object is equal to this
518 * {@code OpenMBeanParameterInfoSupport} instance.
519 */
520 public boolean equals(Object obj) {
521 if (!(obj instanceof OpenMBeanParameterInfo))
522 return false;
523
524 OpenMBeanParameterInfo other = (OpenMBeanParameterInfo) obj;
525
526 return equal(this , other);
527 }
528
529 /**
530 * <p>Returns the hash code value for this {@code
531 * OpenMBeanParameterInfoSupport} instance.</p>
532 *
533 * <p>The hash code of an {@code OpenMBeanParameterInfoSupport}
534 * instance is the sum of the hash codes of all elements of
535 * information used in {@code equals} comparisons (ie: its name,
536 * its <i>open type</i>, its default, min, max and legal
537 * values, and its Descriptor).
538 *
539 * <p>This ensures that {@code t1.equals(t2)} implies that {@code
540 * t1.hashCode()==t2.hashCode()} for any two {@code
541 * OpenMBeanParameterInfoSupport} instances {@code t1} and {@code
542 * t2}, as required by the general contract of the method {@link
543 * Object#hashCode() Object.hashCode()}.
544 *
545 * <p>However, note that another instance of a class implementing
546 * the {@code OpenMBeanParameterInfo} interface may be equal to
547 * this {@code OpenMBeanParameterInfoSupport} instance as defined
548 * by {@link #equals(java.lang.Object)}, but may have a different
549 * hash code if it is calculated differently.
550 *
551 * <p>As {@code OpenMBeanParameterInfoSupport} instances are
552 * immutable, the hash code for this instance is calculated once,
553 * on the first call to {@code hashCode}, and then the same value
554 * is returned for subsequent calls.
555 *
556 * @return the hash code value for this {@code
557 * OpenMBeanParameterInfoSupport} instance
558 */
559 public int hashCode() {
560
561 // Calculate the hash code value if it has not yet been done
562 // (ie 1st call to hashCode())
563 //
564 if (myHashCode == null)
565 myHashCode = OpenMBeanAttributeInfoSupport.hashCode(this );
566
567 // return always the same hash code for this instance (immutable)
568 //
569 return myHashCode.intValue();
570 }
571
572 /**
573 * Returns a string representation of this
574 * {@code OpenMBeanParameterInfoSupport} instance.
575 * <p>
576 * The string representation consists of the name of this class (i.e.
577 * {@code javax.management.openmbean.OpenMBeanParameterInfoSupport}),
578 * the string representation of the name and open type of the described
579 * parameter, the string representation of its default, min, max and legal
580 * values and the string representation of its descriptor.
581 * <p>
582 * As {@code OpenMBeanParameterInfoSupport} instances are immutable,
583 * the string representation for this instance is calculated once,
584 * on the first call to {@code toString}, and then the same value
585 * is returned for subsequent calls.
586 *
587 * @return a string representation of this
588 * {@code OpenMBeanParameterInfoSupport} instance.
589 */
590 public String toString() {
591
592 // Calculate the string value if it has not yet been done (ie
593 // 1st call to toString())
594 //
595 if (myToString == null)
596 myToString = OpenMBeanAttributeInfoSupport.toString(this );
597
598 // return always the same string representation for this
599 // instance (immutable)
600 //
601 return myToString;
602 }
603
604 }
|