    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.beanutils2.locale;
    019
    020import java.util.Locale;
    021
    022/**
    023 * <p>
    024 * Utility methods for converting locale-sensitive String scalar values to objects of the specified Class, String arrays to arrays of the specified Class and
    025 * object to locale-sensitive String scalar value.
    026 * </p>
    027 *
    028 * <p>
    029 * The implementations for these method are provided by {@link LocaleConvertUtilsBean}. These static utility method use the default instance. More sophisticated
    030 * can be provided by using a {@code LocaleConvertUtilsBean} instance.
    031 * </p>
    032 */
    033public class LocaleConvertUtils {
    034
    035    /**
    036     * <p>
    037     * Converts the specified locale-sensitive value into a String.
    038     * </p>
    039     *
    040     * <p>
    041     * For more details see {@code LocaleConvertUtilsBean}
    042     * </p>
    043     *
    044     * @param value The Value to be converted
    045     * @return the converted value
    046     * @see LocaleConvertUtilsBean#convert(Object)
    047     */
    048    public static String convert(final Object value) {
    049        return LocaleConvertUtilsBean.getInstance().convert(value);
    050    }
    051
    052    /**
    053     * <p>
    054     * Converts the specified locale-sensitive value into a String using the particular conversion pattern.
    055     * </p>
    056     *
    057     * <p>
    058     * For more details see {@code LocaleConvertUtilsBean}
    059     * </p>
    060     *
    061     * @param value   The Value to be converted
    062     * @param locale  The locale
    063     * @param pattern The conversion pattern
    064     * @return the converted value
    065     * @see LocaleConvertUtilsBean#convert(Object, Locale, String)
    066     */
    067    public static String convert(final Object value, final Locale locale, final String pattern) {
    068        return LocaleConvertUtilsBean.getInstance().convert(value, locale, pattern);
    069    }
    070
    071    /**
    072     * <p>
    073     * Converts the specified locale-sensitive value into a String using the conversion pattern.
    074     * </p>
    075     *
    076     * <p>
    077     * For more details see {@code LocaleConvertUtilsBean}
    078     * </p>
    079     *
    080     * @param value   The Value to be converted
    081     * @param pattern The conversion pattern
    082     * @return the converted value
    083     * @see LocaleConvertUtilsBean#convert(Object, String)
    084     */
    085    public static String convert(final Object value, final String pattern) {
    086        return LocaleConvertUtilsBean.getInstance().convert(value, pattern);
    087    }
    088
    089    /**
    090     * <p>
    091     * Converts the specified value to an object of the specified class (if possible). Otherwise, return a String representation of the value.
    092     * </p>
    093     *
    094     * <p>
    095     * For more details see {@code LocaleConvertUtilsBean}
    096     * </p>
    097     *
    098     * @param value The String scalar value to be converted
    099     * @param clazz The Data type to which this value should be converted.
    100     * @return the converted value
    101     * @see LocaleConvertUtilsBean#convert(String, Class)
    102     */
    103    public static Object convert(final String value, final Class<?> clazz) {
    104        return LocaleConvertUtilsBean.getInstance().convert(value, clazz);
    105    }
    106
    107    /**
    108     * <p>
    109     * Converts the specified value to an object of the specified class (if possible) using the conversion pattern. Otherwise, return a String representation of
    110     * the value.
    111     * </p>
    112     *
    113     * <p>
    114     * For more details see {@code LocaleConvertUtilsBean}
    115     * </p>
    116     *
    117     * @param value   The String scalar value to be converted
    118     * @param clazz   The Data type to which this value should be converted.
    119     * @param locale  The locale
    120     * @param pattern The conversion pattern
    121     * @return the converted value
    122     * @see LocaleConvertUtilsBean#convert(String, Class, Locale, String)
    123     */
    124    public static Object convert(final String value, final Class<?> clazz, final Locale locale, final String pattern) {
    125        return LocaleConvertUtilsBean.getInstance().convert(value, clazz, locale, pattern);
    126    }
    127
    128    /**
    129     * <p>
    130     * Converts the specified value to an object of the specified class (if possible) using the conversion pattern. Otherwise, return a String representation of
    131     * the value.
    132     * </p>
    133     *
    134     * <p>
    135     * For more details see {@code LocaleConvertUtilsBean}
    136     * </p>
    137     *
    138     * @param value   The String scalar value to be converted
    139     * @param clazz   The Data type to which this value should be converted.
    140     * @param pattern The conversion pattern
    141     * @return the converted value
    142     * @see LocaleConvertUtilsBean#convert(String, Class, String)
    143     */
    144    public static Object convert(final String value, final Class<?> clazz, final String pattern) {
    145        return LocaleConvertUtilsBean.getInstance().convert(value, clazz, pattern);
    146    }
    147
    148    /**
    149     * <p>
    150     * Convert an array of specified values to an array of objects of the specified class (if possible).
    151     * </p>
    152     *
    153     * <p>
    154     * For more details see {@code LocaleConvertUtilsBean}
    155     * </p>
    156     *
    157     * @param values Value to be converted (may be null)
    158     * @param clazz  Java array or element class to be converted to
    159     * @return the converted value
    160     * @see LocaleConvertUtilsBean#convert(String[], Class)
    161     */
    162    public static Object convert(final String[] values, final Class<?> clazz) {
    163        return LocaleConvertUtilsBean.getInstance().convert(values, clazz);
    164    }
    165
    166    /**
    167     * <p>
    168     * Convert an array of specified values to an array of objects of the specified class (if possible) using the conversion pattern.
    169     * </p>
    170     *
    171     * <p>
    172     * For more details see {@code LocaleConvertUtilsBean}
    173     * </p>
    174     *
    175     * @param values  Value to be converted (may be null)
    176     * @param clazz   Java array or element class to be converted to
    177     * @param locale  The locale
    178     * @param pattern The conversion pattern
    179     * @return the converted value
    180     * @see LocaleConvertUtilsBean#convert(String[], Class, Locale, String)
    181     */
    182    public static Object convert(final String[] values, final Class<?> clazz, final Locale locale, final String pattern) {
    183        return LocaleConvertUtilsBean.getInstance().convert(values, clazz, locale, pattern);
    184    }
    185
    186    /**
    187     * <p>
    188     * Convert an array of specified values to an array of objects of the specified class (if possible) using the conversion pattern.
    189     * </p>
    190     *
    191     * <p>
    192     * For more details see {@code LocaleConvertUtilsBean}
    193     * </p>
    194     *
    195     * @param values  Value to be converted (may be null)
    196     * @param clazz   Java array or element class to be converted to
    197     * @param pattern The conversion pattern
    198     * @return the converted value
    199     * @see LocaleConvertUtilsBean#convert(String[], Class, String)
    200     */
    201    public static Object convert(final String[] values, final Class<?> clazz, final String pattern) {
    202        return LocaleConvertUtilsBean.getInstance().convert(values, clazz, pattern);
    203    }
    204
    205    /**
    206     * <p>
    207     * Remove any registered {@link LocaleConverter}.
    208     * </p>
    209     *
    210     * <p>
    211     * For more details see {@code LocaleConvertUtilsBean}
    212     * </p>
    213     *
    214     * @see LocaleConvertUtilsBean#deregister()
    215     */
    216    public static void deregister() {
    217        LocaleConvertUtilsBean.getInstance().deregister();
    218    }
    219
    220    /**
    221     * <p>
    222     * Remove any registered {@link LocaleConverter} for the specified locale and Class.
    223     * </p>
    224     *
    225     * <p>
    226     * For more details see {@code LocaleConvertUtilsBean}
    227     * </p>
    228     *
    229     * @param clazz  Class for which to remove a registered Converter
    230     * @param locale The locale
    231     * @see LocaleConvertUtilsBean#deregister(Class, Locale)
    232     */
    233    public static void deregister(final Class<?> clazz, final Locale locale) {
    234        LocaleConvertUtilsBean.getInstance().deregister(clazz, locale);
    235    }
    236
    237    /**
    238     * <p>
    239     * Remove any registered {@link LocaleConverter} for the specified locale.
    240     * </p>
    241     *
    242     * <p>
    243     * For more details see {@code LocaleConvertUtilsBean}
    244     * </p>
    245     *
    246     * @param locale The locale
    247     * @see LocaleConvertUtilsBean#deregister(Locale)
    248     */
    249    public static void deregister(final Locale locale) {
    250        LocaleConvertUtilsBean.getInstance().deregister(locale);
    251    }
    252
    253    /**
    254     * <p>
    255     * Gets applyLocalized.
    256     * </p>
    257     *
    258     * <p>
    259     * For more details see {@code LocaleConvertUtilsBean}
    260     * </p>
    261     *
    262     * @return {@code true} if pattern is localized, otherwise {@code false}
    263     * @see LocaleConvertUtilsBean#getApplyLocalized()
    264     */
    265    public static boolean getApplyLocalized() {
    266        return LocaleConvertUtilsBean.getInstance().getApplyLocalized();
    267    }
    268
    269    /**
    270     * <p>
    271     * Gets the {@link Locale} which will be used when no {@link Locale} is passed to a method.
    272     * </p>
    273     *
    274     * <p>
    275     * For more details see {@code LocaleConvertUtilsBean}
    276     * </p>
    277     *
    278     * @return the default locale
    279     * @see LocaleConvertUtilsBean#getDefaultLocale()
    280     */
    281    public static Locale getDefaultLocale() {
    282        return LocaleConvertUtilsBean.getInstance().getDefaultLocale();
    283    }
    284
    285    /**
    286     * <p>
    287     * Look up and return any registered {@link LocaleConverter} for the specified destination class and locale; if there is no registered Converter, return
    288     * {@code null}.
    289     * </p>
    290     *
    291     * <p>
    292     * For more details see {@code LocaleConvertUtilsBean}
    293     * </p>
    294     *
    295     * @param <T>    The converter type.
    296     * @param clazz  Class for which to return a registered Converter
    297     * @param locale The Locale
    298     * @return The registered locale Converter, if any
    299     * @see LocaleConvertUtilsBean#lookup(Class, Locale)
    300     */
    301    public static <T> LocaleConverter<T> lookup(final Class<T> clazz, final Locale locale) {
    302        return LocaleConvertUtilsBean.getInstance().lookup(clazz, locale);
    303    }
    304
    305    /**
    306     * <p>
    307     * Register a custom {@link LocaleConverter} for the specified destination {@code Class}, replacing any previously registered converter.
    308     * </p>
    309     *
    310     * <p>
    311     * For more details see {@code LocaleConvertUtilsBean}
    312     * </p>
    313     *
    314     * @param <T>       The converter type.
    315     * @param converter The LocaleConverter to be registered
    316     * @param clazz     The Destination class for conversions performed by this Converter
    317     * @param locale    The locale
    318     * @see LocaleConvertUtilsBean#register(LocaleConverter, Class, Locale)
    319     */
    320    public static <T> void register(final LocaleConverter<T> converter, final Class<T> clazz, final Locale locale) {
    321        LocaleConvertUtilsBean.getInstance().register(converter, clazz, locale);
    322    }
    323
    324    /**
    325     * <p>
    326     * Sets applyLocalized.
    327     * </p>
    328     *
    329     * <p>
    330     * For more details see {@code LocaleConvertUtilsBean}
    331     * </p>
    332     *
    333     * @param newApplyLocalized {@code true} if pattern is localized, otherwise {@code false}
    334     * @see LocaleConvertUtilsBean#setApplyLocalized(boolean)
    335     */
    336    public static void setApplyLocalized(final boolean newApplyLocalized) {
    337        LocaleConvertUtilsBean.getInstance().setApplyLocalized(newApplyLocalized);
    338    }
    339
    340    /**
    341     * <p>
    342     * Sets the {@link Locale} which will be used when no {@link Locale} is passed to a method.
    343     * </p>
    344     *
    345     * <p>
    346     * For more details see {@code LocaleConvertUtilsBean}
    347     * </p>
    348     *
    349     * @param locale the default locale
    350     * @see LocaleConvertUtilsBean#setDefaultLocale(Locale)
    351     */
    352    public static void setDefaultLocale(final Locale locale) {
    353        LocaleConvertUtilsBean.getInstance().setDefaultLocale(locale);
    354    }
    355}