View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration2.convert;
18  
19  import java.util.ArrayList;
20  import java.util.Collection;
21  import java.util.Collections;
22  import java.util.Iterator;
23  import java.util.List;
24  
25  import org.apache.commons.lang3.StringUtils;
26  
27  /**
28   * <p>
29   * A specialized implementation of {@code ListDelimiterHandler} which simulates the list delimiter handling as it was
30   * used by {@code PropertiesConfiguration} in Commons Configuration 1.x.
31   * </p>
32   * <p>
33   * This class mainly exists for compatibility reasons. It is intended to be used by applications which have to deal with
34   * properties files created by an older version of this library.
35   * </p>
36   * <p>
37   * In the 1.x series of Commons Configuration list handling was not fully consistent. The escaping of property values
38   * was done in a different way if they contained a list delimiter or not. From version 2.0 on, escaping is more
39   * stringent which might cause slightly different results when parsing properties files created by or for Configuration
40   * 1.x. If you encounter such problems, you can switch to this {@code ListDelimiterHandler} implementation rather than
41   * the default one. In other cases, this class should not be used!
42   * </p>
43   * <p>
44   * Implementation note: An instance of this class can safely be shared between multiple {@code Configuration} instances.
45   * </p>
46   *
47   * @since 2.0
48   */
49  public class LegacyListDelimiterHandler extends AbstractListDelimiterHandler {
50      /** Constant for the escaping character. */
51      private static final String ESCAPE = "\\";
52  
53      /** Constant for the escaped escaping character. */
54      private static final String DOUBLE_ESC = ESCAPE + ESCAPE;
55  
56      /** Constant for a duplicated sequence of escaping characters. */
57      private static final String QUAD_ESC = DOUBLE_ESC + DOUBLE_ESC;
58  
59      /** The list delimiter character. */
60      private final char delimiter;
61  
62      /**
63       * Creates a new instance of {@code LegacyListDelimiterHandler} and sets the list delimiter character.
64       *
65       * @param listDelimiter the list delimiter character
66       */
67      public LegacyListDelimiterHandler(final char listDelimiter) {
68          delimiter = listDelimiter;
69      }
70  
71      /**
72       * Gets the list delimiter character.
73       *
74       * @return the list delimiter character
75       */
76      public char getDelimiter() {
77          return delimiter;
78      }
79  
80      /**
81       * {@inheritDoc} This implementation performs delimiter escaping for a single value (which is not part of a list).
82       */
83      @Override
84      public Object escape(final Object value, final ValueTransformer transformer) {
85          return escapeValue(value, false, transformer);
86      }
87  
88      /**
89       * {@inheritDoc} This implementation performs a special encoding of backslashes at the end of a string so that they are
90       * not interpreted as escape character for a following list delimiter.
91       */
92      @Override
93      public Object escapeList(final List<?> values, final ValueTransformer transformer) {
94          if (!values.isEmpty()) {
95              final Iterator<?> it = values.iterator();
96              String lastValue = escapeValue(it.next(), true, transformer);
97              final StringBuilder buf = new StringBuilder(lastValue);
98              while (it.hasNext()) {
99                  // if the last value ended with an escape character, it has
100                 // to be escaped itself; otherwise the list delimiter will
101                 // be escaped
102                 if (lastValue.endsWith(ESCAPE) && countTrailingBS(lastValue) / 2 % 2 != 0) {
103                     buf.append(ESCAPE).append(ESCAPE);
104                 }
105                 buf.append(getDelimiter());
106                 lastValue = escapeValue(it.next(), true, transformer);
107                 buf.append(lastValue);
108             }
109             return buf.toString();
110         }
111         return null;
112     }
113 
114     /**
115      * {@inheritDoc} This implementation simulates the old splitting algorithm. The string is split at the delimiter
116      * character if it is not escaped. If the delimiter character is not found, the input is returned unchanged.
117      */
118     @Override
119     protected Collection<String> splitString(final String s, final boolean trim) {
120         if (s.indexOf(getDelimiter()) < 0) {
121             return Collections.singleton(s);
122         }
123 
124         final List<String> list = new ArrayList<>();
125 
126         StringBuilder token = new StringBuilder();
127         int begin = 0;
128         boolean inEscape = false;
129         final char esc = ESCAPE.charAt(0);
130 
131         while (begin < s.length()) {
132             final char c = s.charAt(begin);
133             if (inEscape) {
134                 // last character was the escape marker
135                 // can current character be escaped?
136                 if (c != getDelimiter() && c != esc) {
137                     // no, also add escape character
138                     token.append(esc);
139                 }
140                 token.append(c);
141                 inEscape = false;
142             } else if (c == getDelimiter()) {
143                 // found a list delimiter -> add token and
144                 // resetDefaultFileSystem buffer
145                 String t = token.toString();
146                 if (trim) {
147                     t = t.trim();
148                 }
149                 list.add(t);
150                 token = new StringBuilder();
151             } else if (c == esc) {
152                 // eventually escape next character
153                 inEscape = true;
154             } else {
155                 token.append(c);
156             }
157 
158             begin++;
159         }
160 
161         // Trailing delimiter?
162         if (inEscape) {
163             token.append(esc);
164         }
165         // Add last token
166         String t = token.toString();
167         if (trim) {
168             t = t.trim();
169         }
170         list.add(t);
171 
172         return list;
173     }
174 
175     /**
176      * {@inheritDoc} This is just a dummy implementation. It is never called.
177      */
178     @Override
179     protected String escapeString(final String s) {
180         return null;
181     }
182 
183     /**
184      * Performs the escaping of backslashes in the specified properties value. Because a double backslash is used to escape
185      * the escape character of a list delimiter, double backslashes also have to be escaped if the property is part of a
186      * (single line) list. In addition, because the output is written into a properties file, each occurrence of a backslash
187      * again has to be doubled. This method is called by {@code escapeValue()}.
188      *
189      * @param value the value to be escaped
190      * @param inList a flag whether the value is part of a list
191      * @return the value with escaped backslashes as string
192      */
193     protected String escapeBackslashs(final Object value, final boolean inList) {
194         String strValue = String.valueOf(value);
195 
196         if (inList && strValue.contains(DOUBLE_ESC)) {
197             strValue = StringUtils.replace(strValue, DOUBLE_ESC, QUAD_ESC);
198         }
199 
200         return strValue;
201     }
202 
203     /**
204      * Escapes the given property value. This method is called on saving the configuration for each property value. It
205      * ensures a correct handling of backslash characters and also takes care that list delimiter characters in the value
206      * are escaped.
207      *
208      * @param value the property value
209      * @param inList a flag whether the value is part of a list
210      * @param transformer the {@code ValueTransformer}
211      * @return the escaped property value
212      */
213     protected String escapeValue(final Object value, final boolean inList, final ValueTransformer transformer) {
214         String escapedValue = String.valueOf(transformer.transformValue(escapeBackslashs(value, inList)));
215         if (getDelimiter() != 0) {
216             escapedValue = StringUtils.replace(escapedValue, String.valueOf(getDelimiter()), ESCAPE + getDelimiter());
217         }
218         return escapedValue;
219     }
220 
221     /**
222      * Returns the number of trailing backslashes. This is sometimes needed for the correct handling of escape characters.
223      *
224      * @param line the string to investigate
225      * @return the number of trailing backslashes
226      */
227     private static int countTrailingBS(final String line) {
228         int bsCount = 0;
229         for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--) {
230             bsCount++;
231         }
232 
233         return bsCount;
234     }
235 }