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.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}