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