001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.configuration2.convert;
018
019import java.lang.reflect.Array;
020import java.util.ArrayList;
021import java.util.Collection;
022import java.util.Iterator;
023import java.util.LinkedList;
024
025/**
026 * <p>
027 * An abstract base class for concrete {@code ListDelimiterHandler}
028 * implementations.
029 * </p>
030 * <p>
031 * This base class provides a fully functional implementation for parsing a
032 * value object which can deal with different cases like collections, arrays,
033 * iterators, etc. This logic is typically needed by every concrete subclass.
034 * Other methods are partly implemented handling special corner cases like
035 * <b>null</b> values; concrete subclasses do not have do implement the
036 * corresponding checks.
037 * </p>
038 *
039 * @version $Id: AbstractListDelimiterHandler.java 1790899 2017-04-10 21:56:46Z ggregory $
040 * @since 2.0
041 */
042public abstract class AbstractListDelimiterHandler implements
043        ListDelimiterHandler
044{
045    /**
046     * {@inheritDoc} Depending on the type of the passed in object the following
047     * things happen:
048     * <ul>
049     * <li>Strings are checked for delimiter characters and split if necessary.
050     * This is done by calling the {@code split()} method.</li>
051     * <li>For objects implementing the {@code Iterable} interface, the
052     * corresponding {@code Iterator} is obtained, and contained elements are
053     * added to the resulting iteration.</li>
054     * <li>Arrays are treated as {@code Iterable} objects.</li>
055     * <li>All other types are directly inserted.</li>
056     * <li>Recursive combinations are supported, e.g. a collection containing an
057     * array that contains strings: The resulting collection will only contain
058     * primitive objects.</li>
059     * </ul>
060     */
061    @Override
062    public Iterable<?> parse(Object value)
063    {
064        return flatten(value);
065    }
066
067    /**
068     * {@inheritDoc} This implementation handles the case that the passed in
069     * string is <b>null</b>. In this case, an empty collection is returned.
070     * Otherwise, this method delegates to {@link #splitString(String, boolean)}.
071     */
072    @Override
073    public Collection<String> split(String s, boolean trim)
074    {
075        if (s == null)
076        {
077            return new ArrayList<>(0);
078        }
079        return splitString(s, trim);
080    }
081
082    /**
083     * {@inheritDoc} This implementation checks whether the object to be escaped
084     * is a string. If yes, it delegates to {@link #escapeString(String)},
085     * otherwise no escaping is performed. Eventually, the passed in transformer
086     * is invoked so that additional encoding can be performed.
087     */
088    @Override
089    public Object escape(Object value, ValueTransformer transformer)
090    {
091        Object escValue =
092                (value instanceof String) ? escapeString((String) value)
093                        : value;
094        return transformer.transformValue(escValue);
095    }
096
097    /**
098     * Actually splits the passed in string which is guaranteed to be not
099     * <b>null</b>. This method is called by the base implementation of the
100     * {@code split()} method. Here the actual splitting logic has to be
101     * implemented.
102     *
103     * @param s the string to be split (not <b>null</b>)
104     * @param trim a flag whether the single components have to be trimmed
105     * @return a collection with the extracted components of the passed in
106     *         string
107     */
108    protected abstract Collection<String> splitString(String s, boolean trim);
109
110    /**
111     * Escapes the specified string. This method is called by {@code escape()}
112     * if the passed in object is a string. Concrete subclasses have to
113     * implement their specific escaping logic here, so that the list delimiters
114     * they support are properly escaped.
115     *
116     * @param s the string to be escaped (not <b>null</b>)
117     * @return the escaped string
118     */
119    protected abstract String escapeString(String s);
120
121    /**
122     * Extracts all values contained in the specified object up to the given
123     * limit. The passed in object is evaluated (if necessary in a recursive
124     * way). If it is a complex object (e.g. a collection or an array), all its
125     * elements are processed recursively and added to a target collection. The
126     * process stops if the limit is reached, but depending on the input object,
127     * it might be exceeded. (The limit is just an indicator to stop the process
128     * to avoid unnecessary work if the caller is only interested in a few
129     * values.)
130     *
131     * @param value the value to be processed
132     * @param limit the limit for aborting the processing
133     * @return a &quot;flat&quot; collection containing all primitive values of
134     *         the passed in object
135     */
136    Collection<?> flatten(Object value, int limit)
137    {
138        if (value instanceof String)
139        {
140            return split((String) value, true);
141        }
142
143        Collection<Object> result = new LinkedList<>();
144        if (value instanceof Iterable)
145        {
146            flattenIterator(result, ((Iterable<?>) value).iterator(), limit);
147        }
148        else if (value instanceof Iterator)
149        {
150            flattenIterator(result, (Iterator<?>) value, limit);
151        }
152        else if (value != null)
153        {
154            if (value.getClass().isArray())
155            {
156                for (int len = Array.getLength(value), idx = 0, size = 0; idx < len
157                        && size < limit; idx++, size = result.size())
158                {
159                    result.addAll(flatten(Array.get(value, idx), limit - size));
160                }
161            }
162            else
163            {
164                result.add(value);
165            }
166        }
167
168        return result;
169    }
170
171    /**
172     * Performs the actual work as advertised by the {@code parse()} method.
173     * This method delegates to {@link #flatten(Object, int)} without specifying
174     * a limit.
175     *
176     * @param value the value to be processed
177     * @return a &quot;flat&quot; collection containing all primitive values of
178     *         the passed in object
179     */
180    private Collection<?> flatten(Object value)
181    {
182        return flatten(value, Integer.MAX_VALUE);
183    }
184
185    /**
186     * Flattens the given iterator. For each element in the iteration
187     * {@code flatten()} is called recursively.
188     *
189     * @param target the target collection
190     * @param it the iterator to process
191     * @param limit a limit for the number of elements to extract
192     */
193    private void flattenIterator(Collection<Object> target, Iterator<?> it, int limit)
194    {
195        int size = target.size();
196        while (size < limit && it.hasNext())
197        {
198            target.addAll(flatten(it.next(), limit - size));
199            size = target.size();
200        }
201    }
202}