ListDelimiterHandler.java
/*
* 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 java.util.Collections;
import java.util.IdentityHashMap;
import java.util.List;
/**
* <p>
* Definition of an interface that controls the handling of list delimiters in configuration properties.
* </p>
* <p>
* {@link org.apache.commons.configuration2.AbstractConfiguration AbstractConfiguration} supports list delimiters in
* property values. If such a delimiter is found, the value actually contains multiple values and has to be split. This
* is useful for instance for {@link org.apache.commons.configuration2.PropertiesConfiguration PropertiesConfiguration}:
* properties files that have to be compatible with the {@link java.util.Properties} class cannot have multiple
* occurrences of a single property key, therefore a different storage scheme for multi-valued properties is needed. A
* possible storage scheme could look as follows:
* </p>
*
* <pre>
* myProperty=value1,value2,value3
* </pre>
*
* <p>
* Here a comma is used as list delimiter. When parsing this property (and using a corresponding
* {@code ListDelimiterHandler} implementation) the string value is split, and three values are added for the property
* key.
* </p>
* <p>
* A {@code ListDelimiterHandler} knows how to parse and to escape property values. It is called by concrete
* {@code Configuration} implementations when they have to deal with properties with multiple values.
* </p>
*
* @since 2.0
*/
public interface ListDelimiterHandler {
/**
* A specialized {@code ValueTransformer} implementation which does no transformation. The {@code transformValue()}
* method just returns the passed in object without changes. This instance can be used by configurations which do not
* require additional encoding.
*/
ValueTransformer NOOP_TRANSFORMER = value -> value;
/**
* Escapes the specified single value object. This method is called for properties containing only a single value. So
* this method can rely on the fact that the passed in object is not a list. An implementation has to check whether the
* value contains list delimiter characters and - if so - escape them accordingly.
*
* @param value the value to be escaped
* @param transformer a {@code ValueTransformer} for an additional encoding (must not be <b>null</b>)
* @return the escaped value
*/
Object escape(Object value, ValueTransformer transformer);
/**
* Escapes all values in the given list and concatenates them to a single string. This operation is required by
* configurations that have to represent properties with multiple values in a single line in their external
* configuration representation. This may require an advanced escaping in some cases.
*
* @param values the list with all the values to be converted to a single value
* @param transformer a {@code ValueTransformer} for an additional encoding (must not be <b>null</b>)
* @return the resulting escaped value
*/
Object escapeList(List<?> values, ValueTransformer transformer);
/**
* Extracts all values contained in the specified object up to the given limit. The passed in object is evaluated (if
* necessary in a recursive way). If it is a complex object (e.g. a collection or an array), all its elements are
* processed recursively and added to a target collection. The process stops if the limit is reached, but depending on
* the input object, it might be exceeded. (The limit is just an indicator to stop the process to avoid unnecessary work
* if the caller is only interested in a few values.)
*
* @param value the value to be processed
* @param limit the limit for aborting the processing
* @return a "flat" collection containing all primitive values of the passed in object
* @since 2.9.0
*/
default Collection<?> flatten(final Object value, final int limit) {
return AbstractListDelimiterHandler.flatten(this, value, limit, Collections.newSetFromMap(new IdentityHashMap<>()));
}
/**
* Parses the specified value for list delimiters and splits it if necessary. The passed in object can be either a
* single value or a complex one, e.g. a collection, an array, or an {@code Iterable}. It is the responsibility of this
* method to return an {@code Iterable} which contains all extracted values.
*
* @param value the value to be parsed
* @return an {@code Iterable} allowing access to all extracted values
*/
Iterable<?> parse(Object value);
/**
* Splits the specified string at the list delimiter and returns a collection with all extracted components. A concrete
* implementation also has to deal with escape characters which might mask a list delimiter character at certain
* positions. The boolean {@code trim} flag determines whether each extracted component should be trimmed. This
* typically makes sense as the list delimiter may be surrounded by whitespace. However, there may be specific use cases
* in which automatic trimming is not desired.
*
* @param s the string to be split
* @param trim a flag whether each component of the string is to be trimmed
* @return a collection with all components extracted from the string
*/
Collection<String> split(String s, boolean trim);
}