Package org.apache.commons.configuration2.convert

## Interface ListDelimiterHandler

- All Known Implementing Classes:
    `AbstractListDelimiterHandler`, `DefaultListDelimiterHandler`, `DisabledListDelimiterHandler`, `LegacyListDelimiterHandler`

      public interface ListDelimiterHandler

  Definition of an interface that controls the handling of list delimiters in configuration properties.

  `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 `PropertiesConfiguration`: properties files that have to be compatible with the `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:

       myProperty=value1,value2,value3

  Here a comma is used as list delimiter. When parsing this property (and using a corresponding `ListDelimiterHandler` implementation) the string value is split, and three values are added for the property key.

  A `ListDelimiterHandler` knows how to parse and to escape property values. It is called by concrete `Configuration` implementations when they have to deal with properties with multiple values.

  Since:
    2.0

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static ValueTransformer` | `NOOP_TRANSFORMER` | A specialized `ValueTransformer` implementation which does no transformation.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Object` | `escape​(Object value, ValueTransformer transformer)` | Escapes the specified single value object.
    `Object` | `escapeList​(List<?> values, ValueTransformer transformer)` | Escapes all values in the given list and concatenates them to a single string.
    `default Collection<?>` | `flatten​(Object value, int limit)` | Extracts all values contained in the specified object up to the given limit.
    `Iterable<?>` | `parse​(Object value)` | Parses the specified value for list delimiters and splits it if necessary.
    `Collection<String>` | `split​(String s, boolean trim)` | Splits the specified string at the list delimiter and returns a collection with all extracted components.

- - ### Field Detail

    - #### NOOP_TRANSFORMER

          static final ValueTransformer NOOP_TRANSFORMER

      A specialized `ValueTransformer` implementation which does no transformation. The `transformValue()` method just returns the passed in object without changes. This instance can be used by configurations which do not require additional encoding.

  - ### Method Detail

    - #### escape

          Object escape​(Object value,
                        ValueTransformer transformer)

      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.
      Parameters:
        `value` - the value to be escaped
        `transformer` - a `ValueTransformer` for an additional encoding (must not be null)
      Returns:
        the escaped value

    - #### escapeList

          Object escapeList​(List<?> values,
                            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.
      Parameters:
        `values` - the list with all the values to be converted to a single value
        `transformer` - a `ValueTransformer` for an additional encoding (must not be null)
      Returns:
        the resulting escaped value

    - #### parse

          Iterable<?> parse​(Object value)

      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 `Iterable`. It is the responsibility of this method to return an `Iterable` which contains all extracted values.
      Parameters:
        `value` - the value to be parsed
      Returns:
        an `Iterable` allowing access to all extracted values

    - #### split

          Collection<String> split​(String s,
                                   boolean trim)

      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 `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.
      Parameters:
        `s` - the string to be split
        `trim` - a flag whether each component of the string is to be trimmed
      Returns:
        a collection with all components extracted from the string

    - #### flatten

          default Collection<?> flatten​(Object value,
                                        int limit)

      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.)
      Parameters:
        `value` - the value to be processed
        `limit` - the limit for aborting the processing
      Returns:
        a "flat" collection containing all primitive values of the passed in object
      Since:
        2.9.0