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}