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 * @since 2.0
055 */
056public interface ConversionHandler
057{
058    /**
059     * Converts a single object to the specified target type. A concrete
060     * implementation has to attempt a conversion. If this is not possible, a
061     * {@link ConversionException} is thrown. It is up to a concrete
062     * implementation how <b>null</b> values are handled; a default strategy
063     * would be to return <b>null</b> if the source object is <b>null</b>.
064     *
065     * @param <T> the type of the desired result
066     * @param src the object to be converted
067     * @param targetCls the target class of the conversion
068     * @param ci an object for performing variable substitution
069     * @return the converted object
070     * @throws ConversionException if the requested conversion is not possible
071     */
072    <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci);
073
074    /**
075     * Converts the given object to an array of the specified element type. The
076     * object can be a single value (e.g. a String, a primitive, etc.) or a
077     * complex object containing multiple values (like a collection or another
078     * array). In the latter case all elements contained in the complex object
079     * are converted to the target type. If the value(s) cannot be converted to
080     * the desired target class, a {@link ConversionException} is thrown. Note
081     * that the result type of this method is {@code Object}; because this
082     * method can also produce arrays of a primitive type the return type
083     * {@code Object[]} cannot be used.
084     *
085     * @param src the object to be converted
086     * @param elemClass the element class of the resulting array
087     * @param ci an object for performing variable substitution
088     * @return the array with the converted values
089     * @throws ConversionException if the conversion of an element is not
090     *         possible
091     */
092    Object toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci);
093
094    /**
095     * Converts the given object to a collection of the specified type. The
096     * target collection must be provided (here callers have the option to
097     * specify different types of collections like lists or sets). All values
098     * contained in the specified source object (or the source object itself if
099     * it is a single value) are converted to the desired target class and added
100     * to the destination collection. If the conversion of an element is not
101     * possible, a {@link ConversionException} is thrown.
102     *
103     * @param <T> the type of the elements of the destination collection
104     * @param src the object to be converted
105     * @param elemClass the element class of the destination collection
106     * @param ci an object for performing variable substitution
107     * @param dest the destination collection
108     */
109    <T> void toCollection(Object src, Class<T> elemClass,
110            ConfigurationInterpolator ci, Collection<T> dest);
111}