Summary

Recommend using Locale.of(String, String, String) method instead of the constructor in Locale.Builder class.

Problem

Constructors in java.util.Locale class have been deprecated in JDK19. There are a couple of locations in Locale.Builder class that still reads "use a Locale constructor." which need to be replaced with Locale.of() method.

Solution

Modify the class description and the method description of setVariant() not to recommend the Locale constructor. Also, modernize the class description with newer constructs, i.e., @implNote and @snippet.

Specification

Modify the class description as:

      /**
       * {@code Builder} is used to build instances of {@code Locale}
       * from values configured by the setters.  Unlike the {@code Locale}
-      * constructors, the {@code Builder} checks if a value configured by a
+      * constructors or {@code Locale.of()} factory methods,
+      * 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 obtained from a {@code Builder} is
       * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
       * without losing information.
       *
-      * <p><b>Note:</b> The {@code Locale} class does not provide any
+      * @implNote
+      * The {@code Locale} class does not provide any
       * syntactic restrictions on variant, while BCP 47 requires each variant
       * subtag to be 5 to 8 alphanumerics or a single numeric followed by 3
       * alphanumerics.  The method {@code setVariant} throws
       * {@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}
+      * this restriction. If it is necessary to support such a variant, use
+      * {@link Locale#of(String, String, String)}.  However, keep in mind that a {@code Locale}
       * object obtained this way might lose the variant information when
       * transformed to a BCP 47 language tag.
       *
       * <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();
-      * </pre>
-      * </blockquote>
+      * {@snippet lang=java :
+      * Locale aLocale = new Locale.Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
+      * }
       *
       * <p>Builders can be reused; {@code clear()} resets all
       * fields to their default values.
       *
       * @see Locale#forLanguageTag
+      * @see Locale#of(String, String, String)
       * @since 1.7
       */

Modify the method description for setVariant() as:

@@ -2761,15 +2764,16 @@
           * satisfies the IETF BCP 47 variant subtag's syntax requirements,
           * and normalizes the value to lowercase letters.  However,
           * the {@code Locale} class does not impose any syntactic
           * restriction on variant, and the variant value in
           * {@code Locale} is case sensitive.  To set such a variant,
-          * use a Locale constructor.
+          * use {@link Locale#of(String, String, String)}.
           *
           * @param variant the variant
           * @return This builder.
           * @throws IllformedLocaleException if {@code variant} is ill-formed
+          * @see Locale#of(String, String, String) 
           */