    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.util.ArrayList;
    020import java.util.Collection;
    021import java.util.Collections;
    022import java.util.Iterator;
    023import java.util.List;
    024
    025import org.apache.commons.lang3.StringUtils;
    026
    027/**
    028 * <p>
    029 * A specialized implementation of {@code ListDelimiterHandler} which simulates
    030 * the list delimiter handling as it was used by {@code PropertiesConfiguration}
    031 * in Commons Configuration 1.x.
    032 * </p>
    033 * <p>
    034 * This class mainly exists for compatibility reasons. It is intended to be used
    035 * by applications which have to deal with properties files created by an older
    036 * version of this library.
    037 * </p>
    038 * <p>
    039 * In the 1.x series of Commons Configuration list handling was not fully
    040 * consistent. The escaping of property values was done in a different way if
    041 * they contained a list delimiter or not. From version 2.0 on, escaping is more
    042 * stringent which might cause slightly different results when parsing
    043 * properties files created by or for Configuration 1.x. If you encounter such
    044 * problems, you can switch to this {@code ListDelimiterHandler} implementation
    045 * rather than the default one. In other cases, this class should not be used!
    046 * </p>
    047 * <p>
    048 * Implementation note: An instance of this class can safely be shared between
    049 * multiple {@code Configuration} instances.
    050 * </p>
    051 *
    052 * @version $Id: LegacyListDelimiterHandler.java 1842194 2018-09-27 22:24:23Z ggregory $
    053 * @since 2.0
    054 */
    055public class LegacyListDelimiterHandler extends AbstractListDelimiterHandler
    056{
    057    /** Constant for the escaping character. */
    058    private static final String ESCAPE = "\\";
    059
    060    /** Constant for the escaped escaping character. */
    061    private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
    062
    063    /** Constant for a duplicated sequence of escaping characters. */
    064    private static final String QUAD_ESC = DOUBLE_ESC + DOUBLE_ESC;
    065
    066    /** The list delimiter character. */
    067    private final char delimiter;
    068
    069    /**
    070     * Creates a new instance of {@code LegacyListDelimiterHandler} and sets the
    071     * list delimiter character.
    072     *
    073     * @param listDelimiter the list delimiter character
    074     */
    075    public LegacyListDelimiterHandler(final char listDelimiter)
    076    {
    077        delimiter = listDelimiter;
    078    }
    079
    080    /**
    081     * Returns the list delimiter character.
    082     *
    083     * @return the list delimiter character
    084     */
    085    public char getDelimiter()
    086    {
    087        return delimiter;
    088    }
    089
    090    /**
    091     * {@inheritDoc} This implementation performs delimiter escaping for a
    092     * single value (which is not part of a list).
    093     */
    094    @Override
    095    public Object escape(final Object value, final ValueTransformer transformer)
    096    {
    097        return escapeValue(value, false, transformer);
    098    }
    099
    100    /**
    101     * {@inheritDoc} This implementation performs a special encoding of
    102     * backslashes at the end of a string so that they are not interpreted as
    103     * escape character for a following list delimiter.
    104     */
    105    @Override
    106    public Object escapeList(final List<?> values, final ValueTransformer transformer)
    107    {
    108        if (!values.isEmpty())
    109        {
    110            final Iterator<?> it = values.iterator();
    111            String lastValue = escapeValue(it.next(), true, transformer);
    112            final StringBuilder buf = new StringBuilder(lastValue);
    113            while (it.hasNext())
    114            {
    115                // if the last value ended with an escape character, it has
    116                // to be escaped itself; otherwise the list delimiter will
    117                // be escaped
    118                if (lastValue.endsWith(ESCAPE)
    119                        && (countTrailingBS(lastValue) / 2) % 2 != 0)
    120                {
    121                    buf.append(ESCAPE).append(ESCAPE);
    122                }
    123                buf.append(getDelimiter());
    124                lastValue = escapeValue(it.next(), true, transformer);
    125                buf.append(lastValue);
    126            }
    127            return buf.toString();
    128        }
    129        return null;
    130    }
    131
    132    /**
    133     * {@inheritDoc} This implementation simulates the old splitting algorithm.
    134     * The string is split at the delimiter character if it is not escaped. If
    135     * the delimiter character is not found, the input is returned unchanged.
    136     */
    137    @Override
    138    protected Collection<String> splitString(final String s, final boolean trim)
    139    {
    140        if (s.indexOf(getDelimiter()) < 0)
    141        {
    142            return Collections.singleton(s);
    143        }
    144
    145        final List<String> list = new ArrayList<>();
    146
    147        StringBuilder token = new StringBuilder();
    148        int begin = 0;
    149        boolean inEscape = false;
    150        final char esc = ESCAPE.charAt(0);
    151
    152        while (begin < s.length())
    153        {
    154            final char c = s.charAt(begin);
    155            if (inEscape)
    156            {
    157                // last character was the escape marker
    158                // can current character be escaped?
    159                if (c != getDelimiter() && c != esc)
    160                {
    161                    // no, also add escape character
    162                    token.append(esc);
    163                }
    164                token.append(c);
    165                inEscape = false;
    166            }
    167
    168            else
    169            {
    170                if (c == getDelimiter())
    171                {
    172                    // found a list delimiter -> add token and
    173                    // resetDefaultFileSystem buffer
    174                    String t = token.toString();
    175                    if (trim)
    176                    {
    177                        t = t.trim();
    178                    }
    179                    list.add(t);
    180                    token = new StringBuilder();
    181                }
    182                else if (c == esc)
    183                {
    184                    // eventually escape next character
    185                    inEscape = true;
    186                }
    187                else
    188                {
    189                    token.append(c);
    190                }
    191            }
    192
    193            begin++;
    194        }
    195
    196        // Trailing delimiter?
    197        if (inEscape)
    198        {
    199            token.append(esc);
    200        }
    201        // Add last token
    202        String t = token.toString();
    203        if (trim)
    204        {
    205            t = t.trim();
    206        }
    207        list.add(t);
    208
    209        return list;
    210    }
    211
    212    /**
    213     * {@inheritDoc} This is just a dummy implementation. It is never called.
    214     */
    215    @Override
    216    protected String escapeString(final String s)
    217    {
    218        return null;
    219    }
    220
    221    /**
    222     * Performs the escaping of backslashes in the specified properties value.
    223     * Because a double backslash is used to escape the escape character of a
    224     * list delimiter, double backslashes also have to be escaped if the
    225     * property is part of a (single line) list. In addition, because the output
    226     * is written into a properties file, each occurrence of a backslash again
    227     * has to be doubled. This method is called by {@code escapeValue()}.
    228     *
    229     * @param value the value to be escaped
    230     * @param inList a flag whether the value is part of a list
    231     * @return the value with escaped backslashes as string
    232     */
    233    protected String escapeBackslashs(final Object value, final boolean inList)
    234    {
    235        String strValue = String.valueOf(value);
    236
    237        if (inList && strValue.indexOf(DOUBLE_ESC) >= 0)
    238        {
    239            strValue = StringUtils.replace(strValue, DOUBLE_ESC, QUAD_ESC);
    240        }
    241
    242        return strValue;
    243    }
    244
    245    /**
    246     * Escapes the given property value. This method is called on saving the
    247     * configuration for each property value. It ensures a correct handling of
    248     * backslash characters and also takes care that list delimiter characters
    249     * in the value are escaped.
    250     *
    251     * @param value the property value
    252     * @param inList a flag whether the value is part of a list
    253     * @param transformer the {@code ValueTransformer}
    254     * @return the escaped property value
    255     */
    256    protected String escapeValue(final Object value, final boolean inList,
    257            final ValueTransformer transformer)
    258    {
    259        String escapedValue =
    260                String.valueOf(transformer.transformValue(escapeBackslashs(
    261                        value, inList)));
    262        if (getDelimiter() != 0)
    263        {
    264            escapedValue =
    265                    StringUtils.replace(escapedValue,
    266                            String.valueOf(getDelimiter()), ESCAPE
    267                                    + getDelimiter());
    268        }
    269        return escapedValue;
    270    }
    271
    272    /**
    273     * Returns the number of trailing backslashes. This is sometimes needed for
    274     * the correct handling of escape characters.
    275     *
    276     * @param line the string to investigate
    277     * @return the number of trailing backslashes
    278     */
    279    private static int countTrailingBS(final String line)
    280    {
    281        int bsCount = 0;
    282        for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
    283        {
    284            bsCount++;
    285        }
    286
    287        return bsCount;
    288    }
    289}