1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.configuration2.convert;
18
19 import java.util.Collection;
20
21 import org.apache.commons.configuration2.ex.ConversionException;
22 import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;
23
24 /**
25 * <p>
26 * An interface defining the possible data type conversions supported by the configuration framework.
27 * </p>
28 * <p>
29 * This interface defines a couple of methods related to different kinds of data type conversion:
30 * </p>
31 * <ul>
32 * <li>Conversion to an object of a specific type</li>
33 * <li>Conversion to an array of a specific type</li>
34 * <li>Conversion to a collection of a specific type</li>
35 * </ul>
36 * <p>
37 * Data type conversion is related to variable substitution (aka interpolation). Before a value can be converted to a
38 * target type substitution has to be performed first, and the conversion is done on the resulting value. In order to
39 * support this, the conversion methods expect a {@link ConfigurationInterpolator} object; {@code Configuration}
40 * implementations here pass in their associated instance.
41 * </p>
42 * <p>
43 * A {@code Configuration} object is associated with a concrete {@code ConversionHandler} implementation. Whenever a
44 * data type conversion is required it delegates to this handler. By providing a custom {@code ConversionHandler}
45 * object, the type conversion performed by the configuration object can be adapted.
46 * </p>
47 *
48 * @since 2.0
49 */
50 public interface ConversionHandler {
51
52 /**
53 * Converts a single object to the specified target type. A concrete implementation has to attempt a conversion. If this
54 * is not possible, a {@link ConversionException} is thrown. It is up to a concrete implementation how <strong>null</strong>
55 * values are handled; a default strategy would be to return <strong>null</strong> if the source object is <strong>null</strong>.
56 *
57 * @param <T> the type of the desired result
58 * @param src the object to be converted
59 * @param targetCls the target class of the conversion
60 * @param ci an object for performing variable substitution
61 * @return the converted object
62 * @throws ConversionException if the requested conversion is not possible
63 */
64 <T> T to(Object src, Class<T> targetCls, ConfigurationInterpolator ci);
65
66 /**
67 * Converts the given object to an array of the specified element type. The object can be a single value (for example a String,
68 * a primitive, etc.) or a complex object containing multiple values (like a collection or another array). In the latter
69 * case all elements contained in the complex object are converted to the target type. If the value(s) cannot be
70 * converted to the desired target class, a {@link ConversionException} is thrown. Note that the result type of this
71 * method is {@code Object}; because this method can also produce arrays of a primitive type the return type
72 * {@code Object[]} cannot be used.
73 *
74 * @param src the object to be converted
75 * @param elemClass the element class of the resulting array
76 * @param ci an object for performing variable substitution
77 * @return the array with the converted values
78 * @throws ConversionException if the conversion of an element is not possible
79 */
80 Object toArray(Object src, Class<?> elemClass, ConfigurationInterpolator ci);
81
82 /**
83 * Converts the given object to a collection of the specified type. The target collection must be provided (here callers
84 * have the option to specify different types of collections like lists or sets). All values contained in the specified
85 * source object (or the source object itself if it is a single value) are converted to the desired target class and
86 * added to the destination collection. If the conversion of an element is not possible, a {@link ConversionException}
87 * is thrown.
88 *
89 * @param <T> the type of the elements of the destination collection
90 * @param src the object to be converted
91 * @param elemClass the element class of the destination collection
92 * @param ci an object for performing variable substitution
93 * @param dest the destination collection
94 */
95 <T> void toCollection(Object src, Class<T> elemClass, ConfigurationInterpolator ci, Collection<T> dest);
96 }