Bug ID: JDK-8204235 Make some standard system properties effectively read only

Type: CSR
Component: core-libs
Sub-Component: java.lang

Priority: P3
Status: Closed
Resolution: Approved
Fix Versions: 11

Submitted: 2018-06-01
Updated: 2018-06-26
Resolved: 2018-06-26

Summary
-------

Standard system properties should not be modified after system initialization; behavior that depends on those properties is unpredictable if they are modified.
For example, `java.home`, `user.home`, `user.dir`, and `user.name` should be read-only.

Problem
-------

Changing standard system properties after initialization can unpredictably affect the behavior of the java runtime and lead to bug reports and maintenance issues.
Issues have been noted for `java.home`, `user.home`, `user.dir`, and `user.name`.

The specification for individual system properties varies, the behavior of some properties is specific about when the property is used and when it is cached, in other cases, it is unspecified. Developers may have dependencies on the current implementation and behavior.

The System property API does not have any provision to reject or prevent changing system properties except for the `SecurityManager `checkPropertyAccess` method.
Typically, the SecurityManager is not used and there is no protection against changing selected properties. A broader change is needed but raises compatibility concerns and is beyond the scope of this change.

There is no change to the ability to set properties on the command line or from the environment
before the runtime is initialized.

Solution
--------

A short term fix is to cache the system property values of essential properties and use the internally consistent and stable values.

To draw attention to the broader issue a note is added to `java.lang.System` and a release note added to describe the specific properties values being cached.

Specification
-------------

Add an apiNote to the `java.lang.System.getProperties` method.

```
Changing a standard system property may have unpredictable results unless otherwise specified.
Property values may be cached during initialization or on first use.
Setting a standard property after initialization using getProperties(),
setProperties(Properties), setProperty(String, String), or
clearProperty(String) may not have the desired effect.
```

Add an apiNote to `System` methods `setProperties`, `getProperty`, `setProperty`, and `clearProperty`:
```
Changing a standard system property may have unpredictable results unless otherwise specified.
See getProperties() for details.
```

Moving revised change to Approved.
26-06-2018
The @ implNote about `java.home`, `user.home`, `user.dir`, and `user.name` is not intended to be normative and is removed from the @ implNote.
26-06-2018
The intended semantics of the statement "The values of java.home, user.home, user.dir, and user.name properties are cached during initialization." in this CSR are unclear to me. This text is not being proposed as normative text for all implementations of Java SE 11. To do so, the text could either appear as normal text or inside a implSpec section. Since all the methods in java.lang.System are static, many of the usual uses of implSpec and the like do not apply since there is only one implementation and there is not a need to distinguish between a method's general contract and the contract of a particular implementation, meaning a particular implementation that could be overridden in a subtype. As phrased, the statement does not limit its scope to any identified subset of JDK 11 implementation, from which a reader could reasonably infer that all implementations must behave this way. If that is the intention, an implSpec tag or no tag is more appropriate.
23-06-2018
This current round of changes are intended to highlight the implementation dependencies of properties and provide an early warning for future changes. A future more comprehensive update to properties and APIs will be a more appropriate time to define the normative behavior.
22-06-2018
If we want to require the three properties in question be cached, then I think normative text to for all implementation is a better option (implSpec rather than implNote or just normative text) with the context that an implementation may cache other property values.
22-06-2018
Roger suggestion in the last note looks reasonable to me. I would worry about putting "reference implementation in this implNote could be confusing to readers.
19-06-2018
Any text in the @implNote implicitly applies to the OpenJDK implementation so it should not be necessary to mention "this" or "reference" to mean a particular implementation. How about a neutral description: * During system initialization the {@code java.home}, {@code user.home}, * {@code user.dir}, and {@code user.name} properties are cached.
19-06-2018
While a new section could be added at the top of the class to discuss properties, putting the explanation into one of the get methods would be fine too. The term "reference implementation" is basically used in the JCP sense. The proposed implementation note "The values of java.home, user.home, user.dir, and user.name properties are cached during initialization." leaves implicit the JDK implementations for which this statements holds. It is not mandatory that all possible JDK 11 implementations behave in this way. The JDK implementations derived from the OpenJDK sources will behave this way, at least for JDK 11 GA. We don't have a term for that set of JDK implementations, but it will be a true statement for the reference implementation.
19-06-2018
There is no context in the System class javadoc to add this note too. The root of information about properties is the getProperties() method. Would it be suitable to leave the full text in getProperties and refer to that method from the other xxxProperty methods. I assume the suggestion to use 'reference implementation' is not the JCP's definition of reference implementation.
19-06-2018
Rather than the same text repeated six times in the same class, I'd prefer to see a general note included in the class-level javadoc and then references in the @apiNotes to the general note. For the text 680 * @implNote 681 * The values of {@code java.home}, {@code user.home}, {@code user.dir}, 682 * and {@code user.name} properties are cached during initialization. per recent discussions elsewhere (http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-June/053766.html), I think wording like "The reference implementation caches ... during initialization." is better than the current wording.
18-06-2018
Removed "internally" from the text of the apiNote and implNote.
18-06-2018
I think the word "internally" should be dropped from the proposed apiNote as it leads to several questions. Otherwise looks good.
16-06-2018