View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  
17  
18  package org.apache.commons.beanutils;
19  
20  import java.beans.PropertyDescriptor;
21  import java.lang.reflect.InvocationTargetException;
22  import java.lang.reflect.Method;
23  import java.util.Map;
24  
25  import org.apache.commons.collections.FastHashMap;
26  
27  
28  /**
29   * <p>Utility methods for using Java Reflection APIs to facilitate generic
30   * property getter and setter operations on Java objects.</p>
31   *
32   * <p>The implementations for these methods are provided by <code>PropertyUtilsBean</code>.
33   * For more details see {@link PropertyUtilsBean}.</p>
34   *
35   * @author Craig R. McClanahan
36   * @author Ralph Schaer
37   * @author Chris Audley
38   * @author Rey Fran?ois
39   * @author Gregor Ra?man
40   * @author Jan Sorensen
41   * @author Scott Sanders
42   * @version $Revision: 1.42.2.1 $ $Date: 2004/07/27 21:31:00 $
43   * @see PropertyUtilsBean
44   */
45  
46  public class PropertyUtils {
47  
48  
49      // ----------------------------------------------------- Manifest Constants
50  
51  
52      /**
53       * The delimiter that preceeds the zero-relative subscript for an
54       * indexed reference.
55       */
56      public static final char INDEXED_DELIM = '[';
57  
58  
59      /**
60       * The delimiter that follows the zero-relative subscript for an
61       * indexed reference.
62       */
63      public static final char INDEXED_DELIM2 = ']';
64  
65  
66      /**
67       * The delimiter that preceeds the key of a mapped property.
68       */
69      public static final char MAPPED_DELIM = '(';
70  
71  
72      /**
73       * The delimiter that follows the key of a mapped property.
74       */
75      public static final char MAPPED_DELIM2 = ')';
76  
77  
78      /**
79       * The delimiter that separates the components of a nested reference.
80       */
81      public static final char NESTED_DELIM = '.';
82  
83  
84      // ------------------------------------------------------- Static Variables
85  
86  
87      /**
88       * The debugging detail level for this component.
89       * @deprecated The <code>debug</code> static property is no longer used
90       */
91      private static int debug = 0;
92  
93      /**
94       * @deprecated The <code>debug</code> static property is no longer used
95       */
96      public static int getDebug() {
97          return (debug);
98      }
99  
100     /**
101      * @deprecated The <code>debug</code> static property is no longer used
102      */
103     public static void setDebug(int newDebug) {
104         debug = newDebug;
105     }
106 
107     // --------------------------------------------------------- Public Methods
108 
109 
110     /**
111      * Clear any cached property descriptors information for all classes
112      * loaded by any class loaders.  This is useful in cases where class
113      * loaders are thrown away to implement class reloading.
114      *
115      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
116      *
117      * @see PropertyUtilsBean#clearDescriptors  
118      */
119     public static void clearDescriptors() {
120 	
121         PropertyUtilsBean.getInstance().clearDescriptors();
122 
123     }
124 
125 
126     /**
127      * <p>Copy property values from the "origin" bean to the "destination" bean
128      * for all cases where the property names are the same (even though the
129      * actual getter and setter methods might have been customized via
130      * <code>BeanInfo</code> classes).</p>
131      *
132      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
133      *
134      * @see PropertyUtilsBean#copyProperties  
135      */
136     public static void copyProperties(Object dest, Object orig)
137             throws IllegalAccessException, InvocationTargetException,
138             NoSuchMethodException {
139 
140         PropertyUtilsBean.getInstance().copyProperties(dest, orig);
141     }
142 
143 
144     /**
145      * <p>Return the entire set of properties for which the specified bean
146      * provides a read method.</p>
147      *
148      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
149      *
150      * @see PropertyUtilsBean#describe  
151      */
152     public static Map describe(Object bean)
153             throws IllegalAccessException, InvocationTargetException,
154             NoSuchMethodException {
155 
156         return (PropertyUtilsBean.getInstance().describe(bean));
157 
158     }
159 
160 
161     /**
162      * <p>Return the value of the specified indexed property of the specified
163      * bean, with no type conversions.</p>
164      *
165      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
166      *
167      * @see PropertyUtilsBean#getIndexedProperty(Object,String)  
168      */
169     public static Object getIndexedProperty(Object bean, String name)
170             throws IllegalAccessException, InvocationTargetException,
171             NoSuchMethodException {
172 
173         return (PropertyUtilsBean.getInstance().getIndexedProperty(bean, name));
174 
175     }
176 
177 
178     /**
179      * <p>Return the value of the specified indexed property of the specified
180      * bean, with no type conversions.</p>
181      *
182      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
183      *
184      * @see PropertyUtilsBean#getIndexedProperty(Object,String, int)  
185      */
186     public static Object getIndexedProperty(Object bean,
187                                             String name, int index)
188             throws IllegalAccessException, InvocationTargetException,
189             NoSuchMethodException {
190 
191         return (PropertyUtilsBean.getInstance().getIndexedProperty(bean, name, index));
192     }
193 
194 
195     /**
196      * <p>Return the value of the specified mapped property of the
197      * specified bean, with no type conversions.</p>
198      *
199      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
200      *
201      * @see PropertyUtilsBean#getMappedProperty(Object,String)  
202      */
203     public static Object getMappedProperty(Object bean, String name)
204             throws IllegalAccessException, InvocationTargetException,
205             NoSuchMethodException {
206 
207         return (PropertyUtilsBean.getInstance().getMappedProperty(bean, name));
208 
209     }
210 
211 
212     /**
213      * <p>Return the value of the specified mapped property of the specified
214      * bean, with no type conversions.</p>
215      *
216      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
217      *
218      * @see PropertyUtilsBean#getMappedProperty(Object,String, String)  
219      */
220     public static Object getMappedProperty(Object bean,
221                                            String name, String key)
222             throws IllegalAccessException, InvocationTargetException,
223             NoSuchMethodException {
224 
225         return PropertyUtilsBean.getInstance().getMappedProperty(bean, name, key);
226 
227     }
228 
229 
230     /**
231      * <p>Return the mapped property descriptors for this bean class.</p>
232      *
233      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
234      *
235      * @see PropertyUtilsBean#getMappedPropertyDescriptors(Class)
236      * @deprecated This method should not be exposed
237      */
238     public static FastHashMap getMappedPropertyDescriptors(Class beanClass) {
239 	
240         return PropertyUtilsBean.getInstance().getMappedPropertyDescriptors(beanClass);
241 
242     }
243 
244 
245     /**
246      * <p>Return the mapped property descriptors for this bean.</p>
247      *
248      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
249      *
250      * @see PropertyUtilsBean#getMappedPropertyDescriptors(Object)
251      * @deprecated This method should not be exposed
252      */
253     public static FastHashMap getMappedPropertyDescriptors(Object bean) {
254 
255 	return PropertyUtilsBean.getInstance().getMappedPropertyDescriptors(bean);
256 
257     }
258 
259 
260     /**
261      * <p>Return the value of the (possibly nested) property of the specified
262      * name, for the specified bean, with no type conversions.</p>
263      *
264      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
265      *
266      * @see PropertyUtilsBean#getNestedProperty
267      */
268     public static Object getNestedProperty(Object bean, String name)
269             throws IllegalAccessException, InvocationTargetException,
270             NoSuchMethodException {
271 
272         return PropertyUtilsBean.getInstance().getNestedProperty(bean, name);
273         
274     }
275 
276 
277     /**
278      * <p>Return the value of the specified property of the specified bean,
279      * no matter which property reference format is used, with no
280      * type conversions.</p>
281      *
282      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
283      *
284      * @see PropertyUtilsBean#getProperty
285      */
286     public static Object getProperty(Object bean, String name)
287             throws IllegalAccessException, InvocationTargetException,
288             NoSuchMethodException {
289 
290         return (PropertyUtilsBean.getInstance().getProperty(bean, name));
291 
292     }
293 
294 
295     /**
296      * <p>Retrieve the property descriptor for the specified property of the
297      * specified bean, or return <code>null</code> if there is no such
298      * descriptor.</p>
299      *
300      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
301      *
302      * @see PropertyUtilsBean#getPropertyDescriptor
303      */
304     public static PropertyDescriptor getPropertyDescriptor(Object bean,
305                                                            String name)
306             throws IllegalAccessException, InvocationTargetException,
307             NoSuchMethodException {
308 
309         return PropertyUtilsBean.getInstance().getPropertyDescriptor(bean, name);
310 
311     }
312 
313 
314     /**
315      * <p>Retrieve the property descriptors for the specified class,
316      * introspecting and caching them the first time a particular bean class
317      * is encountered.</p>
318      *
319      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
320      *
321      * @see PropertyUtilsBean#getPropertyDescriptors(Class)
322      */
323     public static PropertyDescriptor[]
324             getPropertyDescriptors(Class beanClass) {
325 
326         return PropertyUtilsBean.getInstance().getPropertyDescriptors(beanClass);
327 
328     }
329 
330 
331     /**
332      * <p>Retrieve the property descriptors for the specified bean,
333      * introspecting and caching them the first time a particular bean class
334      * is encountered.</p>
335      *
336      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
337      *
338      * @see PropertyUtilsBean#getPropertyDescriptors(Object)
339      */
340     public static PropertyDescriptor[] getPropertyDescriptors(Object bean) {
341 
342         return PropertyUtilsBean.getInstance().getPropertyDescriptors(bean);
343 
344     }
345 
346 
347     /**
348      * <p>Return the Java Class repesenting the property editor class that has
349      * been registered for this property (if any).</p>
350      *
351      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
352      *
353      * @see PropertyUtilsBean#getPropertyEditorClass(Object,String)
354      */
355     public static Class getPropertyEditorClass(Object bean, String name)
356             throws IllegalAccessException, InvocationTargetException,
357             NoSuchMethodException {
358 
359 	return PropertyUtilsBean.getInstance().getPropertyEditorClass(bean, name);
360 
361     }
362 
363 
364     /**
365      * <p>Return the Java Class representing the property type of the specified
366      * property, or <code>null</code> if there is no such property for the
367      * specified bean.</p>
368      *
369      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
370      *
371      * @see PropertyUtilsBean#getPropertyType
372      */
373     public static Class getPropertyType(Object bean, String name)
374             throws IllegalAccessException, InvocationTargetException,
375             NoSuchMethodException {
376 
377         return PropertyUtilsBean.getInstance().getPropertyType(bean, name);
378     }
379 
380 
381     /**
382      * <p>Return an accessible property getter method for this property,
383      * if there is one; otherwise return <code>null</code>.</p>
384      *
385      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
386      *
387      * @see PropertyUtilsBean#getReadMethod
388      */
389     public static Method getReadMethod(PropertyDescriptor descriptor) {
390 
391         return (PropertyUtilsBean.getInstance().getReadMethod(descriptor));
392 
393     }
394 
395 
396     /**
397      * <p>Return the value of the specified simple property of the specified
398      * bean, with no type conversions.</p>
399      *
400      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
401      *
402      * @see PropertyUtilsBean#getSimpleProperty
403      */
404     public static Object getSimpleProperty(Object bean, String name)
405             throws IllegalAccessException, InvocationTargetException,
406             NoSuchMethodException {
407 
408         return PropertyUtilsBean.getInstance().getSimpleProperty(bean, name);
409         
410     }
411 
412 
413     /**
414      * <p>Return an accessible property setter method for this property,
415      * if there is one; otherwise return <code>null</code>.</p>
416      *
417      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
418      *
419      * @see PropertyUtilsBean#getWriteMethod
420      */
421     public static Method getWriteMethod(PropertyDescriptor descriptor) {
422 
423         return PropertyUtilsBean.getInstance().getWriteMethod(descriptor);
424 
425     }
426 
427 
428     /**
429      * <p>Return <code>true</code> if the specified property name identifies
430      * a readable property on the specified bean; otherwise, return
431      * <code>false</code>.</p>
432      *
433      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
434      *
435      * @see PropertyUtilsBean#isReadable
436      * @since BeanUtils 1.6
437      */
438     public static boolean isReadable(Object bean, String name) {
439 
440         return PropertyUtilsBean.getInstance().isReadable(bean, name);
441     }
442 
443 
444     /**
445      * <p>Return <code>true</code> if the specified property name identifies
446      * a writeable property on the specified bean; otherwise, return
447      * <code>false</code>.</p>
448      *
449      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
450      *
451      * @see PropertyUtilsBean#isWriteable
452      * @since BeanUtils 1.6
453      */
454     public static boolean isWriteable(Object bean, String name) {
455 
456 	return PropertyUtilsBean.getInstance().isWriteable(bean, name);
457     }
458 
459 
460     /**
461      * <p>Sets the value of the specified indexed property of the specified
462      * bean, with no type conversions.</p>
463      *
464      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
465      *
466      * @see PropertyUtilsBean#setIndexedProperty(Object, String, Object)
467      */
468     public static void setIndexedProperty(Object bean, String name,
469                                           Object value)
470             throws IllegalAccessException, InvocationTargetException,
471             NoSuchMethodException {
472 
473         PropertyUtilsBean.getInstance().setIndexedProperty(bean, name, value);
474 
475     }
476 
477 
478     /**
479      * <p>Sets the value of the specified indexed property of the specified
480      * bean, with no type conversions.</p>
481      *
482      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
483      *
484      * @see PropertyUtilsBean#setIndexedProperty(Object, String, Object)
485      */
486     public static void setIndexedProperty(Object bean, String name,
487                                           int index, Object value)
488             throws IllegalAccessException, InvocationTargetException,
489             NoSuchMethodException {
490 
491         PropertyUtilsBean.getInstance().setIndexedProperty(bean, name, index, value);
492     }
493 
494 
495     /**
496      * <p>Sets the value of the specified mapped property of the
497      * specified bean, with no type conversions.</p>
498      *
499      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
500      *
501      * @see PropertyUtilsBean#setMappedProperty(Object, String, Object)
502      */
503     public static void setMappedProperty(Object bean, String name,
504                                          Object value)
505             throws IllegalAccessException, InvocationTargetException,
506             NoSuchMethodException {
507 
508         PropertyUtilsBean.getInstance().setMappedProperty(bean, name, value);
509     }
510 
511 
512     /**
513      * <p>Sets the value of the specified mapped property of the specified
514      * bean, with no type conversions.</p>
515      *
516      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
517      *
518      * @see PropertyUtilsBean#setMappedProperty(Object, String, String, Object)
519      */
520     public static void setMappedProperty(Object bean, String name,
521                                          String key, Object value)
522             throws IllegalAccessException, InvocationTargetException,
523             NoSuchMethodException {
524 
525         PropertyUtilsBean.getInstance().setMappedProperty(bean, name, key, value);
526     }
527 
528 
529     /**
530      * <p>Sets the value of the (possibly nested) property of the specified
531      * name, for the specified bean, with no type conversions.</p>
532      *
533      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
534      *
535      * @see PropertyUtilsBean#setNestedProperty
536      */
537     public static void setNestedProperty(Object bean,
538                                          String name, Object value)
539             throws IllegalAccessException, InvocationTargetException,
540             NoSuchMethodException {
541 
542         PropertyUtilsBean.getInstance().setNestedProperty(bean, name, value);
543     }
544 
545 
546     /**
547      * <p>Set the value of the specified property of the specified bean,
548      * no matter which property reference format is used, with no
549      * type conversions.</p>
550      *
551      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
552      *
553      * @see PropertyUtilsBean#setProperty
554      */
555     public static void setProperty(Object bean, String name, Object value)
556             throws IllegalAccessException, InvocationTargetException,
557             NoSuchMethodException {
558 
559         PropertyUtilsBean.getInstance().setProperty(bean, name, value);
560 
561     }
562 
563 
564     /**
565      * <p>Set the value of the specified simple property of the specified bean,
566      * with no type conversions.</p>
567      *
568      * <p>For more details see <code>PropertyUtilsBean</code>.</p>
569      *
570      * @see PropertyUtilsBean#setSimpleProperty
571      */
572     public static void setSimpleProperty(Object bean,
573                                          String name, Object value)
574             throws IllegalAccessException, InvocationTargetException,
575             NoSuchMethodException {
576 
577         PropertyUtilsBean.getInstance().setSimpleProperty(bean, name, value);
578     }
579 
580 
581 }