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}