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}