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><