    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 *      https://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.beanutils2.locale;
    019
    020import java.lang.reflect.InvocationTargetException;
    021import java.util.Locale;
    022
    023/**
    024 * <p>
    025 * Utility methods for populating JavaBeans properties via reflection in a locale-dependent manner.
    026 * </p>
    027 *
    028 * <p>
    029 * The implementations for these methods are provided by {@code LocaleBeanUtilsBean}. For more details see {@link LocaleBeanUtilsBean}.
    030 * </p>
    031 */
    032public final class LocaleBeanUtils {
    033
    034    /**
    035     * <p>
    036     * Converts the specified value to the required type.
    037     * </p>
    038     *
    039     * <p>
    040     * For more details see {@code LocaleBeanUtilsBean}
    041     * </p>
    042     *
    043     * @param type  The Java type of target property
    044     * @param index The indexed subscript value (if any)
    045     * @param value The value to be converted
    046     * @return The converted value
    047     * @see LocaleBeanUtilsBean#convert(Class, int, Object)
    048     */
    049    protected static Object convert(final Class<?> type, final int index, final Object value) {
    050        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().convert(type, index, value);
    051    }
    052
    053    /**
    054     * <p>
    055     * Converts the specified value to the required type using the specified conversion pattern.
    056     * </p>
    057     *
    058     * <p>
    059     * For more details see {@code LocaleBeanUtilsBean}
    060     * </p>
    061     *
    062     * @param type    The Java type of target property
    063     * @param index   The indexed subscript value (if any)
    064     * @param value   The value to be converted
    065     * @param pattern The conversion pattern
    066     * @return The converted value
    067     * @see LocaleBeanUtilsBean#convert(Class, int, Object, String)
    068     */
    069    protected static Object convert(final Class<?> type, final int index, final Object value, final String pattern) {
    070        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().convert(type, index, value, pattern);
    071    }
    072
    073    /**
    074     * <p>
    075     * Calculate the property type.
    076     * </p>
    077     *
    078     * <p>
    079     * For more details see {@code LocaleBeanUtilsBean}
    080     * </p>
    081     *
    082     * @param target   The bean
    083     * @param name     The property name
    084     * @param propName The Simple name of target property
    085     * @return The property's type
    086     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    087     * @throws InvocationTargetException if the property accessor method throws an exception
    088     * @see LocaleBeanUtilsBean#definePropertyType(Object, String, String)
    089     */
    090    protected static Class<?> definePropertyType(final Object target, final String name, final String propName)
    091            throws IllegalAccessException, InvocationTargetException {
    092        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().definePropertyType(target, name, propName);
    093    }
    094
    095    /**
    096     * <p>
    097     * Gets whether the pattern is localized or not.
    098     * </p>
    099     *
    100     * <p>
    101     * For more details see {@code LocaleBeanUtilsBean}
    102     * </p>
    103     *
    104     * @return {@code true} if pattern is localized, otherwise {@code false}
    105     * @see LocaleBeanUtilsBean#getApplyLocalized()
    106     */
    107    public static boolean getApplyLocalized() {
    108        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getApplyLocalized();
    109    }
    110
    111    /**
    112     * <p>
    113     * Gets the locale used when no locale is passed.
    114     * </p>
    115     *
    116     * <p>
    117     * For more details see {@code LocaleBeanUtilsBean}
    118     * </p>
    119     *
    120     * @return the default locale
    121     * @see LocaleBeanUtilsBean#getDefaultLocale()
    122     */
    123    public static Locale getDefaultLocale() {
    124        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getDefaultLocale();
    125    }
    126
    127    /**
    128     * Gets the value of the specified locale-sensitive indexed property of the specified bean, as a String using the default conversion pattern of the
    129     * corresponding {@link LocaleConverter}.
    130     *
    131     * <p>
    132     * For more details see {@code LocaleBeanUtilsBean}
    133     * </p>
    134     *
    135     * @param bean Bean whose property is to be extracted
    136     * @param name {@code propertyname[index]} of the property value to be extracted
    137     * @return The indexed property's value, converted to a String
    138     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    139     * @throws InvocationTargetException if the property accessor method throws an exception
    140     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    141     * @see LocaleBeanUtilsBean#getIndexedProperty(Object, String)
    142     */
    143    public static String getIndexedProperty(final Object bean, final String name)
    144            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    145        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getIndexedProperty(bean, name);
    146    }
    147
    148    /**
    149     * <p>
    150     * Return the value of the specified locale-sensitive indexed property of the specified bean, as a String using the default conversion pattern of the
    151     * corresponding {@link LocaleConverter}.
    152     * </p>
    153     *
    154     * <p>
    155     * For more details see {@code LocaleBeanUtilsBean}
    156     * </p>
    157     *
    158     * @param bean  Bean whose property is to be extracted
    159     * @param name  Simple property name of the property value to be extracted
    160     * @param index Index of the property value to be extracted
    161     * @return The indexed property's value, converted to a String
    162     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    163     * @throws InvocationTargetException if the property accessor method throws an exception
    164     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    165     * @see LocaleBeanUtilsBean#getIndexedProperty(Object, String, int)
    166     */
    167    public static String getIndexedProperty(final Object bean, final String name, final int index)
    168            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    169        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getIndexedProperty(bean, name, index);
    170    }
    171
    172    /**
    173     * <p>
    174     * Return the value of the specified locale-sensitive indexed property of the specified bean, as a String using the specified conversion pattern.
    175     * </p>
    176     *
    177     * <p>
    178     * For more details see {@code LocaleBeanUtilsBean}
    179     * </p>
    180     *
    181     * @param bean    Bean whose property is to be extracted
    182     * @param name    Simple property name of the property value to be extracted
    183     * @param index   Index of the property value to be extracted
    184     * @param pattern The conversion pattern
    185     * @return The indexed property's value, converted to a String
    186     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    187     * @throws InvocationTargetException if the property accessor method throws an exception
    188     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    189     * @see LocaleBeanUtilsBean#getIndexedProperty(Object, String, int, String)
    190     */
    191    public static String getIndexedProperty(final Object bean, final String name, final int index, final String pattern)
    192            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    193        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getIndexedProperty(bean, name, index, pattern);
    194    }
    195
    196    /**
    197     * <p>
    198     * Return the value of the specified locale-sensitive indexed property of the specified bean, as a String.
    199     * </p>
    200     *
    201     * <p>
    202     * For more details see {@code LocaleBeanUtilsBean}
    203     * </p>
    204     *
    205     * @param bean    Bean whose property is to be extracted
    206     * @param name    {@code propertyname[index]} of the property value to be extracted
    207     * @param pattern The conversion pattern
    208     * @return The indexed property's value, converted to a String
    209     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    210     * @throws InvocationTargetException if the property accessor method throws an exception
    211     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    212     * @see LocaleBeanUtilsBean#getIndexedProperty(Object, String, String)
    213     */
    214    public static String getIndexedProperty(final Object bean, final String name, final String pattern)
    215            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    216        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getIndexedProperty(bean, name, pattern);
    217    }
    218
    219    /**
    220     * <p>
    221     * Return the value of the specified locale-sensitive mapped property of the specified bean, as a String using the default conversion pattern of the
    222     * corresponding {@link LocaleConverter}.
    223     * </p>
    224     *
    225     * <p>
    226     * For more details see {@code LocaleBeanUtilsBean}
    227     * </p>
    228     *
    229     * @param bean Bean whose property is to be extracted
    230     * @param name {@code propertyname(index)} of the property value to be extracted
    231     * @return The mapped property's value, converted to a String
    232     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    233     * @throws InvocationTargetException if the property accessor method throws an exception
    234     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    235     * @see LocaleBeanUtilsBean#getMappedProperty(Object, String)
    236     */
    237    public static String getMappedProperty(final Object bean, final String name)
    238            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    239        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getMappedProperty(bean, name);
    240    }
    241
    242    /**
    243     * <p>
    244     * Return the value of the specified mapped locale-sensitive property of the specified bean, as a String The key is specified as a method parameter and must
    245     * *not* be included in the property name expression.
    246     * </p>
    247     *
    248     * <p>
    249     * For more details see {@code LocaleBeanUtilsBean}
    250     * </p>
    251     *
    252     * @param bean Bean whose property is to be extracted
    253     * @param name Simple property name of the property value to be extracted
    254     * @param key  Lookup key of the property value to be extracted
    255     * @return The mapped property's value, converted to a String
    256     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    257     * @throws InvocationTargetException if the property accessor method throws an exception
    258     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    259     * @see LocaleBeanUtilsBean#getMappedProperty(Object, String, String)
    260     */
    261    public static String getMappedProperty(final Object bean, final String name, final String key)
    262            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    263        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getMappedProperty(bean, name, key);
    264    }
    265
    266    /**
    267     * <p>
    268     * Return the value of the specified mapped locale-sensitive property of the specified bean, as a String using the specified conversion pattern.
    269     * </p>
    270     *
    271     * <p>
    272     * For more details see {@code LocaleBeanUtilsBean}
    273     * </p>
    274     *
    275     * @param bean    Bean whose property is to be extracted
    276     * @param name    Simple property name of the property value to be extracted
    277     * @param key     Lookup key of the property value to be extracted
    278     * @param pattern The conversion pattern
    279     * @return The mapped property's value, converted to a String
    280     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    281     * @throws InvocationTargetException if the property accessor method throws an exception
    282     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    283     * @see LocaleBeanUtilsBean#getMappedProperty(Object, String, String, String)
    284     */
    285    public static String getMappedProperty(final Object bean, final String name, final String key, final String pattern)
    286            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    287        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getMappedProperty(bean, name, key, pattern);
    288    }
    289
    290    /**
    291     * <p>
    292     * Return the value of the specified locale-sensitive mapped property of the specified bean, as a String using the specified pattern.
    293     * </p>
    294     *
    295     * <p>
    296     * For more details see {@code LocaleBeanUtilsBean}
    297     * </p>
    298     *
    299     * @param bean    Bean whose property is to be extracted
    300     * @param name    {@code propertyname(index)} of the property value to be extracted
    301     * @param pattern The conversion pattern
    302     * @return The mapped property's value, converted to a String
    303     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    304     * @throws InvocationTargetException if the property accessor method throws an exception
    305     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    306     * @see LocaleBeanUtilsBean#getMappedPropertyLocale(Object, String, String)
    307     */
    308    public static String getMappedPropertyLocale(final Object bean, final String name, final String pattern)
    309            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    310        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getMappedPropertyLocale(bean, name, pattern);
    311    }
    312
    313    /**
    314     * <p>
    315     * Return the value of the (possibly nested) locale-sensitive property of the specified name.
    316     * </p>
    317     *
    318     * <p>
    319     * For more details see {@code LocaleBeanUtilsBean}
    320     * </p>
    321     *
    322     * @param bean Bean whose property is to be extracted
    323     * @param name Possibly nested name of the property to be extracted
    324     * @return The nested property's value, converted to a String
    325     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    326     * @throws InvocationTargetException if the property accessor method throws an exception
    327     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    328     * @see LocaleBeanUtilsBean#getNestedProperty(Object, String)
    329     */
    330    public static String getNestedProperty(final Object bean, final String name)
    331            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    332        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getNestedProperty(bean, name);
    333    }
    334
    335    /**
    336     * <p>
    337     * Return the value of the (possibly nested) locale-sensitive property of the specified name, for the specified bean, as a String using the specified
    338     * pattern.
    339     * </p>
    340     *
    341     * <p>
    342     * For more details see {@code LocaleBeanUtilsBean}
    343     * </p>
    344     *
    345     * @param bean    Bean whose property is to be extracted
    346     * @param name    Possibly nested name of the property to be extracted
    347     * @param pattern The conversion pattern
    348     * @return The nested property's value, converted to a String
    349     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    350     * @throws InvocationTargetException if the property accessor method throws an exception
    351     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    352     * @see LocaleBeanUtilsBean#getNestedProperty(Object, String, String)
    353     */
    354    public static String getNestedProperty(final Object bean, final String name, final String pattern)
    355            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    356        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getNestedProperty(bean, name, pattern);
    357    }
    358
    359    /**
    360     * <p>
    361     * Return the value of the specified locale-sensitive property of the specified bean.
    362     * </p>
    363     *
    364     * <p>
    365     * For more details see {@code LocaleBeanUtilsBean}
    366     * </p>
    367     *
    368     * @param bean Bean whose property is to be extracted
    369     * @param name Possibly indexed and/or nested name of the property to be extracted
    370     * @return The property's value, converted to a String
    371     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    372     * @throws InvocationTargetException if the property accessor method throws an exception
    373     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    374     * @see LocaleBeanUtilsBean#getProperty(Object, String)
    375     */
    376    public static String getProperty(final Object bean, final String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    377        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getProperty(bean, name);
    378    }
    379
    380    /**
    381     * <p>
    382     * Return the value of the specified locale-sensitive property of the specified bean.
    383     * </p>
    384     *
    385     * <p>
    386     * For more details see {@code LocaleBeanUtilsBean}
    387     * </p>
    388     *
    389     * @param bean    Bean whose property is to be extracted
    390     * @param name    Possibly indexed and/or nested name of the property to be extracted
    391     * @param pattern The conversion pattern
    392     * @return The nested property's value, converted to a String
    393     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    394     * @throws InvocationTargetException if the property accessor method throws an exception
    395     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    396     * @see LocaleBeanUtilsBean#getProperty(Object, String, String)
    397     */
    398    public static String getProperty(final Object bean, final String name, final String pattern)
    399            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    400        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getProperty(bean, name, pattern);
    401    }
    402
    403    /**
    404     * <p>
    405     * Return the value of the specified simple locale-sensitive property of the specified bean, converted to a String using the default conversion pattern of
    406     * the corresponding {@link LocaleConverter}.
    407     * </p>
    408     *
    409     * <p>
    410     * For more details see {@code LocaleBeanUtilsBean}
    411     * </p>
    412     *
    413     * @param bean Bean whose property is to be extracted
    414     * @param name Name of the property to be extracted
    415     * @return The property's value, converted to a String
    416     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    417     * @throws InvocationTargetException if the property accessor method throws an exception
    418     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    419     * @see LocaleBeanUtilsBean#getSimpleProperty(Object, String)
    420     */
    421    public static String getSimpleProperty(final Object bean, final String name)
    422            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    423        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getSimpleProperty(bean, name);
    424    }
    425
    426    /**
    427     * <p>
    428     * Return the value of the specified simple locale-sensitive property of the specified bean, converted to a String using the specified conversion pattern.
    429     * </p>
    430     *
    431     * <p>
    432     * For more details see {@code LocaleBeanUtilsBean}
    433     * </p>
    434     *
    435     * @param bean    Bean whose property is to be extracted
    436     * @param name    Name of the property to be extracted
    437     * @param pattern The conversion pattern
    438     * @return The property's value, converted to a String
    439     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    440     * @throws InvocationTargetException if the property accessor method throws an exception
    441     * @throws NoSuchMethodException     if an accessor method for this property cannot be found
    442     * @see LocaleBeanUtilsBean#getSimpleProperty(Object, String, String)
    443     */
    444    public static String getSimpleProperty(final Object bean, final String name, final String pattern)
    445            throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {
    446        return LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().getSimpleProperty(bean, name, pattern);
    447    }
    448
    449    /**
    450     * <p>
    451     * Invoke the setter method.
    452     * </p>
    453     *
    454     * <p>
    455     * For more details see {@code LocaleBeanUtilsBean}
    456     * </p>
    457     *
    458     * @param target   The bean
    459     * @param propName The Simple name of target property
    460     * @param key      The Mapped key value (if any)
    461     * @param index    The indexed subscript value (if any)
    462     * @param newValue The value to be set
    463     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    464     * @throws InvocationTargetException if the property accessor method throws an exception
    465     * @see LocaleBeanUtilsBean#invokeSetter(Object, String, String, int, Object)
    466     */
    467    protected static void invokeSetter(final Object target, final String propName, final String key, final int index, final Object newValue)
    468            throws IllegalAccessException, InvocationTargetException {
    469        LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().invokeSetter(target, propName, key, index, newValue);
    470    }
    471
    472    /**
    473     * <p>
    474     * Sets whether the pattern is localized or not.
    475     * </p>
    476     *
    477     * <p>
    478     * For more details see {@code LocaleBeanUtilsBean}
    479     * </p>
    480     *
    481     * @param newApplyLocalized {@code true} if pattern is localized, otherwise {@code false}
    482     * @see LocaleBeanUtilsBean#setApplyLocalized(boolean)
    483     */
    484    public static void setApplyLocalized(final boolean newApplyLocalized) {
    485        LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().setApplyLocalized(newApplyLocalized);
    486    }
    487
    488    /**
    489     * <p>
    490     * Sets the locale used when no locale is passed.
    491     * </p>
    492     *
    493     * <p>
    494     * For more details see {@code LocaleBeanUtilsBean}
    495     * </p>
    496     *
    497     * @param locale the default locale
    498     * @see LocaleBeanUtilsBean#setDefaultLocale(Locale)
    499     */
    500    public static void setDefaultLocale(final Locale locale) {
    501        LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().setDefaultLocale(locale);
    502    }
    503
    504    /**
    505     * <p>
    506     * Set the specified locale-sensitive property value, performing type conversions as required to conform to the type of the destination property using the
    507     * default conversion pattern of the corresponding {@link LocaleConverter}.
    508     * </p>
    509     *
    510     * <p>
    511     * For more details see {@code LocaleBeanUtilsBean}
    512     * </p>
    513     *
    514     * @param bean  Bean on which setting is to be performed
    515     * @param name  Property name (can be nested/indexed/mapped/combo)
    516     * @param value Value to be set
    517     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    518     * @throws InvocationTargetException if the property accessor method throws an exception
    519     * @see LocaleBeanUtilsBean#setProperty(Object, String, Object)
    520     */
    521    public static void setProperty(final Object bean, final String name, final Object value) throws IllegalAccessException, InvocationTargetException {
    522        LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().setProperty(bean, name, value);
    523    }
    524
    525    /**
    526     * <p>
    527     * Set the specified locale-sensitive property value, performing type conversions as required to conform to the type of the destination property using the
    528     * specified conversion pattern.
    529     * </p>
    530     *
    531     * <p>
    532     * For more details see {@code LocaleBeanUtilsBean}
    533     * </p>
    534     *
    535     * @param bean    Bean on which setting is to be performed
    536     * @param name    Property name (can be nested/indexed/mapped/combo)
    537     * @param value   Value to be set
    538     * @param pattern The conversion pattern
    539     * @throws IllegalAccessException    if the caller does not have access to the property accessor method
    540     * @throws InvocationTargetException if the property accessor method throws an exception
    541     * @see LocaleBeanUtilsBean#setProperty(Object, String, Object, String)
    542     */
    543    public static void setProperty(final Object bean, final String name, final Object value, final String pattern)
    544            throws IllegalAccessException, InvocationTargetException {
    545        LocaleBeanUtilsBean.getLocaleBeanUtilsInstance().setProperty(bean, name, value, pattern);
    546    }
    547
    548    private LocaleBeanUtils() {
    549        // empty
    550    }
    551}