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