View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.beanutils.locale;
19  
20  import java.util.Locale;
21  
22  import org.apache.commons.collections.FastHashMap;
23  
24  /**
25   * <p>Utility methods for converting locale-sensitive String scalar values to objects of the
26   * specified Class, String arrays to arrays of the specified Class and
27   * object to locale-sensitive String scalar value.</p>
28   *
29   * <p>The implementations for these method are provided by {@link LocaleConvertUtilsBean}.
30   * These static utility method use the default instance. More sophisticated can be provided
31   * by using a <code>LocaleConvertUtilsBean</code> instance.</p>
32   *
33   * @version $Id$
34   */
35  public class LocaleConvertUtils {
36  
37      // ----------------------------------------------------- Instance Variables
38  
39      /**
40       * <p>Gets the <code>Locale</code> which will be used when
41       * no <code>Locale</code> is passed to a method.</p>
42       *
43       * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
44       * @return the default locale
45       * @see LocaleConvertUtilsBean#getDefaultLocale()
46       */
47      public static Locale getDefaultLocale() {
48  
49          return LocaleConvertUtilsBean.getInstance().getDefaultLocale();
50      }
51  
52      /**
53       * <p>Sets the <code>Locale</code> which will be used when
54       * no <code>Locale</code> is passed to a method.</p>
55       *
56       * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
57       *
58       * @param locale the default locale
59       * @see LocaleConvertUtilsBean#setDefaultLocale(Locale)
60       */
61      public static void setDefaultLocale(final Locale locale) {
62  
63          LocaleConvertUtilsBean.getInstance().setDefaultLocale(locale);
64      }
65  
66      /**
67       * <p>Gets applyLocalized.</p>
68       *
69       * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
70       *
71       * @return <code>true</code> if pattern is localized,
72       * otherwise <code>false</code>
73       * @see LocaleConvertUtilsBean#getApplyLocalized()
74       */
75      public static boolean getApplyLocalized() {
76          return LocaleConvertUtilsBean.getInstance().getApplyLocalized();
77      }
78  
79      /**
80       * <p>Sets applyLocalized.</p>
81       *
82       * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
83       *
84       * @param newApplyLocalized <code>true</code> if pattern is localized,
85       * otherwise <code>false</code>
86       * @see LocaleConvertUtilsBean#setApplyLocalized(boolean)
87       */
88      public static void setApplyLocalized(final boolean newApplyLocalized) {
89          LocaleConvertUtilsBean.getInstance().setApplyLocalized(newApplyLocalized);
90      }
91  
92      // --------------------------------------------------------- Methods
93  
94      /**
95       * <p>Convert the specified locale-sensitive value into a String.</p>
96       *
97       * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
98       *
99       * @param value The Value to be converted
100      * @return the converted value
101      * @see LocaleConvertUtilsBean#convert(Object)
102      */
103     public static String convert(final Object value) {
104         return LocaleConvertUtilsBean.getInstance().convert(value);
105     }
106 
107     /**
108      * <p>Convert the specified locale-sensitive value into a String
109      * using the conversion pattern.</p>
110      *
111      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
112      *
113      * @param value The Value to be converted
114      * @param pattern       The convertion pattern
115      * @return the converted value
116      * @see LocaleConvertUtilsBean#convert(Object, String)
117      */
118     public static String convert(final Object value, final String pattern) {
119         return LocaleConvertUtilsBean.getInstance().convert(value, pattern);
120     }
121 
122     /**
123      * <p>Convert the specified locale-sensitive value into a String
124      * using the paticular convertion pattern.</p>
125      *
126      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
127      *
128      * @param value The Value to be converted
129      * @param locale The locale
130      * @param pattern The convertion pattern
131      * @return the converted value
132      * @see LocaleConvertUtilsBean#convert(Object, Locale, String)
133      */
134     public static String convert(final Object value, final Locale locale, final String pattern) {
135 
136         return LocaleConvertUtilsBean.getInstance().convert(value, locale, pattern);
137     }
138 
139     /**
140      * <p>Convert the specified value to an object of the specified class (if
141      * possible).  Otherwise, return a String representation of the value.</p>
142      *
143      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
144      *
145      * @param value The String scalar value to be converted
146      * @param clazz The Data type to which this value should be converted.
147      * @return the converted value
148      * @see LocaleConvertUtilsBean#convert(String, Class)
149      */
150     public static Object convert(final String value, final Class<?> clazz) {
151 
152         return LocaleConvertUtilsBean.getInstance().convert(value, clazz);
153     }
154 
155     /**
156      * <p>Convert the specified value to an object of the specified class (if
157      * possible) using the convertion pattern. Otherwise, return a String
158      * representation of the value.</p>
159      *
160      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
161      *
162      * @param value The String scalar value to be converted
163      * @param clazz The Data type to which this value should be converted.
164      * @param pattern The convertion pattern
165      * @return the converted value
166      * @see LocaleConvertUtilsBean#convert(String, Class, String)
167      */
168     public static Object convert(final String value, final Class<?> clazz, final String pattern) {
169 
170         return LocaleConvertUtilsBean.getInstance().convert(value, clazz, pattern);
171     }
172 
173     /**
174      * <p>Convert the specified value to an object of the specified class (if
175      * possible) using the convertion pattern. Otherwise, return a String
176      * representation of the value.</p>
177      *
178      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
179      *
180      * @param value The String scalar value to be converted
181      * @param clazz The Data type to which this value should be converted.
182      * @param locale The locale
183      * @param pattern The convertion pattern
184      * @return the converted value
185      * @see LocaleConvertUtilsBean#convert(String, Class, Locale, String)
186      */
187     public static Object convert(final String value, final Class<?> clazz, final Locale locale, final String pattern) {
188 
189         return LocaleConvertUtilsBean.getInstance().convert(value, clazz, locale, pattern);
190     }
191 
192     /**
193      * <p>Convert an array of specified values to an array of objects of the
194      * specified class (if possible) using the convertion pattern.</p>
195      *
196      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
197      *
198      * @param values Value to be converted (may be null)
199      * @param clazz Java array or element class to be converted to
200      * @param pattern The convertion pattern
201      * @return the converted value
202      * @see LocaleConvertUtilsBean#convert(String[], Class, String)
203      */
204     public static Object convert(final String[] values, final Class<?> clazz, final String pattern) {
205 
206         return LocaleConvertUtilsBean.getInstance().convert(values, clazz, pattern);
207     }
208 
209    /**
210     * <p>Convert an array of specified values to an array of objects of the
211     * specified class (if possible).</p>
212     *
213     * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
214     *
215     * @param values Value to be converted (may be null)
216     * @param clazz Java array or element class to be converted to
217     * @return the converted value
218     * @see LocaleConvertUtilsBean#convert(String[], Class)
219     */
220    public static Object convert(final String[] values, final Class<?> clazz) {
221 
222        return LocaleConvertUtilsBean.getInstance().convert(values, clazz);
223    }
224 
225     /**
226      * <p>Convert an array of specified values to an array of objects of the
227      * specified class (if possible) using the convertion pattern.</p>
228      *
229      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
230      *
231      * @param values Value to be converted (may be null)
232      * @param clazz Java array or element class to be converted to
233      * @param locale The locale
234      * @param pattern The convertion pattern
235      * @return the converted value
236      * @see LocaleConvertUtilsBean#convert(String[], Class, Locale, String)
237      */
238     public static Object convert(final String[] values, final Class<?> clazz, final Locale locale, final String pattern) {
239 
240         return LocaleConvertUtilsBean.getInstance().convert(values, clazz, locale, pattern);
241     }
242 
243     /**
244      * <p>Register a custom {@link LocaleConverter} for the specified destination
245      * <code>Class</code>, replacing any previously registered converter.</p>
246      *
247      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
248      *
249      * @param converter The LocaleConverter to be registered
250      * @param clazz The Destination class for conversions performed by this
251      *  Converter
252      * @param locale The locale
253      * @see LocaleConvertUtilsBean#register(LocaleConverter, Class, Locale)
254      */
255     public static void register(final LocaleConverter converter, final Class<?> clazz, final Locale locale) {
256 
257         LocaleConvertUtilsBean.getInstance().register(converter, clazz, locale);
258     }
259 
260     /**
261      * <p>Remove any registered {@link LocaleConverter}.</p>
262      *
263      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
264      *
265      * @see LocaleConvertUtilsBean#deregister()
266      */
267     public static void deregister() {
268 
269        LocaleConvertUtilsBean.getInstance().deregister();
270     }
271 
272 
273     /**
274      * <p>Remove any registered {@link LocaleConverter} for the specified locale.</p>
275      *
276      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
277      *
278      * @param locale The locale
279      * @see LocaleConvertUtilsBean#deregister(Locale)
280      */
281     public static void deregister(final Locale locale) {
282 
283         LocaleConvertUtilsBean.getInstance().deregister(locale);
284     }
285 
286 
287     /**
288      * <p>Remove any registered {@link LocaleConverter} for the specified locale and Class.</p>
289      *
290      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
291      *
292      * @param clazz Class for which to remove a registered Converter
293      * @param locale The locale
294      * @see LocaleConvertUtilsBean#deregister(Class, Locale)
295      */
296     public static void deregister(final Class<?> clazz, final Locale locale) {
297 
298         LocaleConvertUtilsBean.getInstance().deregister(clazz, locale);
299     }
300 
301     /**
302      * <p>Look up and return any registered {@link LocaleConverter} for the specified
303      * destination class and locale; if there is no registered Converter, return
304      * <code>null</code>.</p>
305      *
306      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
307      *
308      * @param clazz Class for which to return a registered Converter
309      * @param locale The Locale
310      * @return The registered locale Converter, if any
311      * @see LocaleConvertUtilsBean#lookup(Class, Locale)
312      */
313     public static LocaleConverter lookup(final Class<?> clazz, final Locale locale) {
314 
315         return LocaleConvertUtilsBean.getInstance().lookup(clazz, locale);
316     }
317 
318     /**
319      * <p>Look up and return any registered FastHashMap instance for the specified locale.</p>
320      *
321      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
322      *
323      * @param locale The Locale
324      * @return The FastHashMap instance contains the all {@link LocaleConverter} types for
325      *  the specified locale.
326      * @see LocaleConvertUtilsBean#lookup(Locale)
327      * @deprecated This method will be modified to return a Map in the next release.
328      */
329     @Deprecated
330     protected static FastHashMap lookup(final Locale locale) {
331         return LocaleConvertUtilsBean.getInstance().lookup(locale);
332     }
333 
334     /**
335      * <p>Create all {@link LocaleConverter} types for specified locale.</p>
336      *
337      * <p>For more details see <code>LocaleConvertUtilsBean</code></p>
338      *
339      * @param locale The Locale
340      * @return The FastHashMap instance contains the all {@link LocaleConverter} types
341      *  for the specified locale.
342      * @see LocaleConvertUtilsBean#create(Locale)
343      * @deprecated This method will be modified to return a Map in the next release.
344      */
345     @Deprecated
346     protected static FastHashMap create(final Locale locale) {
347 
348         return LocaleConvertUtilsBean.getInstance().create(locale);
349     }
350 }