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<Object> minValue;
082    
083      /**
084       * The maximum value of the parameter (may be <code>null</code>).
085       */
086      private Comparable<Object> 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      public <T> OpenMBeanParameterInfoSupport(String name, String desc, OpenType<T> type,
194                                               T defaultValue, Comparable<T> minimumValue,
195                                               Comparable<T> maximumValue)
196        throws OpenDataException
197      {
198        this(name, desc, type);
199        if (defaultValue != null && !(type.isValue(defaultValue)))
200          throw new OpenDataException("The default value is not a member of the " +
201                                      "open type given.");
202        if (minimumValue != null && !(type.isValue(minimumValue)))
203          throw new OpenDataException("The minimum value is not a member of the " +
204                                      "open type given.");
205        if (maximumValue != null && !(type.isValue(maximumValue)))
206          throw new OpenDataException("The maximum value is not a member of the " +
207                                      "open type given.");
208        if (defaultValue != null && (type instanceof ArrayType || 
209                                     type instanceof TabularType))
210          throw new OpenDataException("Default values are not applicable for " +
211                                      "array or tabular types.");
212        if (minValue != null && maxValue != null 
213            && minValue.compareTo(maxValue) > 0)
214          throw new OpenDataException("The minimum value is greater than the " +
215                                      "maximum.");
216        if (minValue != null && defaultValue != null 
217            && minValue.compareTo(defaultValue) > 0)
218          throw new OpenDataException("The minimum value is greater than the " +
219                                      "default.");
220        if (defaultValue != null && maxValue != null
221            && maxValue.compareTo(defaultValue) < 0)
222          throw new OpenDataException("The default value is greater than the " +
223                                      "maximum.");
224        
225        this.defaultValue = defaultValue;
226        minValue = (Comparable<Object>) minimumValue;
227        maxValue = (Comparable<Object>) maximumValue;
228      }
229    
230      /**
231       * <p>
232       * Constructs a new {@link OpenMBeanParameterInfo} using the
233       * specified name, description, open type, default value and
234       * set of legal values.  The name, description and open type cannot be
235       * <code>null</code> and the name and description may not be equal
236       * to the empty string.  The default, maximum and minimum values may
237       * be <code>null</code>.  The following conditions apply when the
238       * parameters mentioned are non-null:
239       * </p>
240       * <ul>
241       * <li>The default value and each of the legal values must be a valid
242       * value for the given open type.</li>
243       * <li>Default and legal values are not applicable to the open types, {@link
244       * ArrayType} and {@link TabularType}.</li>
245       * <li>The default value is not in the set of legal values.</li>
246       * </ul>
247       * <p>
248       * The legal values are copied from the array into a unmodifiable set,
249       * so future modifications to the array have no effect.
250       * </p>
251       *
252       * @param name the name of the parameter.
253       * @param desc a description of the parameter.
254       * @param type the open type of the parameter.
255       * @param defaultValue the default value of the parameter, or <code>null</code>.
256       * @param legalValues the legal values of the parameter.  May be
257       *                    <code>null</code> or an empty array.
258       * @throws IllegalArgumentException if the name, description or
259       *                                  open type are <code>null</code>
260       *                                  or the name or description are
261       *                                  the empty string.
262       * @throws OpenDataException if any condition in the list above is broken.
263       */
264      public <T> OpenMBeanParameterInfoSupport(String name, String desc, OpenType<T> type,
265                                               T defaultValue, T[] legalValues)
266        throws OpenDataException
267      {
268        this(name, desc, type);
269        if (defaultValue != null && !(type.isValue(defaultValue)))
270          throw new OpenDataException("The default value is not a member of the " +
271                                      "open type given.");
272        if (defaultValue != null && (type instanceof ArrayType || 
273                                     type instanceof TabularType))
274          throw new OpenDataException("Default values are not applicable for " +
275                                      "array or tabular types.");
276        if (legalValues != null && (type instanceof ArrayType || 
277                                    type instanceof TabularType))
278          throw new OpenDataException("Legal values are not applicable for " +
279                                      "array or tabular types.");
280        if (legalValues != null && legalValues.length > 0)
281          {
282            Set lv = new HashSet(legalValues.length);
283            for (int a = 0; a < legalValues.length; ++a)
284              {
285                if (legalValues[a] != null && 
286                    !(type.isValue(legalValues[a])))
287                  throw new OpenDataException("The legal value, " 
288                                              + legalValues[a] + 
289                                              "is not a member of the " +
290                                              "open type given.");
291                lv.add(legalValues[a]);
292              }
293            if (defaultValue != null && !(lv.contains(defaultValue)))
294              throw new OpenDataException("The default value is not in the set " +
295                                          "of legal values.");
296            this.legalValues = Collections.unmodifiableSet(lv);
297          }
298        this.defaultValue = defaultValue;
299      }
300    
301      /**
302       * Compares this parameter with the supplied object.  This returns
303       * true iff the object is an instance of {@link OpenMBeanParameterInfo}
304       * with an equal name and open type and the same default, minimum,
305       * maximum and legal values.
306       *
307       * @param obj the object to compare.
308       * @return true if the object is a {@link OpenMBeanParameterInfo}
309       *         instance, 
310       *         <code>name.equals(object.getName())</code>,
311       *         <code>openType.equals(object.getOpenType())</code>,
312       *         <code>defaultValue.equals(object.getDefaultValue())</code>,
313       *         <code>minValue.equals(object.getMinValue())</code>,
314       *         <code>maxValue.equals(object.getMaxValue())</code>,
315       *         and <code>legalValues.equals(object.getLegalValues())</code>.
316       */
317      public boolean equals(Object obj)
318      {
319        if (!(obj instanceof OpenMBeanParameterInfo))
320          return false;
321        OpenMBeanParameterInfo o = (OpenMBeanParameterInfo) obj;
322        return getName().equals(o.getName()) &&
323          openType.equals(o.getOpenType()) &&
324          (defaultValue == null ? o.getDefaultValue() == null :
325           defaultValue.equals(o.getDefaultValue())) &&
326          (minValue == null ? o.getMinValue() == null :
327           minValue.equals(o.getMinValue())) &&
328          (maxValue == null ? o.getMaxValue() == null :
329           maxValue.equals(o.getMaxValue())) &&
330          (legalValues == null ? o.getLegalValues() == null :
331           legalValues.equals(o.getLegalValues()));
332      }
333    
334      /**
335       * Returns the default value of this parameter, or <code>null</code>
336       * if there is no default value.
337       *
338       * @return the default value of the parameter, or <code>null</code>
339       *         if there is no default.
340       */
341      public Object getDefaultValue()
342      {
343        return defaultValue;
344      }
345    
346      /**
347       * Returns a {@link java.util.Set} enumerating the legal values
348       * of this parameter, or <code>null</code> if no such limited
349       * set exists for this parameter.
350       *
351       * @return a set of legal values, or <code>null</code> if no such
352       *         set exists.
353       */
354      public Set<?> getLegalValues()
355      {
356        return legalValues;
357      }
358    
359      /**
360       * Returns the maximum value of this parameter, or <code>null</code>
361       * if there is no maximum.
362       *
363       * @return the maximum value, or <code>null</code> if none exists.
364       */
365      public Comparable<?> getMaxValue()
366      {
367        return maxValue;
368      }
369    
370      /**
371       * Returns the minimum value of this parameter, or <code>null</code>
372       * if there is no minimum.
373       *
374       * @return the minimum value, or <code>null</code> if none exists.
375       */
376      public Comparable<?> getMinValue()
377      {
378        return minValue;
379      }
380    
381      /**
382       * Returns the open type instance which represents the type of this
383       * parameter.
384       *
385       * @return the open type of this parameter.
386       */
387      public OpenType<?> getOpenType()
388      {
389        return openType;
390      }
391    
392      /**
393       * Returns true if this parameter has a default value
394       * (i.e. the value is non-null).
395       *
396       * @return true if this parameter has a default.
397       */
398      public boolean hasDefaultValue()
399      {
400        return defaultValue != null;
401      }
402    
403      /**
404       * <p>
405       * Returns the hashcode of the parameter information as the sum of
406       * the hashcodes of the name, open type, default value, maximum
407       * value, minimum value and the set of legal values.
408       * </p>
409       * <p>
410       * As instances of this class are immutable, the hash code
411       * is computed just once for each instance and reused
412       * throughout its life.
413       * </p>
414       *
415       * @return the hashcode of the parameter information.
416       */
417      public int hashCode()
418      {
419        if (hashCode == null)
420          hashCode = Integer.valueOf(getName().hashCode() + 
421                                     openType.hashCode() +
422                                     (defaultValue == null ? 0 :
423                                      defaultValue.hashCode()) +
424                                     (minValue == null ? 0 :
425                                      minValue.hashCode()) +
426                                     (maxValue == null ? 0 :
427                                      maxValue.hashCode()) +
428                                     (legalValues == null ? 0 :
429                                      legalValues.hashCode()));
430        return hashCode.intValue();
431      }
432    
433      /**
434       * Returns true if there is a set of legal values for this
435       * parameter (i.e. the value is non-null).
436       *
437       * @return true if a set of legal values exists for this
438       *         parameter.
439       */
440      public boolean hasLegalValues()
441      {
442        return legalValues != null;
443      }
444    
445      /**
446       * Returns true if there is a maximum value for this parameter
447       * (i.e. the value is non-null).
448       *
449       * @return true if a maximum value exists for this parameter.
450       */
451      public boolean hasMaxValue()
452      {
453        return maxValue != null;
454      }
455    
456      /**
457       * Returns true if there is a minimum value for this parameter.
458       * (i.e. the value is non-null).
459       *
460       * @return true if a minimum value exists for this parameter.
461       */
462      public boolean hasMinValue()
463      {
464        return minValue != null;
465      }
466    
467      /**
468       * Returns true if the specified object is a valid value for
469       * this parameter.
470       *
471       * @param obj the object to test.
472       * @return true if <code>obj</code> is a valid value for this
473       *         parameter.
474       */
475      public boolean isValue(Object obj)
476      {
477        return openType.isValue(obj);
478      }
479    
480      /**
481       * <p>
482       * Returns a textual representation of this instance.  This
483       * is constructed using the class name
484       * (<code>javax.management.openmbean.OpenMBeanParameterInfo</code>)
485       * along with the name, open type, default, minimum, maximum
486       * and legal values of the parameter.
487       * </p>
488       * <p>
489       * As instances of this class are immutable, the return value
490       * is computed just once for each instance and reused
491       * throughout its life.
492       * </p>
493       *
494       * @return a @link{java.lang.String} instance representing
495       *         the instance in textual form.
496       */
497      public String toString()
498      {
499        if (string == null)
500          string = getClass().getName()
501            + "[name=" + getName() 
502            + ",openType=" + openType 
503            + ",defaultValue=" + defaultValue
504            + ",minValue=" + minValue
505            + ",maxValue=" + maxValue
506            + ",legalValues=" + legalValues
507            + "]";
508        return string;
509      }
510    
511    }