001    /* java.beans.PropertyDescriptor
002       Copyright (C) 1998, 2001, 2004, 2005  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 java.beans;
039    
040    import java.lang.reflect.Constructor;
041    import java.lang.reflect.InvocationTargetException;
042    import java.lang.reflect.Method;
043    
044    /**
045     ** PropertyDescriptor describes information about a JavaBean property,
046     ** by which we mean a property that has been exposed via a pair of
047     ** get and set methods.  (There may be no get method, which means
048     ** the property is write-only, or no set method, which means the
049     ** the property is read-only.)<P>
050     **
051     ** The constraints put on get and set methods are:<P>
052     ** <OL>
053     ** <LI>A get method must have signature
054     **     <CODE>&lt;propertyType&gt; &lt;getMethodName&gt;()</CODE></LI>
055     ** <LI>A set method must have signature
056     **     <CODE>void &lt;setMethodName&gt;(&lt;propertyType&gt;)</CODE></LI>
057     ** <LI>Either method type may throw any exception.</LI>
058     ** <LI>Both methods must be public.</LI>
059     ** </OL>
060     **
061     ** @author John Keiser
062     ** @author Robert Schuster (thebohemian@gmx.net)
063     ** @since 1.1
064     ** @status updated to 1.4
065     **/
066    public class PropertyDescriptor extends FeatureDescriptor
067    {
068        Class<?> propertyType;
069        Method getMethod;
070        Method setMethod;
071    
072        Class<?> propertyEditorClass;
073        boolean bound;
074        boolean constrained;
075    
076        PropertyDescriptor(String name)
077        {
078            setName(name);
079        }
080    
081        /** Create a new PropertyDescriptor by introspection.
082         ** This form of constructor creates the PropertyDescriptor by
083         ** looking for a getter method named <CODE>get&lt;name&gt;()</CODE>
084         ** (or, optionally, if the property is boolean,
085         ** <CODE>is&lt;name&gt;()</CODE>) and
086         ** <CODE>set&lt;name&gt;()</CODE> in class
087         ** <CODE>&lt;beanClass&gt;</CODE>, where &lt;name&gt; has its
088         ** first letter capitalized by the constructor.<P>
089         **
090         ** Note that using this constructor the given property must be read- <strong>and</strong>
091         ** writeable. If the implementation does not both, a read and a write method, an
092         ** <code>IntrospectionException</code> is thrown.
093         **
094         ** <B>Implementation note:</B> If there is both are both isXXX and
095         ** getXXX methods, the former is used in preference to the latter.
096         ** We do not check that an isXXX method returns a boolean. In both
097         ** cases, this matches the behaviour of JDK 1.4<P>
098         **
099         ** @param name the programmatic name of the property, usually
100         **             starting with a lowercase letter (e.g. fooManChu
101         **             instead of FooManChu).
102         ** @param beanClass the class the get and set methods live in.
103         ** @exception IntrospectionException if the methods are not found 
104         **            or invalid.
105         **/
106        public PropertyDescriptor(String name, Class<?> beanClass)
107            throws IntrospectionException
108        {
109            setName(name);
110            if (name.length() == 0)
111            {
112                throw new IntrospectionException("empty property name");
113            }
114            String caps = Character.toUpperCase(name.charAt(0)) + name.substring(1);
115            findMethods(beanClass, "is" + caps, "get" + caps, "set" + caps);
116    
117            if (getMethod == null)
118            {
119                throw new IntrospectionException(
120                    "Cannot find a is" + caps + " or get" + caps + " method");
121            }
122    
123            if (setMethod == null)
124            {
125                throw new IntrospectionException(
126                    "Cannot find a " + caps + " method");
127            }
128    
129            // finally check the methods compatibility        
130            propertyType = checkMethods(getMethod, setMethod);
131        }
132    
133        /** Create a new PropertyDescriptor by introspection.
134         ** This form of constructor allows you to specify the
135         ** names of the get and set methods to search for.<P>
136         **
137         ** <B>Implementation note:</B> If there is a get method (or
138         ** boolean isXXX() method), then the return type of that method
139         ** is used to find the set method.  If there is no get method,
140         ** then the set method is searched for exhaustively.<P>
141         **
142         ** <B>Spec note:</B>
143         ** If there is no get method and multiple set methods with
144         ** the same name and a single parameter (different type of course),
145         ** then an IntrospectionException is thrown.  While Sun's spec
146         ** does not state this, it can make Bean behavior different on
147         ** different systems (since method order is not guaranteed) and as
148         ** such, can be treated as a bug in the spec.  I am not aware of
149         ** whether Sun's implementation catches this.
150         **
151         ** @param name the programmatic name of the property, usually
152         **             starting with a lowercase letter (e.g. fooManChu
153         **             instead of FooManChu).
154         ** @param beanClass the class the get and set methods live in.
155         ** @param getMethodName the name of the get method or <code>null</code> if the property is write-only.
156         ** @param setMethodName the name of the set method or <code>null</code> if the property is read-only.
157         ** @exception IntrospectionException if the methods are not found 
158         **            or invalid.
159         **/
160        public PropertyDescriptor(
161            String name,
162            Class<?> beanClass,
163            String getMethodName,
164            String setMethodName)
165            throws IntrospectionException
166        {
167            setName(name);
168            findMethods(beanClass, getMethodName, null, setMethodName);
169    
170            if (getMethod == null && getMethodName != null)
171            {
172                throw new IntrospectionException(
173                    "Cannot find a getter method called " + getMethodName);
174            }
175    
176            if (setMethod == null && setMethodName != null)
177            {
178                throw new IntrospectionException(
179                    "Cannot find a setter method called " + setMethodName);
180            }
181    
182            propertyType = checkMethods(getMethod, setMethod);
183        }
184    
185        /** Create a new PropertyDescriptor using explicit Methods.
186         ** Note that the methods will be checked for conformance to standard
187         ** Property method rules, as described above at the top of this class.
188         **<br>
189         ** It is possible to call this method with both <code>Method</code> arguments
190         ** being <code>null</code>. In such a case the property type is <code>null</code>.
191         ** 
192         ** @param name the programmatic name of the property, usually
193         **             starting with a lowercase letter (e.g. fooManChu
194         **             instead of FooManChu).
195         ** @param readMethod the read method or <code>null</code> if the property is write-only.
196         ** @param writeMethod the write method or <code>null</code> if the property is read-only.
197         ** @exception IntrospectionException if the methods are not found 
198         **            or invalid.
199         **/
200        public PropertyDescriptor(
201            String name,
202            Method readMethod,
203            Method writeMethod)
204            throws IntrospectionException
205        {
206            setName(name);
207            getMethod = readMethod;
208            setMethod = writeMethod;
209            propertyType = checkMethods(getMethod, setMethod);
210        }
211    
212        /** Get the property type.
213         ** This is the type the get method returns and the set method
214         ** takes in.
215         **/
216        public Class<?> getPropertyType()
217        {
218            return propertyType;
219        }
220    
221        /** Get the get method.  Why they call it readMethod here and
222         ** get everywhere else is beyond me.
223         **/
224        public Method getReadMethod()
225        {
226            return getMethod;
227        }
228    
229        /** Sets the read method.<br/>
230         * The read method is used to retrieve the value of a property. A legal
231         * read method must have no arguments. Its return type must not be
232         * <code>void</code>. If this methods succeeds the property type
233         * is adjusted to the return type of the read method.<br/>
234         * <br/>
235         * It is legal to set the read and the write method to <code>null</code>
236         * or provide method which have been declared in distinct classes.
237         * 
238         * @param readMethod The new method to be used or <code>null</code>.
239         * @throws IntrospectionException If the given method is invalid.
240         * @since 1.2
241         */
242        public void setReadMethod(Method readMethod) throws IntrospectionException
243        {
244            propertyType = checkMethods(readMethod, setMethod);
245    
246            getMethod = readMethod;
247        }
248    
249        /** Get the set method.  Why they call it writeMethod here and
250         ** set everywhere else is beyond me.
251         **/
252        public Method getWriteMethod()
253        {
254            return setMethod;
255        }
256    
257        /** Sets the write method.<br/>
258         * The write method is used to set the value of a property. A legal write method
259         * must have a single argument which can be assigned to the property. If no
260         * read method exists the property type changes to the argument type of the
261         * write method.<br/>
262         * <br/>
263         * It is legal to set the read and the write method to <code>null</code>
264         * or provide method which have been declared in distinct classes.
265         * 
266         * @param writeMethod The new method to be used or <code>null</code>.
267         * @throws IntrospectionException If the given method is invalid.
268         * @since 1.2
269         */
270        public void setWriteMethod(Method writeMethod)
271            throws IntrospectionException
272        {
273            propertyType = checkMethods(getMethod, writeMethod);
274    
275            setMethod = writeMethod;
276        }
277    
278        /** Get whether the property is bound.  Defaults to false. **/
279        public boolean isBound()
280        {
281            return bound;
282        }
283    
284        /** Set whether the property is bound.
285         ** As long as the the bean implements addPropertyChangeListener() and
286         ** removePropertyChangeListener(), setBound(true) may safely be called.<P>
287         ** If these things are not true, then the behavior of the system
288         ** will be undefined.<P>
289         **
290         ** When a property is bound, its set method is required to fire the
291         ** <CODE>PropertyChangeListener.propertyChange())</CODE> event
292         ** after the value has changed.
293         ** @param bound whether the property is bound or not.
294         **/
295        public void setBound(boolean bound)
296        {
297            this.bound = bound;
298        }
299    
300        /** Get whether the property is constrained.  Defaults to false. **/
301        public boolean isConstrained()
302        {
303            return constrained;
304        }
305    
306        /** Set whether the property is constrained.
307         ** If the set method throws <CODE>java.beans.PropertyVetoException</CODE>
308         ** (or subclass thereof) and the bean implements addVetoableChangeListener()
309         ** and removeVetoableChangeListener(), then setConstrained(true) may safely
310         ** be called.  Otherwise, the system behavior is undefined.
311         ** <B>Spec note:</B> given those strict parameters, it would be nice if it
312         ** got set automatically by detection, but oh well.<P>
313         ** When a property is constrained, its set method is required to:<P>
314         ** <OL>
315         ** <LI>Fire the <CODE>VetoableChangeListener.vetoableChange()</CODE>
316         **     event notifying others of the change and allowing them a chance to
317         **     say it is a bad thing.</LI>
318         ** <LI>If any of the listeners throws a PropertyVetoException, then
319         **     it must fire another vetoableChange() event notifying the others
320         **     of a reversion to the old value (though, of course, the change
321         **     was never made).  Then it rethrows the PropertyVetoException and
322         **     exits.</LI>
323         ** <LI>If all has gone well to this point, the value may be changed.</LI>
324         ** </OL>
325         ** @param constrained whether the property is constrained or not.
326         **/
327        public void setConstrained(boolean constrained)
328        {
329            this.constrained = constrained;
330        }
331    
332        /** Get the PropertyEditor class.  Defaults to null. **/
333        public Class<?> getPropertyEditorClass()
334        {
335            return propertyEditorClass;
336        }
337    
338        /** Set the PropertyEditor class.  If the class does not implement
339         ** the PropertyEditor interface, you will likely get an exception
340         ** late in the game.
341         ** @param propertyEditorClass the PropertyEditor class for this 
342         **        class to use.
343         **/
344        public void setPropertyEditorClass(Class<?> propertyEditorClass)
345        {
346            this.propertyEditorClass = propertyEditorClass;
347        }
348    
349        /**
350         * Instantiate a property editor using the property editor class.
351         * If no property editor class has been set, this will return null.
352         * If the editor class has a public constructor which takes a single
353         * argument, that will be used and the bean parameter will be passed
354         * to it.  Otherwise, a public no-argument constructor will be used,
355         * if available.  This method will return null if no constructor is
356         * found or if construction fails for any reason.
357         * @param bean the argument to the constructor
358         * @return a new PropertyEditor, or null on error
359         * @since 1.5
360         */
361        public PropertyEditor createPropertyEditor(Object bean)
362        {
363          if (propertyEditorClass == null)
364            return null;
365          Constructor c = findConstructor(propertyEditorClass,
366                                          new Class[] { Object.class });
367          if (c != null)
368            return instantiateClass(c, new Object[] { bean });
369          c = findConstructor(propertyEditorClass, null);
370          if (c != null)
371            return instantiateClass(c, null);
372          return null;
373        }
374    
375        // Helper method to look up a constructor and return null if it is not
376        // found.
377        private Constructor findConstructor(Class k, Class[] argTypes)
378        {
379          try
380            {
381              return k.getConstructor(argTypes);
382            }
383          catch (NoSuchMethodException _)
384            {
385              return null;
386            }
387        }
388    
389        // Helper method to instantiate an object but return null on error.
390        private PropertyEditor instantiateClass(Constructor c, Object[] args)
391        {
392          try
393            {
394              return (PropertyEditor) c.newInstance(args);
395            }
396          catch (InstantiationException _)
397            {
398              return null;
399            }
400          catch (InvocationTargetException _)
401            {
402              return null;
403            }
404          catch (IllegalAccessException _)
405            {
406              return null;
407            }
408          catch (ClassCastException _)
409            {
410              return null;
411            }
412        }
413    
414        private void findMethods(
415            Class beanClass,
416            String getMethodName1,
417            String getMethodName2,
418            String setMethodName)
419            throws IntrospectionException
420        {
421            try
422            {
423                // Try the first get method name
424                if (getMethodName1 != null)
425                {
426                    try
427                    {
428                        getMethod =
429                            beanClass.getMethod(getMethodName1, new Class[0]);
430                    }
431                    catch (NoSuchMethodException e)
432                    {}
433                }
434    
435                // Fall back to the second get method name
436                if (getMethod == null && getMethodName2 != null)
437                {
438                    try
439                    {
440                        getMethod =
441                            beanClass.getMethod(getMethodName2, new Class[0]);
442                    }
443                    catch (NoSuchMethodException e)
444                    {}
445                }
446    
447                // Try the set method name
448                if (setMethodName != null)
449                {
450                    if (getMethod != null)
451                    {
452                        // If there is a get method, use its return type to help
453                        // select the corresponding set method.
454                        Class propertyType = getMethod.getReturnType();
455                        if (propertyType == Void.TYPE)
456                        {
457                            String msg =
458                                "The property's read method has return type 'void'";
459                            throw new IntrospectionException(msg);
460                        }
461    
462                        Class[] setArgs = new Class[] { propertyType };
463                        try
464                        {
465                            setMethod = beanClass.getMethod(setMethodName, setArgs);
466                        }
467                        catch (NoSuchMethodException e)
468                        {}
469                    }
470                    else if (getMethodName1 == null && getMethodName2 == null)
471                    {
472                        // If this is a write-only property, choose the first set method
473                        // with the required name, one parameter and return type 'void'
474                        Method[] methods = beanClass.getMethods();
475                        for (int i = 0; i < methods.length; i++)
476                        {
477                            if (methods[i].getName().equals(setMethodName)
478                                && methods[i].getParameterTypes().length == 1
479                                && methods[i].getReturnType() == Void.TYPE)
480                            {
481                                setMethod = methods[i];
482                                break;
483                            }
484                        }
485                    }
486                }
487            }
488            catch (SecurityException e)
489            {
490                // FIXME -- shouldn't we just allow SecurityException to propagate?
491                String msg =
492                    "SecurityException thrown on attempt to access methods.";
493                throw new IntrospectionException(msg);
494            }
495        }
496    
497        /** Checks whether the given <code>Method</code> instances are legal read and
498         * write methods. The following requirements must be met:<br/>
499         * <ul>
500         * <li>the read method must not have an argument</li>
501         * <li>the read method must have a non void return type</li>
502         * <li>the read method may not exist</li>
503         * <li>the write method must have a single argument</li>
504         * <li>the property type and the read method's return type must be assignable from the
505         * write method's argument type</li>
506         * <li>the write method may not exist</li>
507         * </ul>
508         * While checking the methods a common new property type is calculated. If the method
509         * succeeds this property type is returned.<br/>
510         * <br/>
511         * For compatibility this has to be noted:<br/>
512         * The two methods are allowed to be defined in two distinct classes and may both be null.
513         * 
514         * @param readMethod The new read method to check.
515         * @param writeMethod The new write method to check.
516         * @return The common property type of the two method.
517         * @throws IntrospectionException If any of the above requirements are not met.
518         */
519        private Class<?> checkMethods(Method readMethod, Method writeMethod)
520            throws IntrospectionException
521        {
522            Class<?> newPropertyType = propertyType;
523    
524            // a valid read method has zero arguments and a non-void return type.
525            if (readMethod != null)
526            {
527                if (readMethod.getParameterTypes().length > 0)
528                {
529                    throw new IntrospectionException("read method has unexpected parameters");
530                }
531    
532                newPropertyType = readMethod.getReturnType();
533    
534                if (newPropertyType == Void.TYPE)
535                {
536                    throw new IntrospectionException("read method return type is void");
537                }
538            }
539    
540            // a valid write method has one argument which can be assigned to the property
541            if (writeMethod != null)
542            {
543                if (writeMethod.getParameterTypes().length != 1)
544                {
545                    String msg = "write method does not have exactly one parameter";
546                    throw new IntrospectionException(msg);
547                }
548    
549                if (readMethod == null)
550                {
551                    // changes the property type if there is no read method
552                    newPropertyType = writeMethod.getParameterTypes()[0];
553                }
554                else
555                {
556                    // checks whether the write method can be assigned to the return type of the read
557                    // method (if this is not the case, the methods are not compatible)
558                    // note: newPropertyType may be null if no methods or method names have been
559                    // delivered in the constructor.
560                    if (newPropertyType != null
561                        && !newPropertyType.isAssignableFrom(
562                            writeMethod.getParameterTypes()[0]))
563                    {
564                        // note: newPropertyType is the same as readMethod.getReturnType() at this point
565                        throw new IntrospectionException("read and write method are not compatible");
566                    }
567    
568                    /* note: the check whether both method are defined in related classes makes sense but is not
569                     * done in the JDK. 
570                     * I leave this code here in case someone at Sun decides to add that functionality in later versions (rschuster)
571                    if ((!readMethod
572                        .getDeclaringClass()
573                        .isAssignableFrom(writeMethod.getDeclaringClass()))
574                        && (!writeMethod
575                            .getDeclaringClass()
576                            .isAssignableFrom(readMethod.getDeclaringClass())))
577                    {
578                        String msg =
579                            "set and get methods are not in the same class.";
580                        throw new IntrospectionException(msg);
581                    }
582                    */
583    
584                }
585            }
586    
587            return newPropertyType;
588        }
589    
590        /**
591         * Return a hash code for this object, conforming to the contract described
592         * in {@link Object#hashCode()}.
593         * @return the hash code
594         * @since 1.5
595         */
596        public int hashCode()
597        {
598          return ((propertyType == null ? 0 : propertyType.hashCode())
599                  | (propertyEditorClass == null ? 0 : propertyEditorClass.hashCode())
600                  | (bound ? Boolean.TRUE : Boolean.FALSE).hashCode()
601                  | (constrained ? Boolean.TRUE : Boolean.FALSE).hashCode()
602                  | (getMethod == null ? 0 : getMethod.hashCode())
603                  | (setMethod == null ? 0 : setMethod.hashCode()));
604        }
605    
606        /** Compares this <code>PropertyDescriptor</code> against the
607         * given object.
608         * Two PropertyDescriptors are equals if
609         * <ul>
610         * <li>the read methods are equal</li>
611         * <li>the write methods are equal</li>
612         * <li>the property types are equals</li>
613         * <li>the property editor classes are equal</li>
614         * <li>the flags (constrained and bound) are equal</li>
615         * </ul>
616         * @return Whether both objects are equal according to the rules given above.
617         * @since 1.4
618        */
619        public boolean equals(Object o)
620        {
621            if (o instanceof PropertyDescriptor)
622            {
623                PropertyDescriptor that = (PropertyDescriptor) o;
624    
625                // compares the property types and checks the case where both are null
626                boolean samePropertyType =
627                    (propertyType == null)
628                        ? that.propertyType == null
629                        : propertyType.equals(that.propertyType);
630    
631                // compares the property editor classes and checks the case where both are null
632                boolean samePropertyEditorClass =
633                    (propertyEditorClass == null)
634                        ? that.propertyEditorClass == null
635                        : propertyEditorClass.equals(that.propertyEditorClass);
636    
637                // compares the flags for equality
638                boolean sameFlags =
639                    bound == that.bound && constrained == that.constrained;
640    
641                // compares the read methods and checks the case where both are null
642                boolean sameReadMethod =
643                    (getMethod == null)
644                        ? that.getMethod == null
645                        : getMethod.equals(that.getMethod);
646    
647                boolean sameWriteMethod =
648                    (setMethod == null)
649                        ? that.setMethod == null
650                        : setMethod.equals(that.setMethod);
651    
652                return samePropertyType
653                    && sameFlags
654                    && sameReadMethod
655                    && sameWriteMethod
656                    && samePropertyEditorClass;
657            }
658            else
659            {
660                return false;
661            }
662            
663        }
664    
665    }