archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8289252: Recommend Locale.of() method instead of the constructor

Browse source 
Reviewed-by: joehw, rriggs
This commit is contained in:
Naoto Sato 2022-06-29 15:47:26 +00:00
parent 570897498b
commit cf7154498f
1 changed files with 12 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

22
src/java.base/share/classes/java/util/Locale.java
View file

@ -2585,34 +2585,35 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* {@code Builder} is used to build instances of {@code Locale} * {@code Builder} is used to build instances of {@code Locale}
* from values configured by the setters. Unlike the {@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} * setter satisfies the syntax requirements defined by the {@code Locale}
* class. A {@code Locale} object obtained from 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 * well-formed and can be transformed to a well-formed IETF BCP 47 language tag
* without losing information. * 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 * syntactic restrictions on variant, while BCP 47 requires each variant
* subtag to be 5 to 8 alphanumerics or a single numeric followed by 3 * subtag to be 5 to 8 alphanumerics or a single numeric followed by 3
* alphanumerics. The method {@code setVariant} throws * alphanumerics. The method {@code setVariant} throws
* {@code IllformedLocaleException} for a variant that does not satisfy * {@code IllformedLocaleException} for a variant that does not satisfy
* this restriction. If it is necessary to support such a variant, use a * this restriction. If it is necessary to support such a variant, use
* Locale constructor. However, keep in mind that a {@code Locale} * {@link Locale#of(String, String, String)}. However, keep in mind that a {@code Locale}
* object obtained 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. * transformed to a BCP 47 language tag.
* *
* <p>The following example shows how to obtain a {@code Locale} object * <p>The following example shows how to obtain a {@code Locale} object
* using a {@code Builder}. * using a {@code Builder}.
* <blockquote> * {@snippet lang=java :
* <pre> * Locale aLocale = new Locale.Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
* Locale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build(); * }
* </pre>
* </blockquote>
* *
* <p>Builders can be reused; {@code clear()} resets all * <p>Builders can be reused; {@code clear()} resets all
* fields to their default values. * fields to their default values.
* *
* @see Locale#forLanguageTag * @see Locale#forLanguageTag
* @see Locale#of(String, String, String)
* @since 1.7 * @since 1.7
*/ */
public static final class Builder { public static final class Builder {
@ -2763,11 +2764,12 @@ public final class Locale implements Cloneable, Serializable {
* the {@code Locale} class does not impose any syntactic * the {@code Locale} class does not impose any syntactic
* restriction on variant, and the variant value in * restriction on variant, and the variant value in
* {@code Locale} is case sensitive. To set such a variant, * {@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 * @param variant the variant
* @return This builder. * @return This builder.
* @throws IllformedLocaleException if {@code variant} is ill-formed * @throws IllformedLocaleException if {@code variant} is ill-formed
* @see Locale#of(String, String, String)
*/ */
public Builder setVariant(String variant) { public Builder setVariant(String variant) {
try { try {