Source code

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
018
019package org.apache.commons.beanutils;
020
021/**
022 * <p>Utility methods for converting String scalar values to objects of the
023 * specified Class, String arrays to arrays of the specified Class.</p>
024 *
025 * <p>For more details, see <code>ConvertUtilsBean</code> which provides the
026 * implementations for these methods.</p>
027 *
028 * @version $Id$
029 * @see ConvertUtilsBean
030 */
031
032public class ConvertUtils {
033
034
035    // ------------------------------------------------------ Static Properties
036
037    /**
038     * Gets the default value for Boolean conversions.
039     * @return The default Boolean value
040     * @deprecated Register replacement converters for Boolean.TYPE and
041     *  Boolean.class instead
042     */
043    @Deprecated
044    public static boolean getDefaultBoolean() {
045        return (ConvertUtilsBean.getInstance().getDefaultBoolean());
046    }
047
048    /**
049     * Sets the default value for Boolean conversions.
050     * @param newDefaultBoolean The default Boolean value
051     * @deprecated Register replacement converters for Boolean.TYPE and
052     *  Boolean.class instead
053     */
054    @Deprecated
055    public static void setDefaultBoolean(final boolean newDefaultBoolean) {
056        ConvertUtilsBean.getInstance().setDefaultBoolean(newDefaultBoolean);
057    }
058
059
060    /**
061     * Gets the default value for Byte conversions.
062     * @return The default Byte value
063     * @deprecated Register replacement converters for Byte.TYPE and
064     *  Byte.class instead
065     */
066    @Deprecated
067    public static byte getDefaultByte() {
068        return ConvertUtilsBean.getInstance().getDefaultByte();
069    }
070
071    /**
072     * Sets the default value for Byte conversions.
073     * @param newDefaultByte The default Byte value
074     * @deprecated Register replacement converters for Byte.TYPE and
075     *  Byte.class instead
076     */
077    @Deprecated
078    public static void setDefaultByte(final byte newDefaultByte) {
079        ConvertUtilsBean.getInstance().setDefaultByte(newDefaultByte);
080    }
081
082
083    /**
084     * Gets the default value for Character conversions.
085     * @return The default Character value
086     * @deprecated Register replacement converters for Character.TYPE and
087     *  Character.class instead
088     */
089    @Deprecated
090    public static char getDefaultCharacter() {
091        return ConvertUtilsBean.getInstance().getDefaultCharacter();
092    }
093
094    /**
095     * Sets the default value for Character conversions.
096     * @param newDefaultCharacter The default Character value
097     * @deprecated Register replacement converters for Character.TYPE and
098     *  Character.class instead
099     */
100    @Deprecated
101    public static void setDefaultCharacter(final char newDefaultCharacter) {
102        ConvertUtilsBean.getInstance().setDefaultCharacter(newDefaultCharacter);
103    }
104
105
106    /**
107     * Gets the default value for Double conversions.
108     * @return The default Double value
109     * @deprecated Register replacement converters for Double.TYPE and
110     *  Double.class instead
111     */
112    @Deprecated
113    public static double getDefaultDouble() {
114        return ConvertUtilsBean.getInstance().getDefaultDouble();
115    }
116
117    /**
118     * Sets the default value for Double conversions.
119     * @param newDefaultDouble The default Double value
120     * @deprecated Register replacement converters for Double.TYPE and
121     *  Double.class instead
122     */
123    @Deprecated
124    public static void setDefaultDouble(final double newDefaultDouble) {
125        ConvertUtilsBean.getInstance().setDefaultDouble(newDefaultDouble);
126    }
127
128
129    /**
130     * Get the default value for Float conversions.
131     * @return The default Float value
132     * @deprecated Register replacement converters for Float.TYPE and
133     *  Float.class instead
134     */
135    @Deprecated
136    public static float getDefaultFloat() {
137        return ConvertUtilsBean.getInstance().getDefaultFloat();
138    }
139
140    /**
141     * Sets the default value for Float conversions.
142     * @param newDefaultFloat The default Float value
143     * @deprecated Register replacement converters for Float.TYPE and
144     *  Float.class instead
145     */
146    @Deprecated
147    public static void setDefaultFloat(final float newDefaultFloat) {
148        ConvertUtilsBean.getInstance().setDefaultFloat(newDefaultFloat);
149    }
150
151
152    /**
153     * Gets the default value for Integer conversions.
154     * @return The default Integer value
155     * @deprecated Register replacement converters for Integer.TYPE and
156     *  Integer.class instead
157     */
158    @Deprecated
159    public static int getDefaultInteger() {
160        return ConvertUtilsBean.getInstance().getDefaultInteger();
161    }
162
163    /**
164     * Sets the default value for Integer conversions.
165     * @param newDefaultInteger The default Integer value
166     * @deprecated Register replacement converters for Integer.TYPE and
167     *  Integer.class instead
168     */
169    @Deprecated
170    public static void setDefaultInteger(final int newDefaultInteger) {
171        ConvertUtilsBean.getInstance().setDefaultInteger(newDefaultInteger);
172    }
173
174
175    /**
176     * Gets the default value for Long conversions.
177     * @return The default Long value
178     * @deprecated Register replacement converters for Long.TYPE and
179     *  Long.class instead
180     */
181    @Deprecated
182    public static long getDefaultLong() {
183        return (ConvertUtilsBean.getInstance().getDefaultLong());
184    }
185
186    /**
187     * Sets the default value for Long conversions.
188     * @param newDefaultLong The default Long value
189     * @deprecated Register replacement converters for Long.TYPE and
190     *  Long.class instead
191     */
192    @Deprecated
193    public static void setDefaultLong(final long newDefaultLong) {
194        ConvertUtilsBean.getInstance().setDefaultLong(newDefaultLong);
195    }
196
197
198    /**
199     * Gets the default value for Short conversions.
200     * @return The default Short value
201     * @deprecated Register replacement converters for Short.TYPE and
202     *  Short.class instead
203     */
204    @Deprecated
205    public static short getDefaultShort() {
206        return ConvertUtilsBean.getInstance().getDefaultShort();
207    }
208
209    /**
210     * Sets the default value for Short conversions.
211     * @param newDefaultShort The default Short value
212     * @deprecated Register replacement converters for Short.TYPE and
213     *  Short.class instead
214     */
215    @Deprecated
216    public static void setDefaultShort(final short newDefaultShort) {
217        ConvertUtilsBean.getInstance().setDefaultShort(newDefaultShort);
218    }
219
220    // --------------------------------------------------------- Public Classes
221
222
223    /**
224     * <p>Convert the specified value into a String.</p>
225     *
226     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
227     *
228     * @param value Value to be converted (may be null)
229     * @return The converted String value or null if value is null
230     *
231     * @see ConvertUtilsBean#convert(Object)
232     */
233    public static String convert(final Object value) {
234        return ConvertUtilsBean.getInstance().convert(value);
235    }
236
237
238    /**
239     * <p>Convert the specified value to an object of the specified class (if
240     * possible).  Otherwise, return a String representation of the value.</p>
241     *
242     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
243     *
244     * @param value Value to be converted (may be null)
245     * @param clazz Java class to be converted to (must not be null)
246     * @return The converted value
247     *
248     * @see ConvertUtilsBean#convert(String, Class)
249     */
250    public static Object convert(final String value, final Class<?> clazz) {
251        return ConvertUtilsBean.getInstance().convert(value, clazz);
252    }
253
254
255    /**
256     * <p>Convert an array of specified values to an array of objects of the
257     * specified class (if possible).</p>
258     *
259     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
260     *
261     * @param values Array of values to be converted
262     * @param clazz Java array or element class to be converted to (must not be null)
263     * @return The converted value
264     *
265     * @see ConvertUtilsBean#convert(String[], Class)
266     */
267    public static Object convert(final String[] values, final Class<?> clazz) {
268        return ConvertUtilsBean.getInstance().convert(values, clazz);
269    }
270
271    /**
272     * <p>Convert the value to an object of the specified class (if
273     * possible).</p>
274     *
275     * @param value Value to be converted (may be null)
276     * @param targetType Class of the value to be converted to (must not be null)
277     * @return The converted value
278     *
279     * @throws ConversionException if thrown by an underlying Converter
280     */
281    public static Object convert(final Object value, final Class<?> targetType) {
282        return ConvertUtilsBean.getInstance().convert(value, targetType);
283    }
284
285    /**
286     * <p>Remove all registered {@link Converter}s, and re-establish the
287     * standard Converters.</p>
288     *
289     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
290     *
291     * @see ConvertUtilsBean#deregister()
292     */
293    public static void deregister() {
294        ConvertUtilsBean.getInstance().deregister();
295    }
296
297
298    /**
299     * <p>Remove any registered {@link Converter} for the specified destination
300     * <code>Class</code>.</p>
301     *
302     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
303     *
304     * @param clazz Class for which to remove a registered Converter
305     * @see ConvertUtilsBean#deregister(Class)
306     */
307    public static void deregister(final Class<?> clazz) {
308        ConvertUtilsBean.getInstance().deregister(clazz);
309    }
310
311
312    /**
313     * <p>Look up and return any registered {@link Converter} for the specified
314     * destination class; if there is no registered Converter, return
315     * <code>null</code>.</p>
316     *
317     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
318     *
319     * @param clazz Class for which to return a registered Converter
320     * @return The registered {@link Converter} or <code>null</code> if not found
321     * @see ConvertUtilsBean#lookup(Class)
322     */
323    public static Converter lookup(final Class<?> clazz) {
324        return ConvertUtilsBean.getInstance().lookup(clazz);
325    }
326
327    /**
328     * Look up and return any registered {@link Converter} for the specified
329     * source and destination class; if there is no registered Converter,
330     * return <code>null</code>.
331     *
332     * @param sourceType Class of the value being converted
333     * @param targetType Class of the value to be converted to
334     * @return The registered {@link Converter} or <code>null</code> if not found
335     */
336    public static Converter lookup(final Class<?> sourceType, final Class<?> targetType) {
337        return ConvertUtilsBean.getInstance().lookup(sourceType, targetType);
338    }
339
340    /**
341     * <p>Register a custom {@link Converter} for the specified destination
342     * <code>Class</code>, replacing any previously registered Converter.</p>
343     *
344     * <p>For more details see <code>ConvertUtilsBean</code>.</p>
345     *
346     * @param converter Converter to be registered
347     * @param clazz Destination class for conversions performed by this
348     *  Converter
349     * @see ConvertUtilsBean#register(Converter, Class)
350     */
351    public static void register(final Converter converter, final Class<?> clazz) {
352        ConvertUtilsBean.getInstance().register(converter, clazz);
353    }
354
355
356    /**
357     * Change primitive Class types to the associated wrapper class. This is
358     * useful for concrete converter implementations which typically treat
359     * primitive types like their corresponding wrapper types.
360     *
361     * @param <T> The type to be checked.
362     * @param type The class type to check.
363     * @return The converted type.
364     * @since 1.9
365     */
366    // All type casts are safe because the TYPE members of the wrapper types
367    // return their own class.
368    @SuppressWarnings("unchecked")
369    public static <T> Class<T> primitiveToWrapper(final Class<T> type) {
370        if (type == null || !type.isPrimitive()) {
371            return type;
372        }
373
374        if (type == Integer.TYPE) {
375            return (Class<T>) Integer.class;
376        } else if (type == Double.TYPE) {
377            return (Class<T>) Double.class;
378        } else if (type == Long.TYPE) {
379            return (Class<T>) Long.class;
380        } else if (type == Boolean.TYPE) {
381            return (Class<T>) Boolean.class;
382        } else if (type == Float.TYPE) {
383            return (Class<T>) Float.class;
384        } else if (type == Short.TYPE) {
385            return (Class<T>) Short.class;
386        } else if (type == Byte.TYPE) {
387            return (Class<T>) Byte.class;
388        } else if (type == Character.TYPE) {
389            return (Class<T>) Character.class;
390        } else {
391            return type;
392        }
393    }
394}