Summary

Clarify the effect of System.setProperty() to the value of java.locale.providers system property.

Problem

The current wording is misleading, as it suggests that the provider loading order will never be changed by System.setProperty() call. It depends on when the class LocaleServiceProvider is initialized. For example, if a logger is installed, the class is initialized before the control reaches to application's main() method. In that case, calling System.setProperty() will have no effect.

Solution

Clarify the wording in the class description. Since some applications may already depend on the existing behavior, modifying the implementation to the existing spec may break those applications, which should be avoided.

Specification

Change the sentences in the class description of java.util.spi.LocaleServiceProvider class as:

@@ -115,9 +115,9 @@ import java.util.Locale;
  * The search order of locale sensitive services can
  * be configured by using the {@systemProperty java.locale.providers} system property.
  * This system property declares the user's preferred order for looking up
- * the locale sensitive services separated by a comma. It is only read at
- * the Java runtime startup, so the later call to System.setProperty() won't
- * affect the order.
+ * the locale sensitive services separated by a comma. As this property value is
+ * read and cached only at the initialization of this class, users should specify the
+ * property on the java launcher command line. Setting it at runtime with
+ * {@link System#setProperty(String, String)} is discouraged and it may not affect
+ * the order.
  * <p>
  * Java Runtime Environment provides the following four locale providers:
  * <ul>