001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.beanutils;
019
020import java.lang.reflect.InvocationTargetException;
021import java.util.Map;
022
023/**
024 * <p>Utility methods for populating JavaBeans properties via reflection.</p>
025 *
026 * <p>The implementations are provided by {@link BeanUtilsBean}.
027 * These static utility methods use the default instance.
028 * More sophisticated behavior can be provided by using a <code>BeanUtilsBean</code> instance.</p>
029 *
030 * @see BeanUtilsBean
031 */
032public class BeanUtils {
033
034    /**
035     * The debugging detail level for this component.
036     *
037     * Note that this static variable will have unexpected side-effects if
038     * this class is deployed in a shared classloader within a container.
039     * However as it is actually completely ignored by this class due to its
040     * deprecated status, it doesn't do any actual harm.
041     *
042     * @deprecated BeanUtils now uses commons-logging for all log messages.
043     *             Use your favorite logging tool to configure logging for
044     *             this class.
045     */
046    @Deprecated
047    private static int debug;
048
049    /**
050     * <p>Clone a bean based on the available property getters and setters,
051     * even if the bean class itself does not implement Cloneable.</p>
052     *
053     * <p>For more details see <code>BeanUtilsBean</code>.</p>
054     *
055     * @param bean Bean to be cloned
056     * @return the cloned bean
057     * @throws IllegalAccessException if the caller does not have
058     *  access to the property accessor method
059     * @throws InstantiationException if a new instance of the bean's
060     *  class cannot be instantiated
061     * @throws InvocationTargetException if the property accessor method
062     *  throws an exception
063     * @throws NoSuchMethodException if an accessor method for this
064     *  property cannot be found
065     * @see BeanUtilsBean#cloneBean
066     */
067    public static Object cloneBean(final Object bean)
068            throws IllegalAccessException, InstantiationException,
069            InvocationTargetException, NoSuchMethodException {
070        return BeanUtilsBean.getInstance().cloneBean(bean);
071    }
072
073    /**
074     * <p>Copy property values from the origin bean to the destination bean
075     * for all cases where the property names are the same.</p>
076     *
077     * <p>For more details see <code>BeanUtilsBean</code>.</p>
078     *
079     * @param dest Destination bean whose properties are modified
080     * @param orig Origin bean whose properties are retrieved
081     * @throws IllegalAccessException if the caller does not have
082     *  access to the property accessor method
083     * @throws IllegalArgumentException if the <code>dest</code> or
084     *  <code>orig</code> argument is null or if the <code>dest</code>
085     *  property type is different from the source type and the relevant
086     *  converter has not been registered.
087     * @throws InvocationTargetException if the property accessor method
088     *  throws an exception
089     * @see BeanUtilsBean#copyProperties
090     */
091    public static void copyProperties(final Object dest, final Object orig)
092        throws IllegalAccessException, InvocationTargetException {
093        BeanUtilsBean.getInstance().copyProperties(dest, orig);
094    }
095
096    /**
097     * <p>Copy the specified property value to the specified destination bean,
098     * performing any type conversion that is required.</p>
099     *
100     * <p>For more details see <code>BeanUtilsBean</code>.</p>
101     *
102     * @param bean Bean on which setting is to be performed
103     * @param name Property name (can be nested/indexed/mapped/combo)
104     * @param value Value to be set
105     * @throws IllegalAccessException if the caller does not have
106     *  access to the property accessor method
107     * @throws InvocationTargetException if the property accessor method
108     *  throws an exception
109     * @see BeanUtilsBean#copyProperty
110     */
111    public static void copyProperty(final Object bean, final String name, final Object value)
112        throws IllegalAccessException, InvocationTargetException {
113        BeanUtilsBean.getInstance().copyProperty(bean, name, value);
114    }
115
116    /**
117     * Create a cache.
118     * @param <K> the key type of the cache
119     * @param <V> the value type of the cache
120     * @return a new cache
121     * @since 1.8.0
122     */
123    public static <K, V> Map<K, V> createCache() {
124        return new WeakFastHashMap<>();
125    }
126
127    /**
128     * <p>Return the entire set of properties for which the specified bean
129     * provides a read method.</p>
130     *
131     * <p>For more details see <code>BeanUtilsBean</code>.</p>
132     *
133     * @param bean Bean whose properties are to be extracted
134     * @return Map of property descriptors
135     * @throws IllegalAccessException if the caller does not have
136     *  access to the property accessor method
137     * @throws InvocationTargetException if the property accessor method
138     *  throws an exception
139     * @throws NoSuchMethodException if an accessor method for this
140     *  property cannot be found
141     * @see BeanUtilsBean#describe
142     */
143    public static Map<String, String> describe(final Object bean)
144            throws IllegalAccessException, InvocationTargetException,
145            NoSuchMethodException {
146        return BeanUtilsBean.getInstance().describe(bean);
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     * @param bean Bean whose property is to be extracted
156     * @param name Name of the property to be extracted
157     * @return The array property value
158     * @throws IllegalAccessException if the caller does not have
159     *  access to the property accessor method
160     * @throws InvocationTargetException if the property accessor method
161     *  throws an exception
162     * @throws NoSuchMethodException if an accessor method for this
163     *  property cannot be found
164     * @see BeanUtilsBean#getArrayProperty
165     */
166    public static String[] getArrayProperty(final Object bean, final String name)
167            throws IllegalAccessException, InvocationTargetException,
168            NoSuchMethodException {
169        return BeanUtilsBean.getInstance().getArrayProperty(bean, name);
170    }
171
172    /**
173     * Return whether a Map is fast
174     * @param map The map
175     * @return Whether it is fast or not.
176     * @since 1.8.0
177     */
178    public static boolean getCacheFast(final Map<?, ?> map) {
179        if (map instanceof WeakFastHashMap) {
180            return ((WeakFastHashMap<?, ?>) map).getFast();
181        }
182        return false;
183    }
184
185    /**
186     * The <code>debug</code> static property is no longer used
187     * @return debug property
188     * @deprecated BeanUtils now uses commons-logging for all log messages.
189     *             Use your favorite logging tool to configure logging for
190     *             this class.
191     */
192    @Deprecated
193    public static int getDebug() {
194        return debug;
195    }
196
197    /**
198     * <p>Return the value of the specified indexed property of the specified
199     * bean, as a String.</p>
200     *
201     * <p>For more details see <code>BeanUtilsBean</code>.</p>
202     *
203     * @param bean Bean whose property is to be extracted
204     * @param name <code>propertyname[index]</code> of the property value
205     *  to be extracted
206     * @return The indexed property's value, converted to a String
207     * @throws IllegalAccessException if the caller does not have
208     *  access to the property accessor method
209     * @throws InvocationTargetException if the property accessor method
210     *  throws an exception
211     * @throws NoSuchMethodException if an accessor method for this
212     *  property cannot be found
213     * @see BeanUtilsBean#getIndexedProperty(Object, String)
214     */
215    public static String getIndexedProperty(final Object bean, final String name)
216            throws IllegalAccessException, InvocationTargetException,
217            NoSuchMethodException {
218        return BeanUtilsBean.getInstance().getIndexedProperty(bean, name);
219    }
220
221    /**
222     * Return the value of the specified indexed property of the specified
223     * bean, as a String.  The index is specified as a method parameter and
224     * must *not* be included in the property name expression
225     *
226     * <p>For more details see <code>BeanUtilsBean</code>.</p>
227     *
228     * @param bean Bean whose property is to be extracted
229     * @param name Simple property name of the property value to be extracted
230     * @param index Index of the property value to be extracted
231     * @return The indexed property's value, converted to a String
232     * @throws IllegalAccessException if the caller does not have
233     *  access to the property accessor method
234     * @throws InvocationTargetException if the property accessor method
235     *  throws an exception
236     * @throws NoSuchMethodException if an accessor method for this
237     *  property cannot be found
238     * @see BeanUtilsBean#getIndexedProperty(Object, String, int)
239     */
240    public static String getIndexedProperty(final Object bean,
241                                            final String name, final int index)
242            throws IllegalAccessException, InvocationTargetException,
243            NoSuchMethodException {
244        return BeanUtilsBean.getInstance().getIndexedProperty(bean, name, index);
245
246    }
247
248    /**
249     * <p>Return the value of the specified indexed property of the specified
250     * bean, as a String.</p>
251     *
252     * <p>For more details see <code>BeanUtilsBean</code>.</p>
253     *
254     * @param bean Bean whose property is to be extracted
255     * @param name <code>propertyname(index)</code> of the property value
256     *  to be extracted
257     * @return The mapped property's value, converted to a String
258     * @throws IllegalAccessException if the caller does not have
259     *  access to the property accessor method
260     * @throws InvocationTargetException if the property accessor method
261     *  throws an exception
262     * @throws NoSuchMethodException if an accessor method for this
263     *  property cannot be found
264     * @see BeanUtilsBean#getMappedProperty(Object, String)
265     */
266    public static String getMappedProperty(final Object bean, final String name)
267            throws IllegalAccessException, InvocationTargetException,
268            NoSuchMethodException {
269        return BeanUtilsBean.getInstance().getMappedProperty(bean, name);
270    }
271
272    /**
273     * <p>Return the value of the specified mapped property of the specified
274     * bean, as a String.</p>
275     *
276     * <p>For more details see <code>BeanUtilsBean</code>.</p>
277     *
278     * @param bean Bean whose property is to be extracted
279     * @param name Simple property name of the property value to be extracted
280     * @param key Lookup key of the property value to be extracted
281     * @return The mapped property's value, converted to a String
282     * @throws IllegalAccessException if the caller does not have
283     *  access to the property accessor method
284     * @throws InvocationTargetException if the property accessor method
285     *  throws an exception
286     * @throws NoSuchMethodException if an accessor method for this
287     *  property cannot be found
288     * @see BeanUtilsBean#getMappedProperty(Object, String, String)
289     */
290    public static String getMappedProperty(final Object bean,
291                                           final String name, final String key)
292            throws IllegalAccessException, InvocationTargetException,
293            NoSuchMethodException {
294        return BeanUtilsBean.getInstance().getMappedProperty(bean, name, key);
295
296    }
297
298    /**
299     * <p>Return the value of the (possibly nested) property of the specified
300     * name, for the specified bean, as a String.</p>
301     *
302     * <p>For more details see <code>BeanUtilsBean</code>.</p>
303     *
304     * @param bean Bean whose property is to be extracted
305     * @param name Possibly nested name of the property to be extracted
306     * @return The nested property's value, converted to a String
307     * @throws IllegalAccessException if the caller does not have
308     *  access to the property accessor method
309     * @throws IllegalArgumentException if a nested reference to a
310     *  property returns null
311     * @throws InvocationTargetException if the property accessor method
312     *  throws an exception
313     * @throws NoSuchMethodException if an accessor method for this
314     *  property cannot be found
315     * @see BeanUtilsBean#getNestedProperty
316     */
317    public static String getNestedProperty(final Object bean, final String name)
318            throws IllegalAccessException, InvocationTargetException,
319            NoSuchMethodException {
320        return BeanUtilsBean.getInstance().getNestedProperty(bean, name);
321
322    }
323
324    /**
325     * <p>Return the value of the specified property of the specified bean,
326     * no matter which property reference format is used, as a String.</p>
327     *
328     * <p>For more details see <code>BeanUtilsBean</code>.</p>
329     *
330     * @param bean Bean whose property is to be extracted
331     * @param name Possibly indexed and/or nested name of the property
332     *  to be extracted
333     * @return The property's value, converted to a String
334     * @throws IllegalAccessException if the caller does not have
335     *  access to the property accessor method
336     * @throws InvocationTargetException if the property accessor method
337     *  throws an exception
338     * @throws NoSuchMethodException if an accessor method for this
339     *  property cannot be found
340     * @see BeanUtilsBean#getProperty
341     */
342    public static String getProperty(final Object bean, final String name)
343            throws IllegalAccessException, InvocationTargetException,
344            NoSuchMethodException {
345        return BeanUtilsBean.getInstance().getProperty(bean, name);
346    }
347
348    /**
349     * <p>Return the value of the specified simple property of the specified
350     * bean, converted to a String.</p>
351     *
352     * <p>For more details see <code>BeanUtilsBean</code>.</p>
353     *
354     * @param bean Bean whose property is to be extracted
355     * @param name Name of the property to be extracted
356     * @return The property's value, converted to a String
357     * @throws IllegalAccessException if the caller does not have
358     *  access to the property accessor method
359     * @throws InvocationTargetException if the property accessor method
360     *  throws an exception
361     * @throws NoSuchMethodException if an accessor method for this
362     *  property cannot be found
363     * @see BeanUtilsBean#getSimpleProperty
364     */
365    public static String getSimpleProperty(final Object bean, final String name)
366            throws IllegalAccessException, InvocationTargetException,
367            NoSuchMethodException {
368        return BeanUtilsBean.getInstance().getSimpleProperty(bean, name);
369    }
370
371    /**
372     * If we're running on JDK 1.4 or later, initialize the cause for the given throwable.
373     *
374     * @param  throwable The throwable.
375     * @param  cause     The cause of the throwable.
376     * @return  always true in 1.10.0.
377     * @since 1.8.0
378     * @deprecated Use {@link Throwable#initCause(Throwable)}.
379     * @see Throwable#initCause(Throwable)
380     */
381    @Deprecated
382    public static boolean initCause(final Throwable throwable, final Throwable cause) {
383        throwable.initCause(cause);
384        return true;
385    }
386
387    /**
388     * <p>Populate the JavaBeans properties of the specified bean, based on
389     * the specified name/value pairs.</p>
390     *
391     * <p>For more details see <code>BeanUtilsBean</code>.</p>
392     *
393     * @param bean JavaBean whose properties are being populated
394     * @param properties Map keyed by property name, with the
395     *  corresponding (String or String[]) value(s) to be set
396     *
397     * @throws IllegalAccessException if the caller does not have
398     *  access to the property accessor method
399     * @throws InvocationTargetException if the property accessor method
400     *  throws an exception
401     * @see BeanUtilsBean#populate
402     */
403    public static void populate(final Object bean, final Map<String, ? extends Object> properties)
404        throws IllegalAccessException, InvocationTargetException {
405        BeanUtilsBean.getInstance().populate(bean, properties);
406    }
407
408    /**
409     * Set whether fast on a Map
410     * @param map The map
411     * @param fast Whether it should be fast or not.
412     * @since 1.8.0
413     */
414    public static void setCacheFast(final Map<?, ?> map, final boolean fast) {
415        if (map instanceof WeakFastHashMap) {
416            ((WeakFastHashMap<?, ?>)map).setFast(fast);
417        }
418    }
419
420    /**
421     * The <code>debug</code> static property is no longer used
422     * @param newDebug debug property
423     * @deprecated BeanUtils now uses commons-logging for all log messages.
424     *             Use your favorite logging tool to configure logging for
425     *             this class.
426     */
427    @Deprecated
428    public static void setDebug(final int newDebug) {
429        debug = newDebug;
430    }
431
432    /**
433     * <p>Set the specified property value, performing type conversions as
434     * required to conform to the type of the destination property.</p>
435     *
436     * <p>For more details see <code>BeanUtilsBean</code>.</p>
437     *
438     * @param bean Bean on which setting is to be performed
439     * @param name Property name (can be nested/indexed/mapped/combo)
440     * @param value Value to be set
441     * @throws IllegalAccessException if the caller does not have
442     *  access to the property accessor method
443     * @throws InvocationTargetException if the property accessor method
444     *  throws an exception
445     * @see BeanUtilsBean#setProperty
446     */
447    public static void setProperty(final Object bean, final String name, final Object value)
448        throws IllegalAccessException, InvocationTargetException {
449        BeanUtilsBean.getInstance().setProperty(bean, name, value);
450    }
451
452    /**
453     * Deprecated, all methods are static.
454     *
455     * @deprecated Will be private in 2.0.
456     */
457    @Deprecated
458    public BeanUtils() {
459        // empty
460    }
461}