Package org.apache.commons.configuration2.convert

## Class AbstractListDelimiterHandler

- java.lang.Object
- - org.apache.commons.configuration2.convert.AbstractListDelimiterHandler

- All Implemented Interfaces:
    `ListDelimiterHandler`
  Direct Known Subclasses:
    `DefaultListDelimiterHandler`, `DisabledListDelimiterHandler`, `LegacyListDelimiterHandler`

      public abstract class AbstractListDelimiterHandler
      extends Object
      implements ListDelimiterHandler

  An abstract base class for concrete `ListDelimiterHandler` implementations.

  This base class provides a fully functional implementation for parsing a value object which can deal with different cases like collections, arrays, iterators, etc. This logic is typically needed by every concrete subclass. Other methods are partly implemented handling special corner cases like null values; concrete subclasses do not have do implement the corresponding checks.

  Since:
    2.0

- - ### Field Summary

    - ### Fields inherited from interface org.apache.commons.configuration2.convert.ListDelimiterHandler

      `NOOP_TRANSFORMER`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AbstractListDelimiterHandler()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Object` | `escape​(Object value, ValueTransformer transformer)` | Escapes the specified single value object.
    `protected abstract String` | `escapeString​(String s)` | Escapes the specified string.
    `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.
    `protected abstract Collection<String>` | `splitString​(String s, boolean trim)` | Actually splits the passed in string which is guaranteed to be not null.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.commons.configuration2.convert.ListDelimiterHandler

      `escapeList, flatten`

- - ### Constructor Detail

    - #### AbstractListDelimiterHandler

          public AbstractListDelimiterHandler()

  - ### Method Detail

    - #### escape

          public 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. This implementation checks whether the object to be escaped is a string. If yes, it delegates to `escapeString(String)`, otherwise no escaping is performed. Eventually, the passed in transformer is invoked so that additional encoding can be performed.
      Specified by:
        `escape` in interface `ListDelimiterHandler`
      Parameters:
        `value` - the value to be escaped
        `transformer` - a `ValueTransformer` for an additional encoding (must not be null)
      Returns:
        the escaped value

    - #### escapeString

          protected abstract String escapeString​(String s)

      Escapes the specified string. This method is called by `escape()` if the passed in object is a string. Concrete subclasses have to implement their specific escaping logic here, so that the list delimiters they support are properly escaped.
      Parameters:
        `s` - the string to be escaped (not null)
      Returns:
        the escaped string

    - #### parse

          public 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. Depending on the type of the passed in object the following things happen:
      - Strings are checked for delimiter characters and split if necessary. This is done by calling the `split()` method.
      - For objects implementing the `Iterable` interface, the corresponding `Iterator` is obtained, and contained elements are added to the resulting iteration.
      - Arrays are treated as `Iterable` objects.
      - All other types are directly inserted.
      - Recursive combinations are supported, e.g. a collection containing an array that contains strings: The resulting collection will only contain primitive objects.
      Specified by:
        `parse` in interface `ListDelimiterHandler`
      Parameters:
        `value` - the value to be parsed
      Returns:
        an `Iterable` allowing access to all extracted values

    - #### split

          public 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. This implementation handles the case that the passed in string is null. In this case, an empty collection is returned. Otherwise, this method delegates to `splitString(String, boolean)`.
      Specified by:
        `split` in interface `ListDelimiterHandler`
      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

    - #### splitString

          protected abstract Collection<String> splitString​(String s,
                                                            boolean trim)

      Actually splits the passed in string which is guaranteed to be not null. This method is called by the base implementation of the `split()` method. Here the actual splitting logic has to be implemented.
      Parameters:
        `s` - the string to be split (not null)
        `trim` - a flag whether the single components have to be trimmed
      Returns:
        a collection with the extracted components of the passed in string