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;
020import java.util.List;
021
022/**
023 * <p>
024 * Definition of an interface that controls the handling of list delimiters in configuration properties.
025 * </p>
026 * <p>
027 * {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration} supports list delimiters in
028 * property values. If such a delimiter is found, the value actually contains multiple values and has to be split. This
029 * is useful for instance for {@link org.apache.commons.configuration2.PropertiesConfiguration PropertiesConfiguration}:
030 * properties files that have to be compatible with the {@code java.util.Properties} class cannot have multiple
031 * occurrences of a single property key, therefore a different storage scheme for multi-valued properties is needed. A
032 * possible storage scheme could look as follows:
033 * </p>
034 *
035 * <pre>
036 * myProperty=value1,value2,value3
037 * </pre>
038 *
039 * <p>
040 * Here a comma is used as list delimiter. When parsing this property (and using a corresponding
041 * {@code ListDelimiterHandler} implementation) the string value is split, and three values are added for the property
042 * key.
043 * </p>
044 * <p>
045 * A {@code ListDelimiterHandler} knows how to parse and to escape property values. It is called by concrete
046 * {@code Configuration} implementations when they have to deal with properties with multiple values.
047 * </p>
048 *
049 * @since 2.0
050 */
051public interface ListDelimiterHandler {
052    /**
053     * A specialized {@code ValueTransformer} implementation which does no transformation. The {@code transformValue()}
054     * method just returns the passed in object without changes. This instance can be used by configurations which do not
055     * require additional encoding.
056     */
057    ValueTransformer NOOP_TRANSFORMER = value -> value;
058
059    /**
060     * Parses the specified value for list delimiters and splits it if necessary. The passed in object can be either a
061     * single value or a complex one, e.g. a collection, an array, or an {@code Iterable}. It is the responsibility of this
062     * method to return an {@code Iterable} which contains all extracted values.
063     *
064     * @param value the value to be parsed
065     * @return an {@code Iterable} allowing access to all extracted values
066     */
067    Iterable<?> parse(Object value);
068
069    /**
070     * Splits the specified string at the list delimiter and returns a collection with all extracted components. A concrete
071     * implementation also has to deal with escape characters which might mask a list delimiter character at certain
072     * positions. The boolean {@code trim} flag determines whether each extracted component should be trimmed. This
073     * typically makes sense as the list delimiter may be surrounded by whitespace. However, there may be specific use cases
074     * in which automatic trimming is not desired.
075     *
076     * @param s the string to be split
077     * @param trim a flag whether each component of the string is to be trimmed
078     * @return a collection with all components extracted from the string
079     */
080    Collection<String> split(String s, boolean trim);
081
082    /**
083     * Escapes the specified single value object. This method is called for properties containing only a single value. So
084     * this method can rely on the fact that the passed in object is not a list. An implementation has to check whether the
085     * value contains list delimiter characters and - if so - escape them accordingly.
086     *
087     * @param value the value to be escaped
088     * @param transformer a {@code ValueTransformer} for an additional encoding (must not be <b>null</b>)
089     * @return the escaped value
090     */
091    Object escape(Object value, ValueTransformer transformer);
092
093    /**
094     * Escapes all values in the given list and concatenates them to a single string. This operation is required by
095     * configurations that have to represent properties with multiple values in a single line in their external
096     * configuration representation. This may require an advanced escaping in some cases.
097     *
098     * @param values the list with all the values to be converted to a single value
099     * @param transformer a {@code ValueTransformer} for an additional encoding (must not be <b>null</b>)
100     * @return the resulting escaped value
101     */
102    Object escapeList(List<?> values, ValueTransformer transformer);
103}