AbstractListDelimiterHandler (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2.convert, class: AbstractListDelimiterHandler

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()`
  Constructs a new instance.

- ## Method Summary

  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 Details

  - ### AbstractListDelimiterHandler

    public AbstractListDelimiterHandler()
    Constructs a new instance.

- ## Method Details

  - ### 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, for example 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, for example 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