Author: oheger Date: Fri Oct 5 20:05:16 2018 New Revision: 1842977 URL: http://svn.apache.org/viewvc?rev=1842977&view=rev Log: [CONFIGURATION-715/716] Documentation improvements.
Thanks to Patrick Schmidt for the patch. Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/PropertiesConfiguration.java commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_properties.xml Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/PropertiesConfiguration.java URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/PropertiesConfiguration.java?rev=1842977&r1=1842976&r2=1842977&view=diff ============================================================================== --- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/PropertiesConfiguration.java (original) +++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/PropertiesConfiguration.java Fri Oct 5 20:05:16 2018 @@ -1353,18 +1353,25 @@ public class PropertiesConfiguration ext /** * An alternative {@link IOFactory} that tries to mimic the behavior of - * {@link java.util.Properties} (Jup) more closely. + * {@link java.util.Properties} (Jup) more closely. The goal is to allow both of + * them be used interchangeably when reading and writing properties files + * without losing or changing information. * <p> * It also has the option to <em>not</em> use Unicode escapes. When using UTF-8 * encoding (which is e.g. the new default for resource bundle properties files * since Java 9), Unicode escapes are no longer required and avoiding them makes * properties files more readable with regular text editors. + * <p> + * Some of the ways this implementation differs from {@link DefaultIOFactory}: * <ul> * <li>Trailing whitespace will not be trimmed from each line.</li> * <li>Unknown escape sequences will have their backslash removed.</li> * <li>{@code \b} is not a recognized escape sequence.</li> * <li>Leading spaces in property values are preserved by escaping them.</li> - * <li></li> + * <li>All natural lines (i.e. in the file) of a logical property line will have + * their leading whitespace trimmed.</li> + * <li>Natural lines that look like comment lines within a logical line are not + * treated as such; they're part of the property value.</li> * </ul> * * @since 2.4 Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_properties.xml URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_properties.xml?rev=1842977&r1=1842976&r2=1842977&view=diff ============================================================================== --- commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_properties.xml (original) +++ commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_properties.xml Fri Oct 5 20:05:16 2018 @@ -389,12 +389,26 @@ config.dirs = \\\\share2 properties writer. A default implementation called <code>DefaultIOFactory</code> is also available and is used by <code>PropertiesConfiguration</code> when no specific - <code>IOFactory</code> is set. To make this discussion more concrete - we provide an example of how to inject a custom properties reader. The - use case is that we have to load a properties file that contains keys - with whitespace, which is not supported by - <code>PropertiesConfiguration</code> per default. A fragment from such - a properties file could look as follows: + <code>IOFactory</code> is set.<br/> + The original goal of <code>PropertiesConfiguration</code> wasn't to be + strictly compatible with the exact file format defined in + <code>java.util.Properties</code> (JUP). However, in cases where this + compatibility is required, the alternative <code>JupIOFactory</code> can + be used, as it aims to mimic the exact behavior of <code>JUP</code>. The + main differences concern the handling of leading and trailing whitespace + and the handling of escape sequences. <code>JupIOFactory</code> can also + be configured to avoid Unicode escape sequences (like \u00DF) when + the used encoding already supports all characters natively. E.g. UTF-8 + is the new default encoding for resource bundle properties files since + Java 9, so Unicode escapes are not required anymore and not using them + can make properties files much more readable in regular text editors. + </p> + <p> + To make this discussion more concrete we provide an example of how to + inject a custom properties reader. The use case is that we have to load + a properties file that contains keys with whitespace, which is not + supported by <code>PropertiesConfiguration</code> per default. A + fragment from such a properties file could look as follows: </p> <source><![CDATA[ Background Color = #800080