Name: nt126004 Date: 10/08/2002


FULL PRODUCT VERSION :
N/A (Documentation Bug)

N/A (Documentation Bug)

A DESCRIPTION OF THE PROBLEM :
The documentation of the load and store methods on
java.util.Properties is incorrect. It may be found at:
http://java.sun.com/j2se/1.4/docs/api/java/util/Properties.html

In java.util.Properties#load:

As specified, only termination characters (=, :, and
whitespace) are unescaped in the key. This omits \,
#, !, and the specification of what is done with unrecognized
escapes, and furthermore is inconsistent with the
implementation. (The implementation does proper unescaping;
that is, a backslash followed by a recognized special
character is substituted as appropriate, otherwise the
backslash is discarded and the escaped character left as is.)

Similarly, in the element string only \t, \r, \n, \\, \",
\', \(space), and \uxxxx are specified to be recognized.
This omits \f, and again is inconsistent with both common
practice and the implementation.

Additionally, the section contains the sentence, 'As an
example, each of the following four lines specifies the key
"Truth" and the associated element value "Beauty":'; which
is then followed by only three examples.

In java.util.Properties#store:

The JavaDoc here notes that non-space whitespace in the
element string (again omitting \f) is escaped, ignoring that
whitespace and spaces in the key string must be escaped as well.


Looking over the many previous bugs filed against
Properties, it appears that the problem is that many fixes
have been made to the class, but nobody has updated the
JavaDoc at the same time.


REPRODUCIBILITY :
This bug can be reproduced always.

CUSTOMER WORKAROUND :
Explain to employee implementing properties file parser in
another language the way the parser ought to behave, instead
of pointing them at the Properties JavaDoc and then being
terribly confused.
(Review ID: 164563)
======================================================================