001    /* OpenMBeanParameterInfoSupport.java -- Open typed info about a parameter.
002       Copyright (C) 2006, 2007 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.management.openmbean;
039    
040    import java.util.Collections;
041    import java.util.HashSet;
042    import java.util.Set;
043    
044    import 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     */
053    public 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    }