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 and Description
AbstractListDelimiterHandler()

Method Summary

Modifier and Type	Method and 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

Constructor Detail

AbstractListDelimiterHandler

public AbstractListDelimiterHandler()

Method Detail

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

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

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

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