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 SecurityManagercheckPropertyAccess` 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.