8353118: Deprecate the use of java.locale.useOldISOCodes system property

src/java.base/share/classes/java/util/Locale.java

@@ -418,8 +418,8 @@
  * <p>The filtering operation returns all matching language tags. It is defined
  * in RFC 4647 as follows:
  * "In filtering, each language range represents the least specific language
- * tag (that is, the language tag with fewest number of subtags) that is an
- * acceptable match. All of the language tags in the matching set of tags will
+ * tag (that is, the language tag with the fewest number of subtags) that is an
+ * acceptable match. All the language tags in the matching set of tags will
  * have an equal or greater number of subtags than the language range. Every
  * non-wildcard subtag in the language range will appear in every one of the
  * matching language tags."
@@ -541,9 +541,12 @@
  * {@code true}, those three current language codes are mapped to their
  * backward compatible forms. The property is only read at Java runtime
  * startup and subsequent calls to {@code System.setProperty()} will
- * have no effect.
+ * have no effect. <b>As of Java SE 25, the use of the
+ * {@code java.locale.useOldISOCodes} system property is deprecated.
+ * This backwards compatible behavior will be removed in a future release
+ * of the JDK.</b>
  *
- * <p>The APIs added in 1.7 map between the old and new language codes,
+ * <p>The APIs added in Java SE 7 map between the old and new language codes,
  * maintaining the mapped codes internal to Locale (so that
  * {@code getLanguage} and {@code toString} reflect the mapped
  * code, which depends on the {@code java.locale.useOldISOCodes} system

src/java.base/share/classes/sun/util/locale/BaseLocale.java

@@ -106,6 +106,12 @@ public final class BaseLocale {
      */
     private static final boolean OLD_ISO_CODES = StaticProperty.javaLocaleUseOldISOCodes()
             .equalsIgnoreCase("true");
+    static {
+        if (OLD_ISO_CODES) {
+            System.err.println("WARNING: The use of the system property \"java.locale.useOldISOCodes\"" +
+                " is deprecated. It will be removed in a future release of the JDK.");
+        }
+    }
 
     private BaseLocale(String language, String script, String region, String variant) {
         this.language = language;

test/jdk/java/util/Locale/UseOldISOCodesTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,8 +23,8 @@
 
 /*
  * @test
- * @bug 8295232
- * @summary Ensures java.locale.useOldISOCodes is statically initialized
+ * @bug 8295232 8353118
+ * @summary Tests for the "java.locale.useOldISOCodes" system property
  * @library /test/lib
  * @run junit UseOldISOCodesTest
  */
@@ -38,20 +38,21 @@
 
 public class UseOldISOCodesTest {
 
-    // Ensure java.locale.useOldISOCodes is only interpreted at runtime startup
     @Test
-    public void staticInitializationTest() throws Exception {
-        ProcessTools.executeTestJava("-Djava.locale.useOldISOCodes=true", "UseOldISOCodesTest$Runner")
+    public void testUseOldISOCodes() throws Exception {
+        var oa = ProcessTools.executeTestJava("-Djava.locale.useOldISOCodes=true", "UseOldISOCodesTest$Runner")
                 .outputTo(System.out)
-                .errorTo(System.err)
-                .shouldHaveExitValue(0);
+                .errorTo(System.err);
+        oa.shouldHaveExitValue(0);
+        oa.stderrShouldMatch("WARNING: The use of the system property \"java.locale.useOldISOCodes\" is deprecated. It will be removed in a future release of the JDK.");
     }
 
     static class Runner {
         private static final String obsoleteCode = "iw";
         private static final String newCode = "he";
 
         public static void main(String[] args) {
+            // Ensure java.locale.useOldISOCodes is only interpreted at runtime startup
             // Should have no effect
             System.setProperty("java.locale.useOldISOCodes", "false");
             Locale locale = Locale.of(newCode);