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