    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 */
    017package org.apache.commons.configuration2.convert;
    018
    019import java.util.Collection;
    020
    021import org.apache.commons.configuration2.ex.ConversionException;
    022import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;
    023
    024/**
    025 * <p>
    026 * An interface defining the possible data type conversions supported by the
    027 * configuration framework.
    028 * </p>
    029 * <p>
    030 * This interface defines a couple of methods related to different kinds of data
    031 * type conversion:
    032 * </p>
    033 * <ul>
    034 * <li>Conversion to an object of a specific type</li>
    035 * <li>Conversion to an array of a specific type</li>
    036 * <li>Conversion to a collection of a specific type</li>
    037 * </ul>
    038 * <p>
    039 * Data type conversion is related to variable substitution (aka interpolation).
    040 * Before a value can be converted to a target type substitution has to be
    041 * performed first, and the conversion is done on the resulting value. In order
    042 * to support this, the conversion methods expect a
    043 * {@link ConfigurationInterpolator} object; {@code Configuration}
    044 * implementations here pass in their associated instance.
    045 * </p>
    046 * <p>
    047 * A {@code Configuration} object is associated with a concrete
    048 * {@code ConversionHandler} implementation. Whenever a data type conversion is
    049 * required it delegates to this handler. By providing a custom
    050 * {@code ConversionHandler} object, the type conversion performed by the
    051 * configuration object can be adapted.
    052 * </p>
    053 *
    054 * @version $Id: ConversionHandler.java 1679781 2015-05-16 17:45:10Z oheger $
    055 * @since 2.0
    056 */
    057public interface ConversionHandler
    058{
    059    /**
    060     * Converts a single object to the specified target type. A concrete
    061     * implementation has to attempt a conversion. If this is not possible, a
    062     * {@link ConversionException} is thrown. It is up to a concrete
    063     * implementation how <b>null</b> values are handled; a default strategy
    064     * would be to return <b>null</b> if the source object is <b>null</b>.
    065     *
    066     * @param <T> the type of the desired result
    067     * @param src the object to be converted
    068     * @param targetCls the target class of the conversion
    069     * @param ci an object for performing variable substitution
    070     * @return the converted object
    071     * @throws ConversionException if the requested conversion is not possible
    072     */
    073    <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci);
    074
    075    /**
    076     * Converts the given object to an array of the specified element type. The
    077     * object can be a single value (e.g. a String, a primitive, etc.) or a
    078     * complex object containing multiple values (like a collection or another
    079     * array). In the latter case all elements contained in the complex object
    080     * are converted to the target type. If the value(s) cannot be converted to
    081     * the desired target class, a {@link ConversionException} is thrown. Note
    082     * that the result type of this method is {@code Object}; because this
    083     * method can also produce arrays of a primitive type the return type
    084     * {@code Object[]} cannot be used.
    085     *
    086     * @param src the object to be converted
    087     * @param elemClass the element class of the resulting array
    088     * @param ci an object for performing variable substitution
    089     * @return the array with the converted values
    090     * @throws ConversionException if the conversion of an element is not
    091     *         possible
    092     */
    093    Object toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci);
    094
    095    /**
    096     * Converts the given object to a collection of the specified type. The
    097     * target collection must be provided (here callers have the option to
    098     * specify different types of collections like lists or sets). All values
    099     * contained in the specified source object (or the source object itself if
    100     * it is a single value) are converted to the desired target class and added
    101     * to the destination collection. If the conversion of an element is not
    102     * possible, a {@link ConversionException} is thrown.
    103     *
    104     * @param <T> the type of the elements of the destination collection
    105     * @param src the object to be converted
    106     * @param elemClass the element class of the destination collection
    107     * @param ci an object for performing variable substitution
    108     * @param dest the destination collection
    109     */
    110    <T> void toCollection(Object src, Class<T> elemClass,
    111            ConfigurationInterpolator ci, Collection<T> dest);
    112}