    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.beanutils2;
    019
    020/**
    021 * <p>
    022 * Utility methods for converting String scalar values to objects of the specified Class, String arrays to arrays of the specified Class.
    023 * </p>
    024 *
    025 * <p>
    026 * For more details, see {@code ConvertUtilsBean} which provides the implementations for these methods.
    027 * </p>
    028 *
    029 * @see ConvertUtilsBean
    030 */
    031public class ConvertUtils {
    032
    033    /**
    034     * <p>
    035     * Converts the specified value into a String.
    036     * </p>
    037     *
    038     * <p>
    039     * For more details see {@code ConvertUtilsBean}.
    040     * </p>
    041     *
    042     * @param value Value to be converted (may be null)
    043     * @return The converted String value or null if value is null
    044     * @see ConvertUtilsBean#convert(Object)
    045     */
    046    public static String convert(final Object value) {
    047        return ConvertUtilsBean.getInstance().convert(value);
    048    }
    049
    050    /**
    051     * <p>
    052     * Converts the value to an object of the specified class (if possible).
    053     * </p>
    054     *
    055     * @param value      Value to be converted (may be null)
    056     * @param targetType Class of the value to be converted to (must not be null)
    057     * @return The converted value
    058     * @throws ConversionException if thrown by an underlying Converter
    059     */
    060    public static Object convert(final Object value, final Class<?> targetType) {
    061        return ConvertUtilsBean.getInstance().convert(value, targetType);
    062    }
    063
    064    /**
    065     * <p>
    066     * Converts the specified value to an object of the specified class (if possible). Otherwise, return a String representation of the value.
    067     * </p>
    068     *
    069     * <p>
    070     * For more details see {@code ConvertUtilsBean}.
    071     * </p>
    072     *
    073     * @param value Value to be converted (may be null)
    074     * @param clazz Java class to be converted to (must not be null)
    075     * @return The converted value
    076     * @see ConvertUtilsBean#convert(String, Class)
    077     */
    078    public static Object convert(final String value, final Class<?> clazz) {
    079        return ConvertUtilsBean.getInstance().convert(value, clazz);
    080    }
    081
    082    /**
    083     * <p>
    084     * Convert an array of specified values to an array of objects of the specified class (if possible).
    085     * </p>
    086     *
    087     * <p>
    088     * For more details see {@code ConvertUtilsBean}.
    089     * </p>
    090     *
    091     * @param values Array of values to be converted
    092     * @param clazz  Java array or element class to be converted to (must not be null)
    093     * @return The converted value
    094     * @see ConvertUtilsBean#convert(String[], Class)
    095     */
    096    public static Object convert(final String[] values, final Class<?> clazz) {
    097        return ConvertUtilsBean.getInstance().convert(values, clazz);
    098    }
    099
    100    /**
    101     * <p>
    102     * Remove all registered {@link Converter}s, and re-establish the standard Converters.
    103     * </p>
    104     *
    105     * <p>
    106     * For more details see {@code ConvertUtilsBean}.
    107     * </p>
    108     *
    109     * @see ConvertUtilsBean#deregister()
    110     */
    111    public static void deregister() {
    112        ConvertUtilsBean.getInstance().deregister();
    113    }
    114
    115    /**
    116     * <p>
    117     * Remove any registered {@link Converter} for the specified destination {@code Class}.
    118     * </p>
    119     *
    120     * <p>
    121     * For more details see {@code ConvertUtilsBean}.
    122     * </p>
    123     *
    124     * @param clazz Class for which to remove a registered Converter
    125     * @see ConvertUtilsBean#deregister(Class)
    126     */
    127    public static void deregister(final Class<?> clazz) {
    128        ConvertUtilsBean.getInstance().deregister(clazz);
    129    }
    130
    131    /**
    132     * Look up and return any registered {@link Converter} for the specified source and destination class; if there is no registered Converter, return
    133     * {@code null}.
    134     *
    135     * @param <T>        The converter type.
    136     * @param sourceType Class of the value being converted
    137     * @param targetType Class of the value to be converted to
    138     * @return The registered {@link Converter} or {@code null} if not found
    139     */
    140    public static <T> Converter<T> lookup(final Class<?> sourceType, final Class<T> targetType) {
    141        return ConvertUtilsBean.getInstance().lookup(sourceType, targetType);
    142    }
    143
    144    /**
    145     * <p>
    146     * Look up and return any registered {@link Converter} for the specified destination class; if there is no registered Converter, return {@code null}.
    147     * </p>
    148     *
    149     * <p>
    150     * For more details see {@code ConvertUtilsBean}.
    151     * </p>
    152     *
    153     * @param <T>   The converter type.
    154     * @param clazz Class for which to return a registered Converter
    155     * @return The registered {@link Converter} or {@code null} if not found
    156     * @see ConvertUtilsBean#lookup(Class)
    157     */
    158    public static <T> Converter<T> lookup(final Class<T> clazz) {
    159        return ConvertUtilsBean.getInstance().lookup(clazz);
    160    }
    161
    162    /**
    163     * Change primitive Class types to the associated wrapper class. This is useful for concrete converter implementations which typically treat primitive types
    164     * like their corresponding wrapper types.
    165     *
    166     * @param <T>  The type to be checked.
    167     * @param type The class type to check.
    168     * @return The converted type.
    169     * @since 1.9
    170     */
    171    // All type casts are safe because the TYPE members of the wrapper types
    172    // return their own class.
    173    @SuppressWarnings("unchecked")
    174    public static <T> Class<T> primitiveToWrapper(final Class<T> type) {
    175        if (type == null || !type.isPrimitive()) {
    176            return type;
    177        }
    178
    179        if (type == Integer.TYPE) {
    180            return (Class<T>) Integer.class;
    181        }
    182        if (type == Double.TYPE) {
    183            return (Class<T>) Double.class;
    184        }
    185        if (type == Long.TYPE) {
    186            return (Class<T>) Long.class;
    187        }
    188        if (type == Boolean.TYPE) {
    189            return (Class<T>) Boolean.class;
    190        }
    191        if (type == Float.TYPE) {
    192            return (Class<T>) Float.class;
    193        }
    194        if (type == Short.TYPE) {
    195            return (Class<T>) Short.class;
    196        }
    197        if (type == Byte.TYPE) {
    198            return (Class<T>) Byte.class;
    199        }
    200        if (type == Character.TYPE) {
    201            return (Class<T>) Character.class;
    202        }
    203        return type;
    204    }
    205
    206    /**
    207     * <p>
    208     * Register a custom {@link Converter} for the specified destination {@code Class}, replacing any previously registered Converter.
    209     * </p>
    210     *
    211     * <p>
    212     * For more details see {@code ConvertUtilsBean}.
    213     * </p>
    214     *
    215     * @param <T>       The converter type.
    216     * @param converter Converter to be registered
    217     * @param clazz     Destination class for conversions performed by this Converter
    218     * @see ConvertUtilsBean#register(Converter, Class)
    219     */
    220    public static <T> void register(final Converter<T> converter, final Class<T> clazz) {
    221        ConvertUtilsBean.getInstance().register(converter, clazz);
    222    }
    223}