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.lang.reflect.InvocationTargetException;
21  import java.util.Map;
22  
23  import org.apache.commons.collections.FastHashMap;
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 Fran?ois
37   * @author Gregor Ra?man
38   * @version $Revision: 1.40 $ $Date: 2004/02/28 13:18:33 $
39   * @see BeanUtilsBean
40   */
41  
42  public class BeanUtils {
43  
44  
45      // ------------------------------------------------------ Private Variables
46  
47  
48      /**
49       * Dummy collection from the Commons Collections API, to force a
50       * ClassNotFoundException if commons-collections.jar is not present in the
51       * runtime classpath, and this class is the first one referenced.
52       * Otherwise, the ClassNotFoundException thrown by ConvertUtils or
53       * PropertyUtils can get masked.
54       */
55      private static FastHashMap dummy = new FastHashMap();
56  
57      /**
58       * The debugging detail level for this component.
59       * @deprecated BeanUtils now uses commons-logging for all log messages.
60       *             Use your favorite logging tool to configure logging for
61       *             this class.
62       */
63      private static int debug = 0;
64  
65      /**
66       * @deprecated BeanUtils now uses commons-logging for all log messages.
67       *             Use your favorite logging tool to configure logging for
68       *             this class.
69       */
70      public static int getDebug() {
71          return (debug);
72      }
73  
74      /**
75       * @deprecated BeanUtils now uses commons-logging for all log messages.
76       *             Use your favorite logging tool to configure logging for
77       *             this class.
78       */
79      public static void setDebug(int newDebug) {
80          debug = newDebug;
81      }
82  
83      // --------------------------------------------------------- Class Methods
84  
85  
86      /**
87       * <p>Clone a bean based on the available property getters and setters,
88       * even if the bean class itself does not implement Cloneable.</p>
89       *
90       * <p>For more details see <code>BeanUtilsBean</code>.</p>
91       *
92       * @see BeanUtilsBean#cloneBean
93       */
94      public static Object cloneBean(Object bean)
95              throws IllegalAccessException, InstantiationException,
96              InvocationTargetException, NoSuchMethodException {
97  
98          return BeanUtilsBean.getInstance().cloneBean(bean);
99  
100     }
101 
102 
103     /**
104      * <p>Copy property values from the origin bean to the destination bean
105      * for all cases where the property names are the same.</p>
106      *
107      * <p>For more details see <code>BeanUtilsBean</code>.</p>
108      *
109      * @see BeanUtilsBean#copyProperties
110      */
111     public static void copyProperties(Object dest, Object orig)
112         throws IllegalAccessException, InvocationTargetException {
113         
114         BeanUtilsBean.getInstance().copyProperties(dest, orig);
115     }
116 
117 
118     /**
119      * <p>Copy the specified property value to the specified destination bean,
120      * performing any type conversion that is required.</p>    
121      *
122      * <p>For more details see <code>BeanUtilsBean</code>.</p>
123      *
124      * @see BeanUtilsBean#copyProperty     
125      */
126     public static void copyProperty(Object bean, String name, Object value)
127         throws IllegalAccessException, InvocationTargetException {
128 
129         BeanUtilsBean.getInstance().copyProperty(bean, name, value);
130     }
131 
132 
133     /**
134      * <p>Return the entire set of properties for which the specified bean
135      * provides a read method.</p>
136      *
137      * <p>For more details see <code>BeanUtilsBean</code>.</p>
138      *
139      * @see BeanUtilsBean#describe 
140      */
141     public static Map describe(Object bean)
142             throws IllegalAccessException, InvocationTargetException,
143             NoSuchMethodException {
144 
145         return BeanUtilsBean.getInstance().describe(bean);
146     }
147 
148 
149     /**
150      * <p>Return the value of the specified array property of the specified
151      * bean, as a String array.</p>
152      *
153      * <p>For more details see <code>BeanUtilsBean</code>.</p>
154      *
155      * @see BeanUtilsBean#getArrayProperty 
156      */
157     public static String[] getArrayProperty(Object bean, String name)
158             throws IllegalAccessException, InvocationTargetException,
159             NoSuchMethodException {
160 
161         return BeanUtilsBean.getInstance().getArrayProperty(bean, name);
162     }
163 
164 
165     /**
166      * <p>Return the value of the specified indexed property of the specified
167      * bean, as a String.</p>
168      *
169      * <p>For more details see <code>BeanUtilsBean</code>.</p>
170      *
171      * @see BeanUtilsBean#getIndexedProperty(Object, String)
172      */
173     public static String getIndexedProperty(Object bean, String name)
174             throws IllegalAccessException, InvocationTargetException,
175             NoSuchMethodException {
176         
177         return BeanUtilsBean.getInstance().getIndexedProperty(bean, name);
178 
179     }
180 
181 
182     /**
183      * Return the value of the specified indexed property of the specified
184      * bean, as a String.  The index is specified as a method parameter and
185      * must *not* be included in the property name expression
186      *
187      * <p>For more details see <code>BeanUtilsBean</code>.</p>
188      *
189      * @see BeanUtilsBean#getIndexedProperty(Object, String, int)
190      */
191     public static String getIndexedProperty(Object bean,
192                                             String name, int index)
193             throws IllegalAccessException, InvocationTargetException,
194             NoSuchMethodException {
195 
196 	return BeanUtilsBean.getInstance().getIndexedProperty(bean, name, index);
197 
198     }
199 
200 
201     /**
202      * </p>Return the value of the specified indexed property of the specified
203      * bean, as a String.</p>
204      *
205      * <p>For more details see <code>BeanUtilsBean</code>.</p>
206      *
207      * @see BeanUtilsBean#getMappedProperty(Object, String)
208      */
209     public static String getMappedProperty(Object bean, String name)
210             throws IllegalAccessException, InvocationTargetException,
211             NoSuchMethodException {
212 
213         return BeanUtilsBean.getInstance().getMappedProperty(bean, name);
214 
215     }
216 
217 
218     /**
219      * </p>Return the value of the specified mapped property of the specified
220      * bean, as a String.</p>
221      *
222      * <p>For more details see <code>BeanUtilsBean</code>.</p>
223      *
224      * @see BeanUtilsBean#getMappedProperty(Object, String, String)
225      */
226     public static String getMappedProperty(Object bean,
227                                            String name, String key)
228             throws IllegalAccessException, InvocationTargetException,
229             NoSuchMethodException {
230 
231         return BeanUtilsBean.getInstance().getMappedProperty(bean, name, key);
232 
233     }
234 
235 
236     /**
237      * <p>Return the value of the (possibly nested) property of the specified
238      * name, for the specified bean, as a String.</p>
239      *
240      * <p>For more details see <code>BeanUtilsBean</code>.</p>
241      *
242      * @see BeanUtilsBean#getNestedProperty
243      */
244     public static String getNestedProperty(Object bean, String name)
245             throws IllegalAccessException, InvocationTargetException,
246             NoSuchMethodException {
247 
248 	return BeanUtilsBean.getInstance().getNestedProperty(bean, name);
249 
250     }
251 
252 
253     /**
254      * <p>Return the value of the specified property of the specified bean,
255      * no matter which property reference format is used, as a String.</p>
256      *
257      * <p>For more details see <code>BeanUtilsBean</code>.</p>
258      *
259      * @see BeanUtilsBean#getProperty
260      */
261     public static String getProperty(Object bean, String name)
262             throws IllegalAccessException, InvocationTargetException,
263             NoSuchMethodException {
264 
265         return BeanUtilsBean.getInstance().getProperty(bean, name);
266 
267     }
268 
269 
270     /**
271      * <p>Return the value of the specified simple property of the specified
272      * bean, converted to a String.</p>
273      *
274      * <p>For more details see <code>BeanUtilsBean</code>.</p>
275      *
276      * @see BeanUtilsBean#getSimpleProperty
277      */
278     public static String getSimpleProperty(Object bean, String name)
279             throws IllegalAccessException, InvocationTargetException,
280             NoSuchMethodException {
281 
282 	return BeanUtilsBean.getInstance().getSimpleProperty(bean, name);
283 
284     }
285 
286 
287     /**
288      * <p>Populate the JavaBeans properties of the specified bean, based on
289      * the specified name/value pairs.</p>
290      *
291      * <p>For more details see <code>BeanUtilsBean</code>.</p>
292      *
293      * @see BeanUtilsBean#populate
294      */
295     public static void populate(Object bean, Map properties)
296         throws IllegalAccessException, InvocationTargetException {
297         
298         BeanUtilsBean.getInstance().populate(bean, properties);
299     }
300 
301 
302     /**
303      * <p>Set the specified property value, performing type conversions as
304      * required to conform to the type of the destination property.</p>
305      *
306      * <p>For more details see <code>BeanUtilsBean</code>.</p>
307      *
308      * @see BeanUtilsBean#setProperty
309      */
310     public static void setProperty(Object bean, String name, Object value)
311         throws IllegalAccessException, InvocationTargetException {
312 
313         BeanUtilsBean.getInstance().setProperty(bean, name, value);
314     }
315 }