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

Package org.apache.commons.configuration2.convert

# Class DefaultListDelimiterHandler

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

All Implemented Interfaces:
  `ListDelimiterHandler`

public class DefaultListDelimiterHandler extends AbstractListDelimiterHandler

The default implementation of the `ListDelimiterHandler` interface.

This class supports list splitting and delimiter escaping using a delimiter character that can be specified when constructing an instance. Splitting of strings works by scanning the input for the list delimiter character. The list delimiter character can be escaped by a backslash. So, provided that a comma is configured as list delimiter, in the example `val1,val2,val3` three values are recognized. In `3\,1415` the list delimiter is escaped so that only a single element is detected. (Note that when writing these examples in Java code, each backslash has to be doubled. This is also true for all other examples in this documentation.)

Because the backslash has a special meaning as escaping character it is always treated in a special way. If it occurs as a normal character in a property value, it has to be escaped using another backslash (similar to the rules of the Java programming language). The following example shows the correct way to define windows network shares: `\\\\Server\\path`. Note that each backslash is doubled. When combining the list delimiter with backslashes the same escaping rules apply. For instance, in `C:\\Temp\\,D:\\data\\` the list delimiter is recognized; it is not escaped by the preceding backslash because this backslash is itself escaped. In contrast, `C:\\Temp\\\,D:\\data\\` defines a single element with a comma being part of the value; two backslashes after `Temp` result in a single one, the third backslash escapes the list delimiter.

As can be seen, there are some constellations which are a bit tricky and cause a larger number of backslashes in sequence. Nevertheless, the escaping rules are consistent and do not cause ambiguous results.

Implementation node: An instance of this class can safely be shared between multiple `Configuration` instances.

Since:
  2.0

- ## Field Summary

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

  `NOOP_TRANSFORMER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultListDelimiterHandler(char listDelimiter)`
  Creates a new instance of `DefaultListDelimiterHandler` and sets the list delimiter character.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `escapeList(List<?> values, ValueTransformer transformer)`
  Escapes all values in the given list and concatenates them to a single string.
  `protected String`
  `escapeString(String s)`
  Escapes the specified string.
  `char`
  `getDelimiter()`
  Gets the list delimiter character used by this instance.
  `protected Collection<String>`
  `splitString(String s, boolean trim)`
  Actually splits the passed in string which is guaranteed to be not null.

  ### Methods inherited from class org.apache.commons.configuration2.convert.AbstractListDelimiterHandler

  `escape, parse, split`

  ### 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

  `flatten`

- ## Constructor Details

  - ### DefaultListDelimiterHandler

    public DefaultListDelimiterHandler(char listDelimiter)
    Creates a new instance of `DefaultListDelimiterHandler` and sets the list delimiter character.
    Parameters:
      `listDelimiter` - the list delimiter character

- ## Method Details

  - ### escapeList

    public Object escapeList(List<?> values, ValueTransformer transformer)
    Description copied from interface: `ListDelimiterHandler`
    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

  - ### escapeString

    protected String escapeString(String s)
    Description copied from class: `AbstractListDelimiterHandler`
    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.
    Specified by:
      `escapeString` in class `AbstractListDelimiterHandler`
    Parameters:
      `s` - the string to be escaped (not null)
    Returns:
      the escaped string

  - ### getDelimiter

    public char getDelimiter()
    Gets the list delimiter character used by this instance.
    Returns:
      the list delimiter character

  - ### splitString

    protected 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. This implementation reverses the escaping done by the `escape()` methods of this class. However, it tries to be tolerant with unexpected escaping sequences: If after the escape character "\" no allowed character follows, both the backslash and the following character are output.
    Specified by:
      `splitString` in class `AbstractListDelimiterHandler`
    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