8282819: Deprecate Locale class constructors

Reviewed-by: lancea, rriggs

Author: naotoj

src/demo/share/jfc/CodePointIM/com/sun/inputmethods/internal/codepointim/CodePointInputMethodDescriptor.java

@@ -75,7 +75,7 @@ public InputMethod createInputMethod() throws Exception {
      */
     public Locale[] getAvailableLocales() {
         Locale[] locales = {
-            new Locale("", "", ""), };
+            Locale.ROOT, };
         return locales;
     }
 

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

@@ -230,46 +230,30 @@
  * implementations in a Java Runtime Environment might not support any
  * particular Unicode locale attributes or key/type pairs.
  *
- * <h3>Creating a Locale</h3>
+ * <h3><a id="ObtainingLocale">Obtaining a Locale</a></h3>
  *
- * <p>There are several different ways to create a {@code Locale}
+ * <p>There are several ways to obtain a {@code Locale}
  * object.
  *
  * <h4>Builder</h4>
  *
  * <p>Using {@link Builder} you can construct a {@code Locale} object
  * that conforms to BCP 47 syntax.
  *
- * <h4>Constructors</h4>
- *
- * <p>The {@code Locale} class provides three constructors:
- * <blockquote>
- * <pre>
- *     {@link #Locale(String language)}
- *     {@link #Locale(String language, String country)}
- *     {@link #Locale(String language, String country, String variant)}
- * </pre>
- * </blockquote>
- * These constructors allow you to create a {@code Locale} object
- * with language, country and variant, but you cannot specify
- * script or extensions.
- *
  * <h4>Factory Methods</h4>
  *
- * <p>The method {@link #forLanguageTag} creates a {@code Locale}
- * object for a well-formed BCP 47 language tag.
+ * <p>The method {@link #forLanguageTag} obtains a {@code Locale}
+ * object for a well-formed BCP 47 language tag. The method
+ * {@link #of(String, String, String)} and its overloads obtain a
+ * {@code Locale} object from given {@code language}, {@code country},
+ * and/or {@code variant} defined above.
  *
  * <h4>Locale Constants</h4>
  *
  * <p>The {@code Locale} class provides a number of convenient constants
- * that you can use to create {@code Locale} objects for commonly used
- * locales. For example, the following creates a {@code Locale} object
- * for the United States:
- * <blockquote>
- * <pre>
- *     Locale.US
- * </pre>
- * </blockquote>
+ * that you can use to obtain {@code Locale} objects for commonly used
+ * locales. For example, {@code Locale.US} is the {@code Locale} object
+ * for the United States.
  *
  * <h3><a id="LocaleMatching">Locale Matching</a></h3>
  *
@@ -344,7 +328,7 @@
  *
  * <h3>Use of Locale</h3>
  *
- * <p>Once you've created a {@code Locale} you can query it for information
+ * <p>Once you've obtained a {@code Locale} you can query it for information
  * about itself. Use {@code getCountry} to get the country (or region)
  * code and {@code getLanguage} to get the language code.
  * You can use {@code getDisplayCountry} to get the
@@ -387,7 +371,7 @@
  *
  * <h3>Compatibility</h3>
  *
- * <p>In order to maintain compatibility with existing usage, Locale's
+ * <p>In order to maintain compatibility, Locale's
  * constructors retain their behavior prior to the Java Runtime
  * Environment version 1.7.  The same is largely true for the
  * {@code toString} method. Thus Locale objects can continue to
@@ -741,6 +725,9 @@ private Locale(BaseLocale baseLocale, LocaleExtensions extensions) {
      * see <a href="#special_cases_constructor">Special Cases</a> for more information.
      * </ul>
      *
+     * @deprecated Locale constructors have been deprecated. See <a href ="#ObtainingLocale">
+     * Obtaining a Locale</a> for other options.
+     *
      * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
      * up to 8 characters in length.  See the {@code Locale} class description about
      * valid language values.
@@ -750,6 +737,7 @@ private Locale(BaseLocale baseLocale, LocaleExtensions extensions) {
      * See the {@code Locale} class description for the details.
      * @throws    NullPointerException thrown if any argument is null.
      */
+    @Deprecated(since="19")
     public Locale(String language, String country, String variant) {
         if (language == null || country == null || variant == null) {
             throw new NullPointerException();
@@ -771,13 +759,17 @@ public Locale(String language, String country, String variant) {
      * any syntactic checks on the input.
      * </ul>
      *
+     * @deprecated Locale constructors have been deprecated. See <a href="#ObtainingLocale">
+     * Obtaining a Locale</a> for other options.
+     *
      * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
      * up to 8 characters in length.  See the {@code Locale} class description about
      * valid language values.
      * @param country An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code.
      * See the {@code Locale} class description about valid country values.
      * @throws    NullPointerException thrown if either argument is null.
      */
+    @Deprecated(since="19")
     public Locale(String language, String country) {
         this(language, country, "");
     }
@@ -794,16 +786,96 @@ public Locale(String language, String country) {
      * any syntactic checks on the input.
      * </ul>
      *
+     * @deprecated Locale constructors have been deprecated. See <a href="#ObtainingLocale">
+     * Obtaining a Locale</a> for other options.
+     *
      * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
      * up to 8 characters in length.  See the {@code Locale} class description about
      * valid language values.
      * @throws    NullPointerException thrown if argument is null.
      * @since 1.4
      */
+    @Deprecated(since="19")
     public Locale(String language) {
         this(language, "", "");
     }
 
+    /**
+     * Obtains a locale from language, country and variant.
+     * This method normalizes the language value to lowercase and
+     * the country value to uppercase.
+     * @implNote
+     * <ul>
+     * <li>This method does not make any syntactic checks on the input.
+     * Use {@link Locale.Builder} for full syntactic checks with BCP47.
+     * <li>The two cases ("ja", "JP", "JP") and ("th", "TH", "TH") are handled specially,
+     * see <a href="#special_cases_constructor">Special Cases</a> for more information.
+     * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
+     * their current forms. See <a href="#legacy_language_codes">Legacy language
+     * codes</a> for more information.
+     * </ul>
+     *
+     * @param language A language code. See the {@code Locale} class description of
+     * <a href="#def_language">language</a> values.
+     * @param country A country code. See the {@code Locale} class description of
+     * <a href="#def_region">country</a> values.
+     * @param variant Any arbitrary value used to indicate a variation of a {@code Locale}.
+     * See the {@code Locale} class description of <a href="#def_variant">variant</a> values.
+     * @throws    NullPointerException thrown if any argument is null.
+     * @return A {@code Locale} object
+     * @since 19
+     */
+    public static Locale of(String language, String country, String variant) {
+        return getInstance(language, "", country, variant, null);
+    }
+
+    /**
+     * Obtains a locale from language and country.
+     * This method normalizes the language value to lowercase and
+     * the country value to uppercase.
+     * @implNote
+     * <ul>
+     * <li>This method does not make any syntactic checks on the input.
+     * Use {@link Locale.Builder} for full syntactic checks with BCP47.
+     * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
+     * their current forms. See <a href="#legacy_language_codes">Legacy language
+     * codes</a> for more information.
+     * </ul>
+     *
+     * @param language A language code. See the {@code Locale} class description of
+     * <a href="#def_language">language</a> values.
+     * @param country A country code. See the {@code Locale} class description of
+     * <a href="#def_region">country</a> values.
+     * @throws    NullPointerException thrown if either argument is null.
+     * @return A {@code Locale} object
+     * @since 19
+     */
+    public static Locale of(String language, String country) {
+        return getInstance(language, "", country, "", null);
+    }
+
+    /**
+     * Obtains a locale from a language code.
+     * This method normalizes the language value to lowercase.
+     * @implNote
+     * <ul>
+     * <li>This method does not make any syntactic checks on the input.
+     * Use {@link Locale.Builder} for full syntactic checks with BCP47.
+     * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
+     * their current forms. See <a href="#legacy_language_codes">Legacy language
+     * codes</a> for more information.
+     * </ul>
+     *
+     * @param language A language code. See the {@code Locale} class description of
+     * <a href="#def_language">language</a> values.
+     * @throws    NullPointerException thrown if argument is null.
+     * @return A {@code Locale} object
+     * @since 19
+     */
+    public static Locale of(String language) {
+        return getInstance(language, "", "", "", null);
+    }
+
     /**
      * Returns a {@code Locale} constructed from the given
      * {@code language}, {@code country} and
@@ -1138,14 +1210,14 @@ public static Locale[] getAvailableLocales() {
 
     /**
      * Returns a list of all 2-letter country codes defined in ISO 3166.
-     * Can be used to create Locales.
+     * Can be used to obtain Locales.
      * This method is equivalent to {@link #getISOCountries(Locale.IsoCountryCode type)}
      * with {@code type}  {@link IsoCountryCode#PART1_ALPHA2}.
      * <p>
      * <b>Note:</b> The {@code Locale} class also supports other codes for
      * country (region), such as 3-letter numeric UN M.49 area codes.
      * Therefore, the list returned by this method does not contain ALL valid
-     * codes that can be used to create Locales.
+     * codes that can be used to obtain Locales.
      * <p>
      * Note that this method does not return obsolete 2-letter country codes.
      * ISO3166-3 codes which designate country codes for those obsolete codes,
@@ -1178,7 +1250,7 @@ public static Set<String> getISOCountries(IsoCountryCode type) {
 
     /**
      * Returns a list of all 2-letter language codes defined in ISO 639.
-     * Can be used to create Locales.
+     * Can be used to obtain Locales.
      * <p>
      * <b>Note:</b>
      * <ul>
@@ -1187,7 +1259,7 @@ public static Set<String> getISOCountries(IsoCountryCode type) {
      * languages whose codes have changed.
      * <li>The {@code Locale} class also supports language codes up to
      * 8 characters in length.  Therefore, the list returned by this method does
-     * not contain ALL valid codes that can be used to create Locales.
+     * not contain ALL valid codes that can be used to obtain Locales.
      * </ul>
      *
      * @return An array of ISO 639 two-letter language codes.
@@ -1520,12 +1592,12 @@ public final String toString() {
      * "NY", representing Norwegian Nynorsk (Norway), is converted
      * to a language tag "nn-NO".</li></ul>
      *
-     * <p><b>Note:</b> Although the language tag created by this
+     * <p><b>Note:</b> Although the language tag obtained by this
      * method is well-formed (satisfies the syntax requirements
      * defined by the IETF BCP 47 specification), it is not
      * necessarily a valid BCP 47 language tag.  For example,
      * <pre>
-     *   new Locale("xx", "YY").toLanguageTag();</pre>
+     *   Locale.forLanguageTag("xx-YY").toLanguageTag();</pre>
      *
      * will return "xx-YY", but the language subtag "xx" and the
      * region subtag "YY" are invalid because they are not registered
@@ -2510,7 +2582,7 @@ public enum Category {
      * from values configured by the setters.  Unlike the {@code Locale}
      * constructors, the {@code Builder} checks if a value configured by a
      * setter satisfies the syntax requirements defined by the {@code Locale}
-     * class.  A {@code Locale} object created by a {@code Builder} is
+     * class.  A {@code Locale} object obtained from a {@code Builder} is
      * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
      * without losing information.
      *
@@ -2521,11 +2593,11 @@ public enum Category {
      * {@code IllformedLocaleException} for a variant that does not satisfy
      * this restriction. If it is necessary to support such a variant, use a
      * Locale constructor.  However, keep in mind that a {@code Locale}
-     * object created this way might lose the variant information when
+     * object obtained this way might lose the variant information when
      * transformed to a BCP 47 language tag.
      *
-     * <p>The following example shows how to create a {@code Locale} object
-     * with the {@code Builder}.
+     * <p>The following example shows how to obtain a {@code Locale} object
+     * using a {@code Builder}.
      * <blockquote>
      * <pre>
      *     Locale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
@@ -2658,7 +2730,7 @@ public Builder setScript(String script) {
          * <p>The typical region value is a two-letter ISO 3166 code or a
          * three-digit UN M.49 area code.
          *
-         * <p>The country value in the {@code Locale} created by the
+         * <p>The country value in the {@code Locale} obtained from a
          * {@code Builder} is always normalized to upper case.
          *
          * @param region the region
@@ -2831,7 +2903,7 @@ public Builder clearExtensions() {
         }
 
         /**
-         * Returns an instance of {@code Locale} created from the fields set
+         * Returns an instance of {@code Locale} obtained from the fields set
          * on this builder.
          *
          * <p>This applies the conversions listed in {@link Locale#forLanguageTag}

src/java.base/share/classes/sun/util/locale/provider/JRELocaleConstants.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2022, 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
@@ -35,10 +35,10 @@
  * @author Masayoshi Okutsu
  */
 public class JRELocaleConstants {
-    public static final Locale JA_JP_JP = new Locale("ja", "JP", "JP");
-    public static final Locale NO_NO_NY = new Locale("no", "NO", "NY");
-    public static final Locale TH_TH    = new Locale("th", "TH");
-    public static final Locale TH_TH_TH = new Locale("th", "TH", "TH");
+    public static final Locale JA_JP_JP = Locale.of("ja", "JP", "JP");
+    public static final Locale NO_NO_NY = Locale.of("no", "NO", "NY");
+    public static final Locale TH_TH    = Locale.of("th", "TH");
+    public static final Locale TH_TH_TH = Locale.of("th", "TH", "TH");
 
     private JRELocaleConstants() {
     }

src/java.base/share/classes/sun/util/locale/provider/LocaleServiceProviderPool.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2022, 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
@@ -369,7 +369,7 @@ static Locale getLookupLocale(Locale locale) {
                         "A locale(" + locale + ") has non-empty extensions, but has illformed fields.");
 
                 // Fallback - script field will be lost.
-                lookupLocale = new Locale(locale.getLanguage(), locale.getCountry(), locale.getVariant());
+                lookupLocale = Locale.of(locale.getLanguage(), locale.getCountry(), locale.getVariant());
             }
         }
         return lookupLocale;

src/java.base/share/classes/sun/util/resources/LocaleData.java

@@ -246,7 +246,7 @@ private static class LocaleDataStrategy implements Bundles.Strategy {
         private static final LocaleDataStrategy INSTANCE = new LocaleDataStrategy();
         // TODO: avoid hard-coded Locales
         private static final Set<Locale> JAVA_BASE_LOCALES
-            = Set.of(Locale.ROOT, Locale.ENGLISH, Locale.US, new Locale("en", "US", "POSIX"));
+            = Set.of(Locale.ROOT, Locale.ENGLISH, Locale.US, Locale.of("en", "US", "POSIX"));
 
         private LocaleDataStrategy() {
         }

src/java.desktop/share/classes/sun/awt/SunToolkit.java

@@ -1181,7 +1181,7 @@ public static Locale getStartupLocale() {
                 variant = AccessController.doPrivileged(
                                 new GetPropertyAction("user.variant", ""));
             }
-            startupLocale = new Locale(language, country, variant);
+            startupLocale = Locale.of(language, country, variant);
         }
         return startupLocale;
     }

src/java.desktop/share/classes/sun/awt/im/ExecutableInputMethodManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2022, 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
@@ -375,7 +375,7 @@ synchronized void changeInputMethod(String choice) {
                     variant = localeString.substring(postIndex + 1);
                 }
             }
-            Locale locale = new Locale(language, country, variant);
+            Locale locale = Locale.of(language, country, variant);
             locator = locator.deriveLocator(locale);
         }
 
@@ -550,8 +550,8 @@ private synchronized void putPreferredInputMethod(InputMethodLocator locator) {
         if (preferredLocale.equals(Locale.KOREA)) {
             preferredLocale = Locale.KOREAN;
         }
-        if (preferredLocale.equals(new Locale("th", "TH"))) {
-            preferredLocale = new Locale("th");
+        if (preferredLocale.equals(Locale.of("th", "TH"))) {
+            preferredLocale = Locale.of("th");
         }
 
         // obtain node
@@ -623,10 +623,10 @@ private Locale getAdvertisedLocale(InputMethodLocator locator, Locale locale) {
                 advertised = Locale.KOREAN;
             }
         } else if (locale.getLanguage().equals("th")) {
-            if (locator.isLocaleAvailable(new Locale("th", "TH"))) {
-                advertised = new Locale("th", "TH");
-            } else if (locator.isLocaleAvailable(new Locale("th"))) {
-                advertised = new Locale("th");
+            if (locator.isLocaleAvailable(Locale.of("th", "TH"))) {
+                advertised = Locale.of("th", "TH");
+            } else if (locator.isLocaleAvailable(Locale.of("th"))) {
+                advertised = Locale.of("th");
             }
         }
 

src/java.desktop/share/classes/sun/font/SunFontManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2022, 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
@@ -3466,7 +3466,7 @@ public Locale run() {
                     String language = System.getProperty("user.language", "en");
                     String country  = System.getProperty("user.country","");
                     String variant  = System.getProperty("user.variant","");
-                    return new Locale(language, country, variant);
+                    return Locale.of(language, country, variant);
                 }
             });
         }

src/java.xml.crypto/share/classes/com/sun/org/apache/xml/internal/security/utils/I18n.java

@@ -160,7 +160,7 @@ public static synchronized void init(String languageCode, String countryCode) {
         I18n.resourceBundle =
             ResourceBundle.getBundle(
                 Constants.exceptionMessagesResourceBundleBase,
-                new Locale(languageCode, countryCode)
+                Locale.of(languageCode, countryCode)
             );
         alreadyInitialized = true;
     }

src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/dom/CollatorFactoryBase.java

@@ -38,7 +38,7 @@ public CollatorFactoryBase() {
     }
 
     public Collator getCollator(String lang, String country) {
-        return Collator.getInstance(new Locale(lang, country));
+        return Collator.getInstance(Locale.of(lang, country));
     }
 
     public Collator getCollator(Locale locale) {

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/jaxp/datatype/XMLGregorianCalendarImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2022, 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
@@ -2425,12 +2425,12 @@ private Locale getDefaultLocale() {
         if (lang != null) {
             if (country != null) {
                 if (variant != null) {
-                    locale = new Locale(lang, country, variant);
+                    locale = Locale.of(lang, country, variant);
                 } else {
-                    locale = new Locale(lang, country);
+                    locale = Locale.of(lang, country);
                 }
             } else {
-                locale = new Locale(lang);
+                locale = Locale.of(lang);
             }
         }
         if (locale == null) {

src/java.xml/share/classes/com/sun/org/apache/xml/internal/utils/LocaleUtility.java

@@ -78,7 +78,7 @@ public static Locale langToLocale(String lang) {
             variant = EMPTY_STRING;
         }
 
-        return new Locale(language, country, variant );
+        return Locale.of(language, country, variant);
     }
 
 

src/java.xml/share/classes/jdk/xml/internal/SecuritySupport.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2022, 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
@@ -275,7 +275,7 @@ public static ResourceBundle getResourceBundle(final String bundle, final Locale
                 return ResourceBundle.getBundle(bundle, locale);
             } catch (MissingResourceException e) {
                 try {
-                    return ResourceBundle.getBundle(bundle, new Locale("en", "US"));
+                    return ResourceBundle.getBundle(bundle, Locale.US);
                 } catch (MissingResourceException e2) {
                     throw new MissingResourceException(
                             "Could not load any resource bundle by " + bundle, bundle, "");

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/plugins/IncludeLocalesPlugin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, 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
@@ -141,9 +141,9 @@ public final class IncludeLocalesPlugin extends AbstractPlugin implements Resour
     private static final String jaJPJPTag = "ja-JP-JP";
     private static final String noNONYTag = "no-NO-NY";
     private static final String thTHTHTag = "th-TH-TH";
-    private static final Locale jaJPJP = new Locale("ja", "JP", "JP");
-    private static final Locale noNONY = new Locale("no", "NO", "NY");
-    private static final Locale thTHTH = new Locale("th", "TH", "TH");
+    private static final Locale jaJPJP = Locale.of("ja", "JP", "JP");
+    private static final Locale noNONY = Locale.of("no", "NO", "NY");
+    private static final Locale thTHTH = Locale.of("th", "TH", "TH");
 
     public IncludeLocalesPlugin() {
         super("include-locales");

test/jdk/java/util/Locale/TestOf.java

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2022, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+/**
+ * @test
+ * @bug 8282819
+ * @summary Unit tests for Locale.of() method. Those tests check the equality
+ *      of obtained objects with ones that are gotten from other means with both
+ *      well-formed and ill-formed arguments. Also checks the possible NPEs
+ *      for error cases.
+ * @run testng TestOf
+ */
+import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertThrows;
+
+import java.util.Locale;
+
+import org.testng.annotations.Test;
+import org.testng.annotations.DataProvider;
+
+@SuppressWarnings("deprecation")
+@Test
+public class TestOf {
+
+    @DataProvider
+    public Object[][] data_1Arg() {
+        return new Object[][]{
+                // well-formed
+                {Locale.ENGLISH, "en"},
+                {Locale.JAPANESE, "ja"},
+
+                // ill-formed
+                {Locale.ROOT, ""},
+                {new Locale("a"), "a"},
+                {new Locale("xxxxxxxxxx"), "xxxxxxxxxx"},
+        };
+    }
+
+    @DataProvider
+    public Object[][] data_2Args() {
+        return new Object[][]{
+                // well-formed
+                {Locale.US, "en", "US"},
+                {Locale.JAPAN, "ja", "JP"},
+
+                // ill-formed
+                {new Locale("", "US"), "", "US"},
+                {new Locale("a", "b"), "a", "b"},
+                {new Locale("xxxxxxxxxx", "yyyyyyyyyy"), "xxxxxxxxxx", "yyyyyyyyyy"},
+        };
+    }
+
+    @DataProvider
+    public Object[][] data_3Args() {
+        return new Object[][]{
+                // well-formed
+                {Locale.forLanguageTag("en-US-POSIX"), "en", "US", "POSIX"},
+                {Locale.forLanguageTag("ja-JP-POSIX"), "ja", "JP", "POSIX"},
+
+                // ill-formed
+                {new Locale("", "", "POSIX"), "", "", "POSIX"},
+                {new Locale("a", "b", "c"), "a", "b", "c"},
+                {new Locale("xxxxxxxxxx", "yyyyyyyyyy", "zzzzzzzzzz"),
+                        "xxxxxxxxxx", "yyyyyyyyyy", "zzzzzzzzzz"},
+                {new Locale("ja", "JP", "JP"), "ja", "JP", "JP"},
+                {new Locale("th", "TH", "TH"), "th", "TH", "TH"},
+                {new Locale("no", "NO", "NY"), "no", "NO", "NY"},
+        };
+    }
+
+    @Test (dataProvider = "data_1Arg")
+    public void test_1Arg(Locale expected, String lang) {
+        assertEquals(Locale.of(lang), expected);
+    }
+
+    @Test (dataProvider = "data_2Args")
+    public void test_2Args(Locale expected, String lang, String ctry) {
+        assertEquals(Locale.of(lang, ctry), expected);
+    }
+
+    @Test (dataProvider = "data_3Args")
+    public void test_3Args(Locale expected, String lang, String ctry, String vrnt) {
+        assertEquals(Locale.of(lang, ctry, vrnt), expected);
+    }
+
+    @Test
+    public void test_NPE() {
+        assertThrows(NullPointerException.class, () -> Locale.of(null));
+        assertThrows(NullPointerException.class, () -> Locale.of("", null));
+        assertThrows(NullPointerException.class, () -> Locale.of("", "", null));
+    }
+}