Class 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 
      Modifier and Type Field Description
      private static int BUF_SIZE
      Constant for a buffer size for escaping strings.
      private char delimiter
      Stores the list delimiter character.
      private static char ESCAPE
      Constant for the escape character.
    • Constructor Summary

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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object escapeList​(java.util.List<?> values, ValueTransformer transformer)
      Escapes all values in the given list and concatenates them to a single string.
      protected java.lang.String escapeString​(java.lang.String s)
      Escapes the specified string.
      char getDelimiter()
      Gets the list delimiter character used by this instance.
      protected java.util.Collection<java.lang.String> splitString​(java.lang.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
    • Field Detail

      • ESCAPE

        private static final char ESCAPE
        Constant for the escape character.
        See Also:
        Constant Field Values
      • BUF_SIZE

        private static final int BUF_SIZE
        Constant for a buffer size for escaping strings. When a character is escaped the string becomes longer. Therefore, the output buffer is longer than the original string length. But we assume, that there are not too many characters that need to be escaped.
        See Also:
        Constant Field Values
      • delimiter

        private final char delimiter
        Stores the list delimiter character.
    • Constructor Detail

      • DefaultListDelimiterHandler

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

      • escapeList

        public java.lang.Object escapeList​(java.util.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 java.lang.String escapeString​(java.lang.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 java.util.Collection<java.lang.String> splitString​(java.lang.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