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