View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.commons.beanutils;
20  
21  import java.lang.reflect.InvocationTargetException;
22  import java.util.Map;
23  
24  
25  
26  /***
27   * <p>Utility methods for populating JavaBeans properties via reflection.</p>
28   *
29   * <p>The implementations are provided by {@link BeanUtilsBean}.
30   * These static utility methods use the default instance.
31   * More sophisticated behaviour can be provided by using a <code>BeanUtilsBean</code> instance.</p>
32   *
33   * @author Craig R. McClanahan
34   * @author Ralph Schaer
35   * @author Chris Audley
36   * @author Rey Francois
37   * @author Gregor Rayman
38   * @version $Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
39   * @see BeanUtilsBean
40   */
41  
42  public class BeanUtils {
43  
44  
45      // ------------------------------------------------------ Private Variables
46  
47  
48      /***
49       * The debugging detail level for this component.
50       * 
51       * Note that this static variable will have unexpected side-effects if
52       * this class is deployed in a shared classloader within a container.
53       * However as it is actually completely ignored by this class due to its
54       * deprecated status, it doesn't do any actual harm.
55       * 
56       * @deprecated BeanUtils now uses commons-logging for all log messages.
57       *             Use your favorite logging tool to configure logging for
58       *             this class.
59       */
60      private static int debug = 0;
61  
62      /***
63       * The <code>debug</code> static property is no longer used
64       * @return debug property
65       * @deprecated BeanUtils now uses commons-logging for all log messages.
66       *             Use your favorite logging tool to configure logging for
67       *             this class.
68       */
69      public static int getDebug() {
70          return (debug);
71      }
72  
73      /***
74       * The <code>debug</code> static property is no longer used
75       * @param newDebug debug property
76       * @deprecated BeanUtils now uses commons-logging for all log messages.
77       *             Use your favorite logging tool to configure logging for
78       *             this class.
79       */
80      public static void setDebug(int newDebug) {
81          debug = newDebug;
82      }
83  
84      // --------------------------------------------------------- Class Methods
85  
86  
87      /***
88       * <p>Clone a bean based on the available property getters and setters,
89       * even if the bean class itself does not implement Cloneable.</p>
90       *
91       * <p>For more details see <code>BeanUtilsBean</code>.</p>
92       *
93       * @param bean Bean to be cloned
94       * @return the cloned bean
95       *
96       * @exception IllegalAccessException if the caller does not have
97       *  access to the property accessor method
98       * @exception InstantiationException if a new instance of the bean's
99       *  class cannot be instantiated
100      * @exception InvocationTargetException if the property accessor method
101      *  throws an exception
102      * @exception NoSuchMethodException if an accessor method for this
103      *  property cannot be found
104      * @see BeanUtilsBean#cloneBean
105      */
106     public static Object cloneBean(Object bean)
107             throws IllegalAccessException, InstantiationException,
108             InvocationTargetException, NoSuchMethodException {
109 
110         return BeanUtilsBean.getInstance().cloneBean(bean);
111 
112     }
113 
114 
115     /***
116      * <p>Copy property values from the origin bean to the destination bean
117      * for all cases where the property names are the same.</p>
118      *
119      * <p>For more details see <code>BeanUtilsBean</code>.</p>
120      *
121      * @param dest Destination bean whose properties are modified
122      * @param orig Origin bean whose properties are retrieved
123      *
124      * @exception IllegalAccessException if the caller does not have
125      *  access to the property accessor method
126      * @exception IllegalArgumentException if the <code>dest</code> or
127      *  <code>orig</code> argument is null or if the <code>dest</code> 
128      *  property type is different from the source type and the relevant
129      *  converter has not been registered.
130      * @exception InvocationTargetException if the property accessor method
131      *  throws an exception
132      * @see BeanUtilsBean#copyProperties
133      */
134     public static void copyProperties(Object dest, Object orig)
135         throws IllegalAccessException, InvocationTargetException {
136         
137         BeanUtilsBean.getInstance().copyProperties(dest, orig);
138     }
139 
140 
141     /***
142      * <p>Copy the specified property value to the specified destination bean,
143      * performing any type conversion that is required.</p>    
144      *
145      * <p>For more details see <code>BeanUtilsBean</code>.</p>
146      *
147      * @param bean Bean on which setting is to be performed
148      * @param name Property name (can be nested/indexed/mapped/combo)
149      * @param value Value to be set
150      *
151      * @exception IllegalAccessException if the caller does not have
152      *  access to the property accessor method
153      * @exception InvocationTargetException if the property accessor method
154      *  throws an exception
155      * @see BeanUtilsBean#copyProperty     
156      */
157     public static void copyProperty(Object bean, String name, Object value)
158         throws IllegalAccessException, InvocationTargetException {
159 
160         BeanUtilsBean.getInstance().copyProperty(bean, name, value);
161     }
162 
163 
164     /***
165      * <p>Return the entire set of properties for which the specified bean
166      * provides a read method.</p>
167      *
168      * <p>For more details see <code>BeanUtilsBean</code>.</p>
169      *
170      * @param bean Bean whose properties are to be extracted
171      * @return Map of property descriptors
172      *
173      * @exception IllegalAccessException if the caller does not have
174      *  access to the property accessor method
175      * @exception InvocationTargetException if the property accessor method
176      *  throws an exception
177      * @exception NoSuchMethodException if an accessor method for this
178      *  property cannot be found
179      * @see BeanUtilsBean#describe 
180      */
181     public static Map describe(Object bean)
182             throws IllegalAccessException, InvocationTargetException,
183             NoSuchMethodException {
184 
185         return BeanUtilsBean.getInstance().describe(bean);
186     }
187 
188 
189     /***
190      * <p>Return the value of the specified array property of the specified
191      * bean, as a String array.</p>
192      *
193      * <p>For more details see <code>BeanUtilsBean</code>.</p>
194      *
195      * @param bean Bean whose property is to be extracted
196      * @param name Name of the property to be extracted
197      * @return The array property value
198      *
199      * @exception IllegalAccessException if the caller does not have
200      *  access to the property accessor method
201      * @exception InvocationTargetException if the property accessor method
202      *  throws an exception
203      * @exception NoSuchMethodException if an accessor method for this
204      *  property cannot be found
205      * @see BeanUtilsBean#getArrayProperty 
206      */
207     public static String[] getArrayProperty(Object bean, String name)
208             throws IllegalAccessException, InvocationTargetException,
209             NoSuchMethodException {
210 
211         return BeanUtilsBean.getInstance().getArrayProperty(bean, name);
212     }
213 
214 
215     /***
216      * <p>Return the value of the specified indexed property of the specified
217      * bean, as a String.</p>
218      *
219      * <p>For more details see <code>BeanUtilsBean</code>.</p>
220      *
221      * @param bean Bean whose property is to be extracted
222      * @param name <code>propertyname[index]</code> of the property value
223      *  to be extracted
224      * @return The indexed property's value, converted to a String
225      *
226      * @exception IllegalAccessException if the caller does not have
227      *  access to the property accessor method
228      * @exception InvocationTargetException if the property accessor method
229      *  throws an exception
230      * @exception NoSuchMethodException if an accessor method for this
231      *  property cannot be found
232      * @see BeanUtilsBean#getIndexedProperty(Object, String)
233      */
234     public static String getIndexedProperty(Object bean, String name)
235             throws IllegalAccessException, InvocationTargetException,
236             NoSuchMethodException {
237         
238         return BeanUtilsBean.getInstance().getIndexedProperty(bean, name);
239 
240     }
241 
242 
243     /***
244      * Return the value of the specified indexed property of the specified
245      * bean, as a String.  The index is specified as a method parameter and
246      * must *not* be included in the property name expression
247      *
248      * <p>For more details see <code>BeanUtilsBean</code>.</p>
249      *
250      * @param bean Bean whose property is to be extracted
251      * @param name Simple property name of the property value to be extracted
252      * @param index Index of the property value to be extracted
253      * @return The indexed property's value, converted to a String
254      *
255      * @exception IllegalAccessException if the caller does not have
256      *  access to the property accessor method
257      * @exception InvocationTargetException if the property accessor method
258      *  throws an exception
259      * @exception NoSuchMethodException if an accessor method for this
260      *  property cannot be found
261      * @see BeanUtilsBean#getIndexedProperty(Object, String, int)
262      */
263     public static String getIndexedProperty(Object bean,
264                                             String name, int index)
265             throws IllegalAccessException, InvocationTargetException,
266             NoSuchMethodException {
267 
268         return BeanUtilsBean.getInstance().getIndexedProperty(bean, name, index);
269 
270     }
271 
272 
273     /***
274      * </p>Return the value of the specified indexed property of the specified
275      * bean, as a String.</p>
276      *
277      * <p>For more details see <code>BeanUtilsBean</code>.</p>
278      *
279      * @param bean Bean whose property is to be extracted
280      * @param name <code>propertyname(index)</code> of the property value
281      *  to be extracted
282      * @return The mapped property's value, converted to a String
283      *
284      * @exception IllegalAccessException if the caller does not have
285      *  access to the property accessor method
286      * @exception InvocationTargetException if the property accessor method
287      *  throws an exception
288      * @exception NoSuchMethodException if an accessor method for this
289      *  property cannot be found
290      * @see BeanUtilsBean#getMappedProperty(Object, String)
291      */
292     public static String getMappedProperty(Object bean, String name)
293             throws IllegalAccessException, InvocationTargetException,
294             NoSuchMethodException {
295 
296         return BeanUtilsBean.getInstance().getMappedProperty(bean, name);
297 
298     }
299 
300 
301     /***
302      * </p>Return the value of the specified mapped property of the specified
303      * bean, as a String.</p>
304      *
305      * <p>For more details see <code>BeanUtilsBean</code>.</p>
306      *
307      * @param bean Bean whose property is to be extracted
308      * @param name Simple property name of the property value to be extracted
309      * @param key Lookup key of the property value to be extracted
310      * @return The mapped property's value, converted to a String
311      *
312      * @exception IllegalAccessException if the caller does not have
313      *  access to the property accessor method
314      * @exception InvocationTargetException if the property accessor method
315      *  throws an exception
316      * @exception NoSuchMethodException if an accessor method for this
317      *  property cannot be found
318      * @see BeanUtilsBean#getMappedProperty(Object, String, String)
319      */
320     public static String getMappedProperty(Object bean,
321                                            String name, String key)
322             throws IllegalAccessException, InvocationTargetException,
323             NoSuchMethodException {
324 
325         return BeanUtilsBean.getInstance().getMappedProperty(bean, name, key);
326 
327     }
328 
329 
330     /***
331      * <p>Return the value of the (possibly nested) property of the specified
332      * name, for the specified bean, as a String.</p>
333      *
334      * <p>For more details see <code>BeanUtilsBean</code>.</p>
335      *
336      * @param bean Bean whose property is to be extracted
337      * @param name Possibly nested name of the property to be extracted
338      * @return The nested property's value, converted to a String
339      *
340      * @exception IllegalAccessException if the caller does not have
341      *  access to the property accessor method
342      * @exception IllegalArgumentException if a nested reference to a
343      *  property returns null
344      * @exception InvocationTargetException if the property accessor method
345      *  throws an exception
346      * @exception NoSuchMethodException if an accessor method for this
347      *  property cannot be found
348      * @see BeanUtilsBean#getNestedProperty
349      */
350     public static String getNestedProperty(Object bean, String name)
351             throws IllegalAccessException, InvocationTargetException,
352             NoSuchMethodException {
353 
354         return BeanUtilsBean.getInstance().getNestedProperty(bean, name);
355 
356     }
357 
358 
359     /***
360      * <p>Return the value of the specified property of the specified bean,
361      * no matter which property reference format is used, as a String.</p>
362      *
363      * <p>For more details see <code>BeanUtilsBean</code>.</p>
364      *
365      * @param bean Bean whose property is to be extracted
366      * @param name Possibly indexed and/or nested name of the property
367      *  to be extracted
368      * @return The property's value, converted to a String
369      *
370      * @exception IllegalAccessException if the caller does not have
371      *  access to the property accessor method
372      * @exception InvocationTargetException if the property accessor method
373      *  throws an exception
374      * @exception NoSuchMethodException if an accessor method for this
375      *  property cannot be found
376      * @see BeanUtilsBean#getProperty
377      */
378     public static String getProperty(Object bean, String name)
379             throws IllegalAccessException, InvocationTargetException,
380             NoSuchMethodException {
381 
382         return BeanUtilsBean.getInstance().getProperty(bean, name);
383 
384     }
385 
386 
387     /***
388      * <p>Return the value of the specified simple property of the specified
389      * bean, converted to a String.</p>
390      *
391      * <p>For more details see <code>BeanUtilsBean</code>.</p>
392      *
393      * @param bean Bean whose property is to be extracted
394      * @param name Name of the property to be extracted
395      * @return The property's value, converted to a String
396      *
397      * @exception IllegalAccessException if the caller does not have
398      *  access to the property accessor method
399      * @exception InvocationTargetException if the property accessor method
400      *  throws an exception
401      * @exception NoSuchMethodException if an accessor method for this
402      *  property cannot be found
403      * @see BeanUtilsBean#getSimpleProperty
404      */
405     public static String getSimpleProperty(Object bean, String name)
406             throws IllegalAccessException, InvocationTargetException,
407             NoSuchMethodException {
408 
409         return BeanUtilsBean.getInstance().getSimpleProperty(bean, name);
410 
411     }
412 
413 
414     /***
415      * <p>Populate the JavaBeans properties of the specified bean, based on
416      * the specified name/value pairs.</p>
417      *
418      * <p>For more details see <code>BeanUtilsBean</code>.</p>
419      *
420      * @param bean JavaBean whose properties are being populated
421      * @param properties Map keyed by property name, with the
422      *  corresponding (String or String[]) value(s) to be set
423      *
424      * @exception IllegalAccessException if the caller does not have
425      *  access to the property accessor method
426      * @exception InvocationTargetException if the property accessor method
427      *  throws an exception
428      * @see BeanUtilsBean#populate
429      */
430     public static void populate(Object bean, Map properties)
431         throws IllegalAccessException, InvocationTargetException {
432         
433         BeanUtilsBean.getInstance().populate(bean, properties);
434     }
435 
436 
437     /***
438      * <p>Set the specified property value, performing type conversions as
439      * required to conform to the type of the destination property.</p>
440      *
441      * <p>For more details see <code>BeanUtilsBean</code>.</p>
442      *
443      * @param bean Bean on which setting is to be performed
444      * @param name Property name (can be nested/indexed/mapped/combo)
445      * @param value Value to be set
446      *
447      * @exception IllegalAccessException if the caller does not have
448      *  access to the property accessor method
449      * @exception InvocationTargetException if the property accessor method
450      *  throws an exception
451      * @see BeanUtilsBean#setProperty
452      */
453     public static void setProperty(Object bean, String name, Object value)
454         throws IllegalAccessException, InvocationTargetException {
455 
456         BeanUtilsBean.getInstance().setProperty(bean, name, value);
457     }
458 
459     /*** 
460      * If we're running on JDK 1.4 or later, initialize the cause for the given throwable.
461      * 
462      * @param  throwable The throwable.
463      * @param  cause     The cause of the throwable.
464      * @return  true if the cause was initialized, otherwise false.
465      */
466     public static boolean initCause(Throwable throwable, Throwable cause) {
467         return BeanUtilsBean.getInstance().initCause(throwable, cause);
468     }
469 }