The java.util.Properties class allows the properties to be written out
to a stream or through a writer. In its current form, the specification
of these APIs state that a comment comprising of the current date is
always written out. The spec doesn't make any guarantees about the order
of the properties when they are written out.
There have been requests asking to make these APIs more deterministic.
These requests, from what I have seen, mainly ask for:
- A way to disable writing out the date comment
- A way to write out the properties in a deterministic and reproducible way
There have been discussions in the mailing list in the past which have
been captured in JDK-8231640[1]. In these discussions, there has been an
inclination to not touch the current existing API implementations and
instead introduce new API(s) to achieve the proposed use cases.
Before starting off with an implementation, I wanted to try and get some
inputs on what the new API(s) would look like and what the scope of such
a work should be.
Right now, the Properties class has 2 "store" APIs:
public void store(Writer writer, String comments) throws IOException
public void store(OutputStream out, String comments) throws IOException
For the sake of this discussion we won't be talking about the "save"
API, in that same class, which has been deprecated.
As part of this enhancement, one of the proposed API name is
"storeCanonical". As a start, I plan to use this name for the new API.
Is there any different suggestion for the name?
As for the API signature, I plan to introduce 2 new APIs:
public void storeCanonical(Writer writer, String comments) throws
IOException
public void storeCanonical(OutputStream out, String comments)
throws IOException
to match what the "store" variants currently provide. The first
difference between these "storeCanonical" and the "store" will be the
trivial part where these new "storeCanonical" implementations will no
longer write out the date comment. Users are allowed to pass optional
comments to these new APIs. If any comment is passed to these APIs,
these will continue to be written out first, before the actual
properties are written out.
Speaking of optional comments, should the APIs accept an instance of
java.util.Optional for the comments parameter. Perhaps:
public void storeCanonical(Writer writer, Optional<String>
comments) throws IOException
public void storeCanonical(OutputStream out, Optional<String>
comments) throws IOException
Coming to the part where we write out the properties, these APIs will
write out the properties in the lexicographical order of the property
keys. An additional enhancement perhaps could be to allow users to pass
in an optional java.util.Comparator instance to provide for application
specific ordering of the property keys while being written out by these
APIs. I am not too sure if we should introduce that. Any inputs? If we
do introduce it, we would end up with 4 new APIs:
public void storeCanonical(Writer writer, Optional<String>
comments) throws IOException
public void storeCanonical(OutputStream out, Optional<String>
comments) throws IOException
public void storeCanonical(Writer writer, Optional<String>
comments, Comparator<String> keyOrderer) throws IOException
public void storeCanonical(OutputStream out, Optional<String>
comments, Comparator<String> keyOrderer) throws IOException
Is that worth it?
Finally, the other semantics, like the property key value separators,
how/where newlines are inserted, what character encoding is used etc...
will continue to match with the current semantics of the "store" APIs.
[1] https://bugs.openjdk.java.net/browse/JDK-8231640
-Jaikiran
