Proposal: JDK-8231640 - (prop) Canonical property storage

[Jaikiran Pai]

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