https://commons.apache.org/proper/commons-configuration/: Tools to assist in the reading of configuration/preferences files in various formats (The Apache Software Foundation)
  • Konstantin Shaposhnikov (scand.com)
  • Jamie M. Guillemette (TD Bank)
  • Jorge Ferrer ()
  • Gabriele Garuglieri (Infoblu S.p.A)
  • Nicolas De Loof (Cap Gemini)
  • Oliver Kopp
  • Dennis Kieselhorst (IRIAN Deutschland)
  • Raviteja Lokineni
  • Vincent Maurin (glispa GmbH)
  • The Alchemist
  • Pascal Essiembre (Norconex Inc.)
  • Patrick Schmidt
  • Daniel Rall (CollabNet, Inc.)
  • Jason van Zyl (Zenplex)
  • Martin Poeschl (tucana.at)
  • dIon Gillard (Multitask Consulting)
  • Henning P. Schmiedehausen (INTERMETA - Gesellschaft fuer Mehrwertdienste mbH)
  • Eric Pugh (upstate.com)
  • Brian E. Dunbar (dunbarconsulting.org)
  • Emmanuel Bourg (Ariane Software)
  • Oliver Heger (Bosch Software Innovations)
  • Jörg Schaible
  • Ralph Goers (Intuit)
  • Gary Gregory (Rocket Software)
  • Claude Warren
  • Rob Tompkins 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.configuration2.convert;

import java.util.Collection;

import org.apache.commons.configuration2.ex.ConversionException;
import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;



An interface defining the possible data type conversions supported by the
configuration framework.




This interface defines a couple of methods related to different kinds of data
type conversion:



    

  • Conversion to an object of a specific type
    • 

  • Conversion to an array of a specific type
    • 

  • Conversion to a collection of a specific type
    • 



 Data type conversion is related to variable substitution (aka interpolation). Before a value can be converted to a target type substitution has to be performed first, and the conversion is done on the resulting value. In order to support this, the conversion methods expect a ConfigurationInterpolator object; Configuration implementations here pass in their associated instance. 


 A Configuration object is associated with a concrete ConversionHandler implementation. Whenever a data type conversion is required it delegates to this handler. By providing a custom ConversionHandler object, the type conversion performed by the configuration object can be adapted. 


Since:2.0
/**
 * <p>
 * An interface defining the possible data type conversions supported by the
 * configuration framework.
 * </p>
 * <p>
 * This interface defines a couple of methods related to different kinds of data
 * type conversion:
 * </p>
 * <ul>
 * <li>Conversion to an object of a specific type</li>
 * <li>Conversion to an array of a specific type</li>
 * <li>Conversion to a collection of a specific type</li>
 * </ul>
 * <p>
 * Data type conversion is related to variable substitution (aka interpolation).
 * Before a value can be converted to a target type substitution has to be
 * performed first, and the conversion is done on the resulting value. In order
 * to support this, the conversion methods expect a
 * {@link ConfigurationInterpolator} object; {@code Configuration}
 * implementations here pass in their associated instance.
 * </p>
 * <p>
 * A {@code Configuration} object is associated with a concrete
 * {@code ConversionHandler} implementation. Whenever a data type conversion is
 * required it delegates to this handler. By providing a custom
 * {@code ConversionHandler} object, the type conversion performed by the
 * configuration object can be adapted.
 * </p>
 *
 * @since 2.0
 */
public interface ConversionHandler
{
    
Converts a single object to the specified target type. A concrete implementation has to attempt a conversion. If this is not possible, a ConversionException is thrown. It is up to a concrete implementation how null values are handled; a default strategy
would be to return null if the source object is null.

Params:
  • src – the object to be converted
  • targetCls – the target class of the conversion
  • ci – an object for performing variable substitution
Type parameters:
  • <T> – the type of the desired result
Throws:
Returns:the converted object
/**
     * Converts a single object to the specified target type. A concrete
     * implementation has to attempt a conversion. If this is not possible, a
     * {@link ConversionException} is thrown. It is up to a concrete
     * implementation how <b>null</b> values are handled; a default strategy
     * would be to return <b>null</b> if the source object is <b>null</b>.
     *
     * @param <T> the type of the desired result
     * @param src the object to be converted
     * @param targetCls the target class of the conversion
     * @param ci an object for performing variable substitution
     * @return the converted object
     * @throws ConversionException if the requested conversion is not possible
     */
    <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci);

    
Converts the given object to an array of the specified element type. The object can be a single value (e.g. a String, a primitive, etc.) or a complex object containing multiple values (like a collection or another array). In the latter case all elements contained in the complex object are converted to the target type. If the value(s) cannot be converted to the desired target class, a ConversionException is thrown. Note that the result type of this method is Object; because this method can also produce arrays of a primitive type the return type Object[] cannot be used. 
Params:
  • src – the object to be converted
  • elemClass – the element class of the resulting array
  • ci – an object for performing variable substitution
Throws:
Returns:the array with the converted values
/**
     * Converts the given object to an array of the specified element type. The
     * object can be a single value (e.g. a String, a primitive, etc.) or a
     * complex object containing multiple values (like a collection or another
     * array). In the latter case all elements contained in the complex object
     * are converted to the target type. If the value(s) cannot be converted to
     * the desired target class, a {@link ConversionException} is thrown. Note
     * that the result type of this method is {@code Object}; because this
     * method can also produce arrays of a primitive type the return type
     * {@code Object[]} cannot be used.
     *
     * @param src the object to be converted
     * @param elemClass the element class of the resulting array
     * @param ci an object for performing variable substitution
     * @return the array with the converted values
     * @throws ConversionException if the conversion of an element is not
     *         possible
     */
    Object toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci);

    
Converts the given object to a collection of the specified type. The target collection must be provided (here callers have the option to specify different types of collections like lists or sets). All values contained in the specified source object (or the source object itself if it is a single value) are converted to the desired target class and added to the destination collection. If the conversion of an element is not possible, a ConversionException is thrown. 
Params:
  • src – the object to be converted
  • elemClass – the element class of the destination collection
  • ci – an object for performing variable substitution
  • dest – the destination collection
Type parameters:
  • <T> – the type of the elements of the destination collection
/**
     * Converts the given object to a collection of the specified type. The
     * target collection must be provided (here callers have the option to
     * specify different types of collections like lists or sets). All values
     * contained in the specified source object (or the source object itself if
     * it is a single value) are converted to the desired target class and added
     * to the destination collection. If the conversion of an element is not
     * possible, a {@link ConversionException} is thrown.
     *
     * @param <T> the type of the elements of the destination collection
     * @param src the object to be converted
     * @param elemClass the element class of the destination collection
     * @param ci an object for performing variable substitution
     * @param dest the destination collection
     */
    <T> void toCollection(Object src, Class<T> elemClass,
            ConfigurationInterpolator ci, Collection<T> dest);
}