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

8303275: Use {@Return and @linkplain in Locale and related classes

Browse source 
Reviewed-by: naoto
This commit is contained in:
Justin Lu 2023-03-07 18:18:59 +00:00 • committed by Naoto Sato
parent ac3ab5b007
commit acf899612f
3 changed files with 88 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -427,7 +427,7 @@ import sun.util.locale.provider.TimeZoneNameUtility;
* stream, including extensions. * stream, including extensions.
* *
* <p>During deserialization, readResolve adds extensions as described * <p>During deserialization, readResolve adds extensions as described
* in <a href="#special_cases_constructor">Special Cases</a>, only * in {@linkplain ##special_cases_constructor Special Cases}, only
* for the two cases th_TH_TH and ja_JP_JP. * for the two cases th_TH_TH and ja_JP_JP.
* *
* <h4><a id="legacy_language_codes">Legacy language codes</a></h4> * <h4><a id="legacy_language_codes">Legacy language codes</a></h4>
@ -719,16 +719,16 @@ public final class Locale implements Cloneable, Serializable {
* @implNote * @implNote
* <ul> * <ul>
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* <li>For backward compatibility reasons, this constructor does not make * <li>For backward compatibility reasons, this constructor does not make
* any syntactic checks on the input. * any syntactic checks on the input.
* <li>The two cases ("ja", "JP", "JP") and ("th", "TH", "TH") are handled specially, * <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. * see {@linkplain ##special_cases_constructor Special Cases} for more information.
* </ul> * </ul>
* *
* @deprecated Locale constructors have been deprecated. See <a href ="#ObtainingLocale"> * @deprecated Locale constructors have been deprecated. See {@linkplain ##ObtainingLocale
* Obtaining a Locale</a> for other options. * Obtaining a Locale} for other options.
* *
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag * @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 * up to 8 characters in length. See the {@code Locale} class description about
@ -755,14 +755,14 @@ public final class Locale implements Cloneable, Serializable {
* @implNote * @implNote
* <ul> * <ul>
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* <li>For backward compatibility reasons, this constructor does not make * <li>For backward compatibility reasons, this constructor does not make
* any syntactic checks on the input. * any syntactic checks on the input.
* </ul> * </ul>
* *
* @deprecated Locale constructors have been deprecated. See <a href="#ObtainingLocale"> * @deprecated Locale constructors have been deprecated. See {@linkplain
* Obtaining a Locale</a> for other options. * ##ObtainingLocale Obtaining a Locale} for other options.
* *
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag * @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 * up to 8 characters in length. See the {@code Locale} class description about
@ -782,14 +782,14 @@ public final class Locale implements Cloneable, Serializable {
* @implNote * @implNote
* <ul> * <ul>
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* <li>For backward compatibility reasons, this constructor does not make * <li>For backward compatibility reasons, this constructor does not make
* any syntactic checks on the input. * any syntactic checks on the input.
* </ul> * </ul>
* *
* @deprecated Locale constructors have been deprecated. See <a href="#ObtainingLocale"> * @deprecated Locale constructors have been deprecated. See {@linkplain
* Obtaining a Locale</a> for other options. * ##ObtainingLocale Obtaining a Locale} for other options.
* *
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag * @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 * up to 8 characters in length. See the {@code Locale} class description about
@ -811,18 +811,19 @@ public final class Locale implements Cloneable, Serializable {
* <li>This method does not make any syntactic checks on the input. * <li>This method does not make any syntactic checks on the input.
* Use {@link Locale.Builder} for full syntactic checks with BCP47. * Use {@link Locale.Builder} for full syntactic checks with BCP47.
* <li>The two cases ("ja", "JP", "JP") and ("th", "TH", "TH") are handled specially, * <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. * see {@linkplain ##special_cases_constructor Special Cases} for more information.
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* </ul> * </ul>
* *
* @param language A language code. See the {@code Locale} class description of * @param language A language code. See the {@code Locale} class description of
* <a href="#def_language">language</a> values. * {@linkplain ##def_language language} values.
* @param country A country code. See the {@code Locale} class description of * @param country A country code. See the {@code Locale} class description of
* <a href="#def_region">country</a> values. * {@linkplain ##def_region country} values.
* @param variant Any arbitrary value used to indicate a variation of a {@code Locale}. * @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. * See the {@code Locale} class description of {@linkplain ##def_variant
* variant} values.
* @throws NullPointerException thrown if any argument is null. * @throws NullPointerException thrown if any argument is null.
* @return A {@code Locale} object * @return A {@code Locale} object
* @since 19 * @since 19
@ -840,14 +841,14 @@ public final class Locale implements Cloneable, Serializable {
* <li>This method does not make any syntactic checks on the input. * <li>This method does not make any syntactic checks on the input.
* Use {@link Locale.Builder} for full syntactic checks with BCP47. * Use {@link Locale.Builder} for full syntactic checks with BCP47.
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* </ul> * </ul>
* *
* @param language A language code. See the {@code Locale} class description of * @param language A language code. See the {@code Locale} class description of
* <a href="#def_language">language</a> values. * {@linkplain ##def_language language} values.
* @param country A country code. See the {@code Locale} class description of * @param country A country code. See the {@code Locale} class description of
* <a href="#def_region">country</a> values. * {@linkplain ##def_region country} values.
* @throws NullPointerException thrown if either argument is null. * @throws NullPointerException thrown if either argument is null.
* @return A {@code Locale} object * @return A {@code Locale} object
* @since 19 * @since 19
@ -864,12 +865,12 @@ public final class Locale implements Cloneable, Serializable {
* <li>This method does not make any syntactic checks on the input. * <li>This method does not make any syntactic checks on the input.
* Use {@link Locale.Builder} for full syntactic checks with BCP47. * Use {@link Locale.Builder} for full syntactic checks with BCP47.
* <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to * <li>Obsolete ISO 639 codes ("iw", "ji", and "in") are mapped to
* their current forms. See <a href="#legacy_language_codes">Legacy language * their current forms. See {@linkplain ##legacy_language_codes Legacy language
* codes</a> for more information. * codes} for more information.
* </ul> * </ul>
* *
* @param language A language code. See the {@code Locale} class description of * @param language A language code. See the {@code Locale} class description of
* <a href="#def_language">language</a> values. * {@linkplain ##def_language language} values.
* @throws NullPointerException thrown if argument is null. * @throws NullPointerException thrown if argument is null.
* @return A {@code Locale} object * @return A {@code Locale} object
* @since 19 * @since 19
@ -1197,22 +1198,22 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns an array of all installed locales. * {@return an array of installed locales}
*
* The returned array represents the union of locales supported * The returned array represents the union of locales supported
* by the Java runtime environment and by installed * by the Java runtime environment and by installed
* {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider} * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
* implementations. At a minimum, the returned array must contain a * implementations. At a minimum, the returned array must contain a
* {@code Locale} instance equal to {@link Locale#ROOT Locale.ROOT} and * {@code Locale} instance equal to {@link Locale#ROOT Locale.ROOT} and
* a {@code Locale} instance equal to {@link Locale#US Locale.US}. * a {@code Locale} instance equal to {@link Locale#US Locale.US}.
*
* @return An array of installed locales.
*/ */
public static Locale[] getAvailableLocales() { public static Locale[] getAvailableLocales() {
return LocaleServiceProviderPool.getAllAvailableLocales(); return LocaleServiceProviderPool.getAllAvailableLocales();
} }
/** /**
* Returns a stream of all installed locales. * {@return a stream of installed locales}
*
* The returned stream represents the union of locales supported * The returned stream represents the union of locales supported
* by the Java runtime environment and by installed * by the Java runtime environment and by installed
* {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider} * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
@ -1222,7 +1223,6 @@ public final class Locale implements Cloneable, Serializable {
* *
* @implNote Unlike {@code getAvailableLocales()}, this method does * @implNote Unlike {@code getAvailableLocales()}, this method does
* not create a defensive copy of the Locale array. * not create a defensive copy of the Locale array.
* @return A stream of installed locales.
* @since 21 * @since 21
*/ */
public static Stream<Locale> availableLocales() { public static Stream<Locale> availableLocales() {
@ -1256,12 +1256,11 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns a {@code Set} of ISO3166 country codes for the specified type. * {@return a {@code Set} of ISO3166 country codes for the specified type}
* *
* @param type {@link Locale.IsoCountryCode} specified ISO code type. * @param type {@link Locale.IsoCountryCode} specified ISO code type.
* @see java.util.Locale.IsoCountryCode * @see java.util.Locale.IsoCountryCode
* @throws NullPointerException if type is null * @throws NullPointerException if type is null
* @return a {@code Set} of ISO country codes for the specified type.
* @since 9 * @since 9
*/ */
public static Set<String> getISOCountries(IsoCountryCode type) { public static Set<String> getISOCountries(IsoCountryCode type) {
@ -1308,8 +1307,8 @@ public final class Locale implements Cloneable, Serializable {
* Returns the language code of this Locale. * Returns the language code of this Locale.
* *
* @implNote This method returns the new forms for the obsolete ISO 639 * @implNote This method returns the new forms for the obsolete ISO 639
* codes ("iw", "ji", and "in"). See <a href="#legacy_language_codes"> * codes ("iw", "ji", and "in"). See {@linkplain ##legacy_language_codes
* Legacy language codes</a> for more information. * Legacy language codes} for more information.
* *
* @return The language code, or the empty string if none is defined. * @return The language code, or the empty string if none is defined.
* @see #getDisplayLanguage * @see #getDisplayLanguage
@ -1355,8 +1354,8 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns {@code true} if this {@code Locale} has any <a href="#def_extensions"> * Returns {@code true} if this {@code Locale} has any {@linkplain ##def_extensions
* extensions</a>. * extensions}.
* *
* @return {@code true} if this {@code Locale} has any extensions * @return {@code true} if this {@code Locale} has any extensions
* @since 1.8 * @since 1.8
@ -1366,8 +1365,8 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns a copy of this {@code Locale} with no <a href="#def_extensions"> * Returns a copy of this {@code Locale} with no {@linkplain ##def_extensions
* extensions</a>. If this {@code Locale} has no extensions, this {@code Locale} * extensions}. If this {@code Locale} has no extensions, this {@code Locale}
* is returned. * is returned.
* *
* @return a copy of this {@code Locale} with no extensions, or {@code this} * @return a copy of this {@code Locale} with no extensions, or {@code this}
@ -1571,16 +1570,15 @@ public final class Locale implements Cloneable, Serializable {
* syntax requirements, this method handles these fields as * syntax requirements, this method handles these fields as
* described below: * described below:
* *
* <p><b>Language:</b> If language is empty, or not <a * <p><b>Language:</b> If language is empty, or not
* href="#def_language" >well-formed</a> (for example "a" or * {@linkplain ##def_language well-formed} (for example "a" or
* "e2"), it will be emitted as "und" (Undetermined). * "e2"), it will be emitted as "und" (Undetermined).
* *
* <p><b>Country:</b> If country is not <a * <p><b>Country:</b> If country is not {@linkplain ##def_region well-formed}
* href="#def_region">well-formed</a> (for example "12" or "USA"), * (for example "12" or "USA"), it will be omitted.
* it will be omitted.
* *
* <p><b>Variant:</b> If variant <b>is</b> <a * <p><b>Variant:</b> If variant <b>is</b> {@linkplain ##def_variant
* href="#def_variant">well-formed</a>, each sub-segment * well-formed}, each sub-segment
* (delimited by '-' or '_') is emitted as a subtag. Otherwise: * (delimited by '-' or '_') is emitted as a subtag. Otherwise:
* <ul> * <ul>
* *
@ -1702,7 +1700,7 @@ public final class Locale implements Cloneable, Serializable {
* <li>The language codes "iw", "ji", and "in" are mapped to "he", * <li>The language codes "iw", "ji", and "in" are mapped to "he",
* "yi", and "id" respectively. (This is the same canonicalization * "yi", and "id" respectively. (This is the same canonicalization
* that's done in Locale's constructors.) See * that's done in Locale's constructors.) See
* <a href="#legacy_language_codes">Legacy language codes</a> * {@linkplain ##legacy_language_codes Legacy language codes}
* for more information. * for more information.
* *
* <li>The portion of a private use subtag prefixed by "lvariant", * <li>The portion of a private use subtag prefixed by "lvariant",
@ -1830,7 +1828,8 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns a three-letter abbreviation of this locale's language. * {@return a three-letter abbreviation of this locale's language}
*
* If the language matches an ISO 639-1 two-letter code, the * If the language matches an ISO 639-1 two-letter code, the
* corresponding ISO 639-2/T three-letter lowercase code is * corresponding ISO 639-2/T three-letter lowercase code is
* returned. The ISO 639-2 language codes can be found on-line, * returned. The ISO 639-2 language codes can be found on-line,
@ -1839,7 +1838,6 @@ public final class Locale implements Cloneable, Serializable {
* language, the language is returned as is. If the locale does * language, the language is returned as is. If the locale does
* not specify a language the empty string is returned. * not specify a language the empty string is returned.
* *
* @return A three-letter abbreviation of this locale's language.
* @throws MissingResourceException Throws MissingResourceException if * @throws MissingResourceException Throws MissingResourceException if
* three-letter language abbreviation is not available for this locale. * three-letter language abbreviation is not available for this locale.
*/ */
@ -1858,7 +1856,8 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns a three-letter abbreviation for this locale's country. * {@return a three-letter abbreviation of this locale's country}
*
* If the country matches an ISO 3166-1 alpha-2 code, the * If the country matches an ISO 3166-1 alpha-2 code, the
* corresponding ISO 3166-1 alpha-3 uppercase code is returned. * corresponding ISO 3166-1 alpha-3 uppercase code is returned.
* If the locale doesn't specify a country, this will be the empty * If the locale doesn't specify a country, this will be the empty
@ -1866,7 +1865,6 @@ public final class Locale implements Cloneable, Serializable {
* *
* <p>The ISO 3166-1 codes can be found on-line. * <p>The ISO 3166-1 codes can be found on-line.
* *
* @return A three-letter abbreviation of this locale's country.
* @throws MissingResourceException Throws MissingResourceException if the * @throws MissingResourceException Throws MissingResourceException if the
* three-letter country abbreviation is not available for this locale. * three-letter country abbreviation is not available for this locale.
*/ */
@ -2074,7 +2072,7 @@ public final class Locale implements Cloneable, Serializable {
* Returns a name for the locale that is appropriate for display to the * Returns a name for the locale that is appropriate for display to the
* user. This will be the values returned by getDisplayLanguage(), * user. This will be the values returned by getDisplayLanguage(),
* getDisplayScript(), getDisplayCountry(), getDisplayVariant() and * getDisplayScript(), getDisplayCountry(), getDisplayVariant() and
* optional <a href="./Locale.html#def_locale_extension">Unicode extensions</a> * optional {@linkplain ##def_locale_extension Unicode extensions}
* assembled into a single string. The non-empty values are used in order, with * assembled into a single string. The non-empty values are used in order, with
* the second and subsequent names in parentheses. For example: * the second and subsequent names in parentheses. For example:
* <blockquote> * <blockquote>
@ -2099,8 +2097,8 @@ public final class Locale implements Cloneable, Serializable {
* Returns a name for the locale that is appropriate for display * Returns a name for the locale that is appropriate for display
* to the user. This will be the values returned by * to the user. This will be the values returned by
* getDisplayLanguage(), getDisplayScript(), getDisplayCountry(), * getDisplayLanguage(), getDisplayScript(), getDisplayCountry(),
* getDisplayVariant(), and optional <a href="./Locale.html#def_locale_extension"> * getDisplayVariant(), and optional {@linkplain ##def_locale_extension
* Unicode extensions</a> assembled into a single string. The non-empty * Unicode extensions} assembled into a single string. The non-empty
* values are used in order, with the second and subsequent names in * values are used in order, with the second and subsequent names in
* parentheses. For example: * parentheses. For example:
* <blockquote> * <blockquote>
@ -2467,7 +2465,7 @@ public final class Locale implements Cloneable, Serializable {
* are exactly "ja", "JP", "JP" or "th", "TH", "TH" and script/extensions * are exactly "ja", "JP", "JP" or "th", "TH", "TH" and script/extensions
* fields are empty, this method supplies {@code UNICODE_LOCALE_EXTENSION} * fields are empty, this method supplies {@code UNICODE_LOCALE_EXTENSION}
* "ca"/"japanese" (calendar type is "japanese") or "nu"/"thai" (number script * "ca"/"japanese" (calendar type is "japanese") or "nu"/"thai" (number script
* type is "thai"). See <a href="Locale.html#special_cases_constructor">Special Cases</a> * type is "thai"). See {@linkplain ##special_cases_constructor Special Cases}
* for more information. * for more information.
* *
* @return an instance of {@code Locale} equivalent to * @return an instance of {@code Locale} equivalent to
@ -2704,7 +2702,7 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the language. If {@code language} is the empty string or * Sets the language. If {@code language} is the empty string or
* null, the language in this {@code Builder} is removed. Otherwise, * null, the language in this {@code Builder} is removed. Otherwise,
* the language must be <a href="./Locale.html#def_language">well-formed</a> * the language must be {@linkplain Locale##def_language well-formed}
* or an exception is thrown. * or an exception is thrown.
* *
* <p>The typical language value is a two or three-letter language * <p>The typical language value is a two or three-letter language
@ -2726,7 +2724,7 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the script. If {@code script} is null or the empty string, * Sets the script. If {@code script} is null or the empty string,
* the script in this {@code Builder} is removed. * the script in this {@code Builder} is removed.
* Otherwise, the script must be <a href="./Locale.html#def_script">well-formed</a> or an * Otherwise, the script must be {@linkplain Locale##def_script well-formed} or an
* exception is thrown. * exception is thrown.
* *
* <p>The typical script value is a four-letter script code as defined by ISO 15924. * <p>The typical script value is a four-letter script code as defined by ISO 15924.
@ -2747,7 +2745,7 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the region. If region is null or the empty string, the region * Sets the region. If region is null or the empty string, the region
* in this {@code Builder} is removed. Otherwise, * in this {@code Builder} is removed. Otherwise,
* the region must be <a href="./Locale.html#def_region">well-formed</a> or an * the region must be {@linkplain Locale##def_region well-formed} or an
* exception is thrown. * exception is thrown.
* *
* <p>The typical region value is a two-letter ISO 3166 code or a * <p>The typical region value is a two-letter ISO 3166 code or a
@ -2772,7 +2770,7 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the variant. If variant is null or the empty string, the * Sets the variant. If variant is null or the empty string, the
* variant in this {@code Builder} is removed. Otherwise, it * variant in this {@code Builder} is removed. Otherwise, it
* must consist of one or more <a href="./Locale.html#def_variant">well-formed</a> * must consist of one or more {@linkplain Locale##def_variant well-formed}
* subtags, or an exception is thrown. * subtags, or an exception is thrown.
* *
* <p><b>Note:</b> This method checks if {@code variant} * <p><b>Note:</b> This method checks if {@code variant}
@ -2800,7 +2798,7 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the extension for the given key. If the value is null or the * Sets the extension for the given key. If the value is null or the
* empty string, the extension is removed. Otherwise, the extension * empty string, the extension is removed. Otherwise, the extension
* must be <a href="./Locale.html#def_extensions">well-formed</a> or an exception * must be {@linkplain Locale##def_extensions well-formed} or an exception
* is thrown. * is thrown.
* *
* <p><b>Note:</b> The key {@link Locale#UNICODE_LOCALE_EXTENSION * <p><b>Note:</b> The key {@link Locale#UNICODE_LOCALE_EXTENSION
@ -2832,9 +2830,8 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Sets the Unicode locale keyword type for the given key. If the type * Sets the Unicode locale keyword type for the given key. If the type
* is null, the Unicode keyword is removed. Otherwise, the key must be * is null, the Unicode keyword is removed. Otherwise, the key must be
* non-null and both key and type must be <a * non-null and both key and type must be {@linkplain
* href="./Locale.html#def_locale_extension">well-formed</a> or an exception * Locale##def_locale_extension well-formed} or an exception is thrown.
* is thrown.
* *
* <p>Keys and types are converted to lower case. * <p>Keys and types are converted to lower case.
* *
@ -2861,8 +2858,8 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Adds a unicode locale attribute, if not already present, otherwise * Adds a unicode locale attribute, if not already present, otherwise
* has no effect. The attribute must not be null and must be <a * has no effect. The attribute must not be null and must be
* href="./Locale.html#def_locale_extension">well-formed</a> or an exception * {@linkplain Locale##def_locale_extension well-formed} or an exception
* is thrown. * is thrown.
* *
* @param attribute the attribute * @param attribute the attribute
@ -2882,8 +2879,8 @@ public final class Locale implements Cloneable, Serializable {
/** /**
* Removes a unicode locale attribute, if present, otherwise has no * Removes a unicode locale attribute, if present, otherwise has no
* effect. The attribute must not be null and must be <a * effect. The attribute must not be null and must be
* href="./Locale.html#def_locale_extension">well-formed</a> or an exception * {@linkplain Locale##def_locale_extension well-formed} or an exception
* is thrown. * is thrown.
* *
* <p>Attribute comparison for removal is case-insensitive. * <p>Attribute comparison for removal is case-insensitive.
@ -3088,8 +3085,8 @@ public final class Locale implements Cloneable, Serializable {
* <a href="https://tools.ietf.org/html/rfc4647">RFC 4647 Matching of * <a href="https://tools.ietf.org/html/rfc4647">RFC 4647 Matching of
* Language Tags</a>. A language range is an identifier which is used to * Language Tags</a>. A language range is an identifier which is used to
* select language tag(s) meeting specific requirements by using the * select language tag(s) meeting specific requirements by using the
* mechanisms described in <a href="Locale.html#LocaleMatching">Locale * mechanisms described in {@linkplain Locale##LocaleMatching Locale
* Matching</a>. A list which represents a user's preferences and consists * Matching}. A list which represents a user's preferences and consists
* of language ranges is called a <em>Language Priority List</em>. * of language ranges is called a <em>Language Priority List</em>.
* *
* <p>There are two types of language ranges: basic and extended. In RFC * <p>There are two types of language ranges: basic and extended. In RFC
@ -3389,9 +3386,7 @@ public final class Locale implements Cloneable, Serializable {
} }
/** /**
* Returns a hash code value for the object. * {@return a hash code value for this object}
*
* @return a hash code value for this object.
*/ */
@Override @Override
public int hashCode() { public int hashCode() {

21
src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java
View file

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2005, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -86,8 +86,8 @@ import java.util.Locale;
* methods of installed providers for the appropriate interface to find one that * methods of installed providers for the appropriate interface to find one that
* supports the requested locale. If such a provider is found, its other * supports the requested locale. If such a provider is found, its other
* methods are called to obtain the requested object or name. When checking * methods are called to obtain the requested object or name. When checking
* whether a locale is supported, the <a href="../Locale.html#def_extensions"> * whether a locale is supported, the {@linkplain Locale##def_extensions
* locale's extensions</a> are ignored by default. (If locale's extensions should * locale's extensions} are ignored by default. (If locale's extensions should
* also be checked, the {@code isSupportedLocale} method must be overridden.) * also be checked, the {@code isSupportedLocale} method must be overridden.)
* If neither the Java runtime environment itself nor an installed provider * If neither the Java runtime environment itself nor an installed provider
* supports the requested locale, the methods go through a list of candidate * supports the requested locale, the methods go through a list of candidate
@ -175,23 +175,22 @@ public abstract class LocaleServiceProvider {
} }
/** /**
* Returns an array of all locales for which this locale service provider * {@return an array of all locales for which this locale service provider
* can provide localized objects or names. This information is used to * can provide localized objects or names}
* compose {@code getAvailableLocales()} values of the locale-dependent *
* services, such as {@code DateFormat.getAvailableLocales()}. * This information is used to compose {@code getAvailableLocales()}
* values of the locale-dependent services, such as
* {@code DateFormat.getAvailableLocales()}.
* *
* <p>The array returned by this method should not include two or more * <p>The array returned by this method should not include two or more
* {@code Locale} objects only differing in their extensions. * {@code Locale} objects only differing in their extensions.
*
* @return An array of all locales for which this locale service provider
* can provide localized objects or names.
*/ */
public abstract Locale[] getAvailableLocales(); public abstract Locale[] getAvailableLocales();
/** /**
* Returns {@code true} if the given {@code locale} is supported by * Returns {@code true} if the given {@code locale} is supported by
* this locale service provider. The given {@code locale} may contain * this locale service provider. The given {@code locale} may contain
* <a href="../Locale.html#def_extensions">extensions</a> that should be * {@linkplain Locale##def_extensions extensions} that should be
* taken into account for the support determination. * taken into account for the support determination.
* *
* <p>The default implementation returns {@code true} if the given {@code locale} * <p>The default implementation returns {@code true} if the given {@code locale}

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

@ -50,7 +50,7 @@ import java.util.stream.Stream;
public final class LocaleServiceProviderPool { public final class LocaleServiceProviderPool {
/** /**
* A Map that holds singleton instances of this class. Each instance holds a * A Map that holds singleton instances of this class. Each instance holds a
* set of provider implementations of a particular locale sensitive service. * set of provider implementations of a particular locale sensitive service.
*/ */
private static final ConcurrentMap<Class<? extends LocaleServiceProvider>, LocaleServiceProviderPool> poolOfPools = private static final ConcurrentMap<Class<? extends LocaleServiceProvider>, LocaleServiceProviderPool> poolOfPools =
@ -63,7 +63,7 @@ public final class LocaleServiceProviderPool {
new ConcurrentHashMap<>(); new ConcurrentHashMap<>();
/** /**
* Available locales for this locale sensitive service. This also contains * Available locales for this locale sensitive service. This also contains
* JRE's available locales * JRE's available locales
*/ */
private Set<Locale> availableLocales = null; private Set<Locale> availableLocales = null;
@ -148,33 +148,31 @@ public final class LocaleServiceProviderPool {
} }
/** /**
* Returns a stream of the available locales for all the provider classes. * {@return a stream of the available locales for all the provider classes}
* This stream is constructed from all the locales
* that are provided by each provider, including the JRE.
* *
* @return a stream of the available locales for all provider classes * This stream is constructed from all the locales that are provided by each
* provider, including the JRE.
*/ */
public static Stream<Locale> streamAllAvailableLocales() { public static Stream<Locale> streamAllAvailableLocales() {
return Arrays.stream(AllAvailableLocales.allAvailableLocales); return Arrays.stream(AllAvailableLocales.allAvailableLocales);
} }
/** /**
* Returns an array of available locales for all the provider classes. * {@return an array of the available locales for all the provider classes}
*
* This array is a merged array of all the locales that are provided by each * This array is a merged array of all the locales that are provided by each
* provider, including the JRE. * provider, including the JRE.
*
* @return an array of the available locales for all provider classes
*/ */
public static Locale[] getAllAvailableLocales() { public static Locale[] getAllAvailableLocales() {
return AllAvailableLocales.allAvailableLocales.clone(); return AllAvailableLocales.allAvailableLocales.clone();
} }
/** /**
* Returns an array of available locales. This array is a * {@return an array of the available locales}
*
* This array is a
* merged array of all the locales that are provided by each * merged array of all the locales that are provided by each
* provider, including the JRE. * provider, including the JRE.
*
* @return an array of the available locales
*/ */
public Locale[] getAvailableLocales() { public Locale[] getAvailableLocales() {
Set<Locale> locList = new HashSet<>(); Set<Locale> locList = new HashSet<>();