KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > beanutils > PropertyUtils


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 JavaDoc;
21 import java.lang.reflect.InvocationTargetException JavaDoc;
22 import java.lang.reflect.Method JavaDoc;
23 import java.util.Map JavaDoc;
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 JavaDoc dest, Object JavaDoc orig)
137             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
138             NoSuchMethodException JavaDoc {
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 JavaDoc describe(Object JavaDoc bean)
153             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
154             NoSuchMethodException JavaDoc {
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 JavaDoc getIndexedProperty(Object JavaDoc bean, String JavaDoc name)
170             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
171             NoSuchMethodException JavaDoc {
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 JavaDoc getIndexedProperty(Object JavaDoc bean,
187                                             String JavaDoc name, int index)
188             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
189             NoSuchMethodException JavaDoc {
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 JavaDoc getMappedProperty(Object JavaDoc bean, String JavaDoc name)
204             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
205             NoSuchMethodException JavaDoc {
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 JavaDoc getMappedProperty(Object JavaDoc bean,
221                                            String JavaDoc name, String JavaDoc key)
222             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
223             NoSuchMethodException JavaDoc {
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 JavaDoc 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 JavaDoc 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 JavaDoc getNestedProperty(Object JavaDoc bean, String JavaDoc name)
269             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
270             NoSuchMethodException JavaDoc {
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 JavaDoc getProperty(Object JavaDoc bean, String JavaDoc name)
287             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
288             NoSuchMethodException JavaDoc {
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 JavaDoc getPropertyDescriptor(Object JavaDoc bean,
305                                                            String JavaDoc name)
306             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
307             NoSuchMethodException JavaDoc {
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 JavaDoc[]
324             getPropertyDescriptors(Class JavaDoc 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 JavaDoc[] getPropertyDescriptors(Object JavaDoc 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 JavaDoc getPropertyEditorClass(Object JavaDoc bean, String JavaDoc name)
356             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
357             NoSuchMethodException JavaDoc {
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 JavaDoc getPropertyType(Object JavaDoc bean, String JavaDoc name)
374             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
375             NoSuchMethodException JavaDoc {
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 JavaDoc getReadMethod(PropertyDescriptor JavaDoc 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 JavaDoc getSimpleProperty(Object JavaDoc bean, String JavaDoc name)
405             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
406             NoSuchMethodException JavaDoc {
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 JavaDoc getWriteMethod(PropertyDescriptor JavaDoc 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 JavaDoc bean, String JavaDoc 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 JavaDoc bean, String JavaDoc 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 JavaDoc bean, String JavaDoc name,
469                                           Object JavaDoc value)
470             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
471             NoSuchMethodException JavaDoc {
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 JavaDoc bean, String JavaDoc name,
487                                           int index, Object JavaDoc value)
488             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
489             NoSuchMethodException JavaDoc {
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 JavaDoc bean, String JavaDoc name,
504                                          Object JavaDoc value)
505             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
506             NoSuchMethodException JavaDoc {
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 JavaDoc bean, String JavaDoc name,
521                                          String JavaDoc key, Object JavaDoc value)
522             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
523             NoSuchMethodException JavaDoc {
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 JavaDoc bean,
538                                          String JavaDoc name, Object JavaDoc value)
539             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
540             NoSuchMethodException JavaDoc {
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 JavaDoc bean, String JavaDoc name, Object JavaDoc value)
556             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
557             NoSuchMethodException JavaDoc {
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 JavaDoc bean,
573                                          String JavaDoc name, Object JavaDoc value)
574             throws IllegalAccessException JavaDoc, InvocationTargetException JavaDoc,
575             NoSuchMethodException JavaDoc {
576
577         PropertyUtilsBean.getInstance().setSimpleProperty(bean, name, value);
578     }
579
580
581 }
582
Popular Tags