001/* OpenMBeanParameterInfoSupport.java -- Open typed info about a parameter.
002   Copyright (C) 2006, 2007 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.management.openmbean;
039
040import java.util.Collections;
041import java.util.HashSet;
042import java.util.Set;
043
044import javax.management.MBeanParameterInfo;
045
046/**
047 * Describes the parameters of a constructor or operation associated
048 * with an open management bean.
049 *
050 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
051 * @since 1.5
052 */
053public class OpenMBeanParameterInfoSupport
054  extends MBeanParameterInfo
055  implements OpenMBeanParameterInfo
056{
057
058  /**
059   * Compatible with JDK 1.5
060   */
061  private static final long serialVersionUID = -7235016873758443122L;
062
063  /**
064   * The open type of the parameter.
065   */
066  private OpenType<?> openType;
067
068  /**
069   * The default value of the parameter (may be <code>null</code>).
070   */
071  private Object defaultValue;
072
073  /**
074   * The possible legal values of the parameter (may be <code>null</code>).
075   */
076  private Set<?> legalValues;
077
078  /**
079   * The minimum value of the parameter (may be <code>null</code>).
080   */
081  private Comparable<?> minValue;
082
083  /**
084   * The maximum value of the parameter (may be <code>null</code>).
085   */
086  private Comparable<?> maxValue;
087
088  /**
089   * The hash code of this instance.
090   */
091  private transient Integer hashCode;
092
093  /**
094   * The <code>toString()</code> result of this instance.
095   */
096  private transient String string;
097
098  /**
099   * Constructs a new {@link OpenMBeanParameterInfo} using the specified
100   * name, description and open type.  None of these values may be
101   * <code>null</code> and the name and description may not be equal
102   * to the empty string.
103   *
104   * @param name the name of the parameter.
105   * @param desc a description of the parameter.
106   * @param type the open type of the parameter.
107   * @throws IllegalArgumentException if the name, description or
108   *                                  open type are <code>null</code>
109   *                                  or the name or description are
110   *                                  the empty string.
111   */
112  public OpenMBeanParameterInfoSupport(String name, String desc, OpenType<?> type)
113  {
114    super(name, type == null ? null : type.getClassName(), desc);
115    if (name == null)
116      throw new IllegalArgumentException("The name may not be null.");
117    if (desc == null)
118      throw new IllegalArgumentException("The description may not be null.");
119    if (type == null)
120      throw new IllegalArgumentException("The type may not be null.");
121    if (name.length() == 0)
122      throw new IllegalArgumentException("The name may not be the empty string.");
123    if (desc.length() == 0)
124      throw new IllegalArgumentException("The description may not be the " +
125                                         "empty string.");
126    openType = type;
127  }
128
129  /**
130   * Constructs a new {@link OpenMBeanParameterInfo} using the
131   * specified name, description, open type and default value.  The
132   * name, description and open type cannot be <code>null</code> and
133   * the name and description may not be equal to the empty string.
134   * The default value may be <code>null</code>.  If non-null, it must
135   * be a valid value of the given open type.  Default values are not
136   * applicable to the open types, {@link ArrayType} and {@link
137   * TabularType}.
138   *
139   * @param name the name of the parameter.
140   * @param desc a description of the parameter.
141   * @param type the open type of the parameter.
142   * @param defaultValue the default value of the parameter.
143   * @throws IllegalArgumentException if the name, description or
144   *                                  open type are <code>null</code>
145   *                                  or the name or description are
146   *                                  the empty string.
147   * @throws OpenDataException if <code>defaultValue<code> is non-null
148   *                           and is either not a value of the given
149   *                           open type or the open type is an instance
150   *                           of {@link ArrayType} or {@link TabularType}.
151   */
152  public <T> OpenMBeanParameterInfoSupport(String name, String desc, OpenType<T> type,
153                                           T defaultValue)
154    throws OpenDataException
155  {
156    this(name, desc, type, defaultValue, null);
157  }
158
159  /**
160   * <p>
161   * Constructs a new {@link OpenMBeanParameterInfo} using the
162   * specified name, description, open type, default, maximum and
163   * minimum values.  The name, description and open type cannot be
164   * <code>null</code> and the name and description may not be equal
165   * to the empty string.  The default, maximum and minimum values may
166   * be <code>null</code>.  The following conditions apply when the
167   * parameters mentioned are non-null:
168   * </p>
169   * <ul>
170   * <li>The values must be valid values for the given open type.</li>
171   * <li>Default values are not applicable to the open types, {@link
172   * ArrayType} and {@link TabularType}.</li>
173   * <li>The minimum value must be smaller than or equal to the maximum value
174   * (literally, <code>minValue.compareTo(maxValue) <= 0</code>.</li>
175   * <li>The minimum value must be smaller than or equal to the default value
176   * (literally, <code>minValue.compareTo(defaultValue) <= 0</code>.</li>
177   * <li>The default value must be smaller than or equal to the maximum value
178   * (literally, <code>defaultValue.compareTo(maxValue) <= 0</code>.</li>
179   * </ul>
180   *
181   * @param name the name of the parameter.
182   * @param desc a description of the parameter.
183   * @param type the open type of the parameter.
184   * @param defaultValue the default value of the parameter, or <code>null</code>.
185   * @param minimumValue the minimum value of the parameter, or <code>null</code>.
186   * @param maximumValue the maximum value of the parameter, or <code>null</code>.
187   * @throws IllegalArgumentException if the name, description or
188   *                                  open type are <code>null</code>
189   *                                  or the name or description are
190   *                                  the empty string.
191   * @throws OpenDataException if any condition in the list above is broken.
192   */
193  @SuppressWarnings("unchecked")
194  public <T> OpenMBeanParameterInfoSupport(String name, String desc, OpenType<T> type,
195                                           T defaultValue, Comparable<T> minimumValue,
196                                           Comparable<T> maximumValue)
197    throws OpenDataException
198  {
199    this(name, desc, type);
200    if (defaultValue != null && !(type.isValue(defaultValue)))
201      throw new OpenDataException("The default value is not a member of the " +
202                                  "open type given.");
203    if (minimumValue != null && !(type.isValue(minimumValue)))
204      throw new OpenDataException("The minimum value is not a member of the " +
205                                  "open type given.");
206    if (maximumValue != null && !(type.isValue(maximumValue)))
207      throw new OpenDataException("The maximum value is not a member of the " +
208                                  "open type given.");
209    if (defaultValue != null && (type instanceof ArrayType ||
210                                 type instanceof TabularType))
211      throw new OpenDataException("Default values are not applicable for " +
212                                  "array or tabular types.");
213    if (minimumValue != null && maximumValue != null
214        && minimumValue.compareTo((T) maximumValue) > 0)
215      throw new OpenDataException("The minimum value is greater than the " +
216                                  "maximum.");
217    if (minimumValue != null && defaultValue != null
218        && minimumValue.compareTo(defaultValue) > 0)
219      throw new OpenDataException("The minimum value is greater than the " +
220                                  "default.");
221    if (defaultValue != null && maximumValue != null
222        && maximumValue.compareTo(defaultValue) < 0)
223      throw new OpenDataException("The default value is greater than the " +
224                                  "maximum.");
225
226    this.defaultValue = defaultValue;
227    minValue = minimumValue;
228    maxValue = maximumValue;
229  }
230
231  /**
232   * <p>
233   * Constructs a new {@link OpenMBeanParameterInfo} using the
234   * specified name, description, open type, default value and
235   * set of legal values.  The name, description and open type cannot be
236   * <code>null</code> and the name and description may not be equal
237   * to the empty string.  The default, maximum and minimum values may
238   * be <code>null</code>.  The following conditions apply when the
239   * parameters mentioned are non-null:
240   * </p>
241   * <ul>
242   * <li>The default value and each of the legal values must be a valid
243   * value for the given open type.</li>
244   * <li>Default and legal values are not applicable to the open types, {@link
245   * ArrayType} and {@link TabularType}.</li>
246   * <li>The default value is not in the set of legal values.</li>
247   * </ul>
248   * <p>
249   * The legal values are copied from the array into a unmodifiable set,
250   * so future modifications to the array have no effect.
251   * </p>
252   *
253   * @param name the name of the parameter.
254   * @param desc a description of the parameter.
255   * @param type the open type of the parameter.
256   * @param defaultValue the default value of the parameter, or <code>null</code>.
257   * @param legalValues the legal values of the parameter.  May be
258   *                    <code>null</code> or an empty array.
259   * @throws IllegalArgumentException if the name, description or
260   *                                  open type are <code>null</code>
261   *                                  or the name or description are
262   *                                  the empty string.
263   * @throws OpenDataException if any condition in the list above is broken.
264   */
265  public <T> OpenMBeanParameterInfoSupport(String name, String desc, OpenType<T> type,
266                                           T defaultValue, T[] legalValues)
267    throws OpenDataException
268  {
269    this(name, desc, type);
270    if (defaultValue != null && !(type.isValue(defaultValue)))
271      throw new OpenDataException("The default value is not a member of the " +
272                                  "open type given.");
273    if (defaultValue != null && (type instanceof ArrayType ||
274                                 type instanceof TabularType))
275      throw new OpenDataException("Default values are not applicable for " +
276                                  "array or tabular types.");
277    if (legalValues != null && (type instanceof ArrayType ||
278                                type instanceof TabularType))
279      throw new OpenDataException("Legal values are not applicable for " +
280                                  "array or tabular types.");
281    if (legalValues != null && legalValues.length > 0)
282      {
283        Set<T> lv = new HashSet<T>(legalValues.length);
284        for (int a = 0; a < legalValues.length; ++a)
285          {
286            if (legalValues[a] != null &&
287                !(type.isValue(legalValues[a])))
288              throw new OpenDataException("The legal value, "
289                                          + legalValues[a] +
290                                          "is not a member of the " +
291                                          "open type given.");
292            lv.add(legalValues[a]);
293          }
294        if (defaultValue != null && !(lv.contains(defaultValue)))
295          throw new OpenDataException("The default value is not in the set " +
296                                      "of legal values.");
297        this.legalValues = Collections.unmodifiableSet(lv);
298      }
299    this.defaultValue = defaultValue;
300  }
301
302  /**
303   * Compares this parameter with the supplied object.  This returns
304   * true iff the object is an instance of {@link OpenMBeanParameterInfo}
305   * with an equal name and open type and the same default, minimum,
306   * maximum and legal values.
307   *
308   * @param obj the object to compare.
309   * @return true if the object is a {@link OpenMBeanParameterInfo}
310   *         instance,
311   *         <code>name.equals(object.getName())</code>,
312   *         <code>openType.equals(object.getOpenType())</code>,
313   *         <code>defaultValue.equals(object.getDefaultValue())</code>,
314   *         <code>minValue.equals(object.getMinValue())</code>,
315   *         <code>maxValue.equals(object.getMaxValue())</code>,
316   *         and <code>legalValues.equals(object.getLegalValues())</code>.
317   */
318  public boolean equals(Object obj)
319  {
320    if (!(obj instanceof OpenMBeanParameterInfo))
321      return false;
322    OpenMBeanParameterInfo o = (OpenMBeanParameterInfo) obj;
323    return getName().equals(o.getName()) &&
324      openType.equals(o.getOpenType()) &&
325      (defaultValue == null ? o.getDefaultValue() == null :
326       defaultValue.equals(o.getDefaultValue())) &&
327      (minValue == null ? o.getMinValue() == null :
328       minValue.equals(o.getMinValue())) &&
329      (maxValue == null ? o.getMaxValue() == null :
330       maxValue.equals(o.getMaxValue())) &&
331      (legalValues == null ? o.getLegalValues() == null :
332       legalValues.equals(o.getLegalValues()));
333  }
334
335  /**
336   * Returns the default value of this parameter, or <code>null</code>
337   * if there is no default value.
338   *
339   * @return the default value of the parameter, or <code>null</code>
340   *         if there is no default.
341   */
342  public Object getDefaultValue()
343  {
344    return defaultValue;
345  }
346
347  /**
348   * Returns a {@link java.util.Set} enumerating the legal values
349   * of this parameter, or <code>null</code> if no such limited
350   * set exists for this parameter.
351   *
352   * @return a set of legal values, or <code>null</code> if no such
353   *         set exists.
354   */
355  public Set<?> getLegalValues()
356  {
357    return legalValues;
358  }
359
360  /**
361   * Returns the maximum value of this parameter, or <code>null</code>
362   * if there is no maximum.
363   *
364   * @return the maximum value, or <code>null</code> if none exists.
365   */
366  public Comparable<?> getMaxValue()
367  {
368    return maxValue;
369  }
370
371  /**
372   * Returns the minimum value of this parameter, or <code>null</code>
373   * if there is no minimum.
374   *
375   * @return the minimum value, or <code>null</code> if none exists.
376   */
377  public Comparable<?> getMinValue()
378  {
379    return minValue;
380  }
381
382  /**
383   * Returns the open type instance which represents the type of this
384   * parameter.
385   *
386   * @return the open type of this parameter.
387   */
388  public OpenType<?> getOpenType()
389  {
390    return openType;
391  }
392
393  /**
394   * Returns true if this parameter has a default value
395   * (i.e. the value is non-null).
396   *
397   * @return true if this parameter has a default.
398   */
399  public boolean hasDefaultValue()
400  {
401    return defaultValue != null;
402  }
403
404  /**
405   * <p>
406   * Returns the hashcode of the parameter information as the sum of
407   * the hashcodes of the name, open type, default value, maximum
408   * value, minimum value and the set of legal values.
409   * </p>
410   * <p>
411   * As instances of this class are immutable, the hash code
412   * is computed just once for each instance and reused
413   * throughout its life.
414   * </p>
415   *
416   * @return the hashcode of the parameter information.
417   */
418  public int hashCode()
419  {
420    if (hashCode == null)
421      hashCode = Integer.valueOf(getName().hashCode() +
422                                 openType.hashCode() +
423                                 (defaultValue == null ? 0 :
424                                  defaultValue.hashCode()) +
425                                 (minValue == null ? 0 :
426                                  minValue.hashCode()) +
427                                 (maxValue == null ? 0 :
428                                  maxValue.hashCode()) +
429                                 (legalValues == null ? 0 :
430                                  legalValues.hashCode()));
431    return hashCode.intValue();
432  }
433
434  /**
435   * Returns true if there is a set of legal values for this
436   * parameter (i.e. the value is non-null).
437   *
438   * @return true if a set of legal values exists for this
439   *         parameter.
440   */
441  public boolean hasLegalValues()
442  {
443    return legalValues != null;
444  }
445
446  /**
447   * Returns true if there is a maximum value for this parameter
448   * (i.e. the value is non-null).
449   *
450   * @return true if a maximum value exists for this parameter.
451   */
452  public boolean hasMaxValue()
453  {
454    return maxValue != null;
455  }
456
457  /**
458   * Returns true if there is a minimum value for this parameter.
459   * (i.e. the value is non-null).
460   *
461   * @return true if a minimum value exists for this parameter.
462   */
463  public boolean hasMinValue()
464  {
465    return minValue != null;
466  }
467
468  /**
469   * Returns true if the specified object is a valid value for
470   * this parameter.
471   *
472   * @param obj the object to test.
473   * @return true if <code>obj</code> is a valid value for this
474   *         parameter.
475   */
476  public boolean isValue(Object obj)
477  {
478    return openType.isValue(obj);
479  }
480
481  /**
482   * <p>
483   * Returns a textual representation of this instance.  This
484   * is constructed using the class name
485   * (<code>javax.management.openmbean.OpenMBeanParameterInfo</code>)
486   * along with the name, open type, default, minimum, maximum
487   * and legal values of the parameter.
488   * </p>
489   * <p>
490   * As instances of this class are immutable, the return value
491   * is computed just once for each instance and reused
492   * throughout its life.
493   * </p>
494   *
495   * @return a @link{java.lang.String} instance representing
496   *         the instance in textual form.
497   */
498  public String toString()
499  {
500    if (string == null)
501      string = getClass().getName()
502        + "[name=" + getName()
503        + ",openType=" + openType
504        + ",defaultValue=" + defaultValue
505        + ",minValue=" + minValue
506        + ",maxValue=" + maxValue
507        + ",legalValues=" + legalValues
508        + "]";
509    return string;
510  }
511
512}