    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}