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

[Jaikiran Pai]

On 25/08/21 6:21 pm, Alan Bateman wrote:
> On 24/08/2021 15:07, Jaikiran Pai wrote:
>> 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.
>
> Another possibility is to add an overload of store that adds a 
> java.time.Instant argument for the timestamp. It could be specified as 
> Instant.EPOCH where reproducibility is required.
>
> Magnus brings up the possibility of specifying that the store methods 
> look for SOURCE_DATE_EPOCH. As it happens, someone tried that [1]. 
> With a spec change and the correct implementation then it should be 
> feasible option to explore.

Introducing an overloaded "store" which takes the timestamp or 
implicitly using the SOURCE_DATE_EPOCH environment variable would mean 
that the Properties.store(...) APIs will continue to always write out a 
Date representation into the outputstream. That effectively means that 
there will continue to be no way to disable writing out a (date) 
comment. More specifically, even if a user doesn't explicitly specify a 
comment, we would end up writing a default (date) comment. Do we want 
that? Or while we are doing these changes, should we introduce this 
ability of disabling writing out these date comments by default? That, 
IMO, can only be done by introducing new APIs instead of trying to 
slightly change the spec and the implementation of the current "store" 
APIs. After all, if any callers do want a date (and a reproducible one 
at that), they could always do so by passing that as a value for the 
"comment" parameter of these (new) "storeXXX" APIs.

>
> We touched on the ordering issue in the jdk-dev discussion in 2019. I 
> think that can be changed to write in sorted key order without a spec 
> change, although it could be a useful property to specify.

I think, based on the discussion/inputs so far, there's clarity on this 
part that changing the current implementation of "store" to write out 
the property keys in a specific order would be a good thing, 
irrespective of whether or not we introduce new APIs to deal with the 
date comment aspect. Daniel had an interesting point of 
logging.properties file and the order that would need to be maintained 
for those, but like he noted in that same reply, I don't think that's a 
use case to consider for the "store" APIs, since they never previously 
supported/guaranteed that use case.

-Jaikiran