* If the specified {@code locale} contains "cu" and/or "rg" - * Unicode extensions, + * {@linkplain Locale##def_locale_extension Unicode extensions}, * the instance returned from this method reflects * the values specified with those extensions. If both "cu" and "rg" are * specified, the currency from the "cu" extension supersedes the implicit one @@ -514,7 +514,7 @@ public final class Currency implements Serializable { *
* If the default {@link Locale.Category#DISPLAY DISPLAY} locale * contains "rg" (region override) - * Unicode extension, + * {@linkplain Locale##def_locale_extension Unicode extensions}, * the symbol returned from this method reflects * the value specified with that extension. *
@@ -536,7 +536,7 @@ public final class Currency implements Serializable { * symbol can be determined, the ISO 4217 currency code is returned. *
* If the specified {@code locale} contains "rg" (region override) - * Unicode extension, + * {@linkplain Locale##def_locale_extension Unicode extensions}, * the symbol returned from this method reflects * the value specified with that extension. * diff --git a/src/java.base/share/classes/java/util/ListResourceBundle.java b/src/java.base/share/classes/java/util/ListResourceBundle.java index bac72b3dfe6..428e3b1ac32 100644 --- a/src/java.base/share/classes/java/util/ListResourceBundle.java +++ b/src/java.base/share/classes/java/util/ListResourceBundle.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2023, 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 @@ -61,14 +61,13 @@ import sun.util.ResourceBundleEnumeration; * "MyResources" is the default member of the bundle family, and * "MyResources_fr" is the French member. * These members are based on {@code ListResourceBundle} - * (a related example shows + * (a related {@linkplain PropertyResourceBundle##sample example} shows * how you can add a bundle to this family that's based on a properties file). * The keys in this example are of the form "s1" etc. The actual * keys are entirely up to your choice, so long as they are the same as * the keys you use in your program to retrieve the objects from the bundle. * Keys are case-sensitive. - *
- *
+ * {@snippet lang=java :
*
* public class MyResources extends ListResourceBundle {
* protected Object[][] getContents() {
@@ -103,8 +102,7 @@ import sun.util.ResourceBundleEnumeration;
* };
* }
* }
- *
- *
+ * }
*
* * The implementation of a {@code ListResourceBundle} subclass must be thread-safe diff --git a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java index 368ba3854fb..8fac36fb84f 100644 --- a/src/java.base/share/classes/java/util/Locale.java +++ b/src/java.base/share/classes/java/util/Locale.java @@ -349,23 +349,19 @@ import sun.util.locale.provider.TimeZoneNameUtility; * for creating a default object of that type. For example, the * {@code NumberFormat} class provides these three convenience methods * for creating a default {@code NumberFormat} object: - *
- *+ * {@snippet lang=java : + * NumberFormat.getInstance(); + * NumberFormat.getCurrencyInstance(); + * NumberFormat.getPercentInstance(); + * } * Each of these methods has two variants; one with an explicit locale * and one without; the latter uses the default * {@link Locale.Category#FORMAT FORMAT} locale: - *- * NumberFormat.getInstance() - * NumberFormat.getCurrencyInstance() - * NumberFormat.getPercentInstance() - *- *
- *+ * {@snippet lang=java : + * NumberFormat.getInstance(myLocale); + * NumberFormat.getCurrencyInstance(myLocale); + * NumberFormat.getPercentInstance(myLocale); + * } * A {@code Locale} is the mechanism for identifying the kind of object * ({@code NumberFormat}) that you would like to get. The locale is * just a mechanism for identifying objects, @@ -1620,8 +1616,9 @@ public final class Locale implements Cloneable, Serializable { * 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, - *- * NumberFormat.getInstance(myLocale) - * NumberFormat.getCurrencyInstance(myLocale) - * NumberFormat.getPercentInstance(myLocale) - *- *
- * Locale.forLanguageTag("xx-YY").toLanguageTag();
+ * {@snippet lang=java :
+ * Locale.forLanguageTag("xx-YY").toLanguageTag();
+ * }
*
* will return "xx-YY", but the language subtag "xx" and the
* region subtag "YY" are invalid because they are not registered
@@ -1764,7 +1761,7 @@ public final class Locale implements Cloneable, Serializable {
* result locale (without case normalization). If it is then
* empty, the private use subtag is discarded:
*
- *
+ * {@snippet lang=java :
* Locale loc;
* loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX");
* loc.getVariant(); // returns "POSIX"
@@ -1773,16 +1770,16 @@ public final class Locale implements Cloneable, Serializable {
* loc = Locale.forLanguageTag("de-POSIX-x-URP-lvariant-Abc-Def");
* loc.getVariant(); // returns "POSIX_Abc_Def"
* loc.getExtension('x'); // returns "urp"
- *
+ * }
*
*
+ * {@snippet lang=java :
* Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
* Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
- *
+ * }
*
*
+ * {@snippet lang=java :
* Locale.forLanguageTag("ja-JP-x-lvariant-JP").toLanguageTag();
* // returns "ja-JP-u-ca-japanese-x-lvariant-JP"
* Locale.forLanguageTag("th-TH-x-lvariant-TH").toLanguageTag();
* // returns "th-TH-u-nu-thai-x-lvariant-TH"
- *
+ * }
*
*
- *
- * # MessageFormat pattern
- * s1=Die Platte \"{1}\" enthält {0}.
- *
- * # location of {0} in pattern
- * s2=1
- *
- * # sample disk name
- * s3=Meine Platte
- *
- * # first ChoiceFormat choice
- * s4=keine Dateien
- *
- * # second ChoiceFormat choice
- * s5=eine Datei
- *
- * # third ChoiceFormat choice
- * s6={0,number} Dateien
- *
- * # sample date
- * s7=3. März 1996
- *
- *
+ * {@snippet lang=properties :
+ * # MessageFormat pattern
+ * s1=Die Platte \"{1}\" enth\u00E4lt {0}.
+ * # location of {0} in pattern
+ * s2=1
+ * # sample disk name
+ * s3=Meine Platte
+ * # first ChoiceFormat choice
+ * s4=keine Dateien
+ * # second ChoiceFormat choice
+ * s5=eine Datei
+ * # third ChoiceFormat choice
+ * s6={0,number} Dateien
+ * # sample date
+ * s7=3. M\u00E4rz 1996
+ * }
*
* @apiNote
* {@code PropertyResourceBundle} can be constructed either
diff --git a/src/java.base/share/classes/java/util/ResourceBundle.java b/src/java.base/share/classes/java/util/ResourceBundle.java
index 75f4160ab62..b9a2dca88d5 100644
--- a/src/java.base/share/classes/java/util/ResourceBundle.java
+++ b/src/java.base/share/classes/java/util/ResourceBundle.java
@@ -125,20 +125,17 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* the {@code ResourceBundle} class using the
* {@link #getBundle(java.lang.String, java.util.Locale) getBundle}
* method:
- *
- *
+ * {@snippet lang=java :
* ResourceBundle myResources =
* ResourceBundle.getBundle("MyResources", currentLocale);
- *
- *
+ * }
*
* * Resource bundles contain key/value pairs. The keys uniquely * identify a locale-specific object in the bundle. Here's an * example of a {@code ListResourceBundle} that contains * two key/value pairs: - *
- *
+ * {@snippet lang=java :
* public class MyResources extends ListResourceBundle {
* protected Object[][] getContents() {
* return new Object[][] {
@@ -149,8 +146,7 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* };
* }
* }
- *
- *
+ * }
* Keys are always {@code String}s.
* In this example, the keys are "OkKey" and "CancelKey".
* In the above example, the values
@@ -161,12 +157,10 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* You retrieve an object from resource bundle using the appropriate
* getter method. Because "OkKey" and "CancelKey"
* are both strings, you would use {@code getString} to retrieve them:
- *
- *
+ * {@snippet lang=java :
* button1 = new Button(myResources.getString("OkKey"));
* button2 = new Button(myResources.getString("CancelKey"));
- *
- *
+ * }
* The getter methods all require the key as an argument and return
* the object if found. If the object is not found, the getter method
* throws a {@code MissingResourceException}.
@@ -177,11 +171,9 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* as well as a generic {@code getObject} method for any other
* type of object. When using {@code getObject}, you'll
* have to cast the result to the appropriate type. For example:
- *
- *
+ * {@snippet lang=java :
* int[] myIntegers = (int[]) myResources.getObject("intList");
- *
- *
+ * }
*
* * The Java Platform provides two subclasses of {@code ResourceBundle}, @@ -330,24 +322,27 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION; * Notice that you don't need to supply a value if * a "parent-level" {@code ResourceBundle} handles the same * key with the same value (as for the okKey below). - *
- *
+ * {@snippet lang=java :
* // default (English language, United States)
* public class MyResources extends ResourceBundle {
* public Object handleGetObject(String key) {
- * if (key.equals("okKey")) return "Ok";
- * if (key.equals("cancelKey")) return "Cancel";
+ * if (key.equals("okKey")) {
+ * return "Ok";
+ * }
+ * if (key.equals("cancelKey")) {
+ * return "Cancel";
+ * }
* return null;
* }
*
- * public Enumeration<String> getKeys() {
+ * public Enumeration getKeys() {
* return Collections.enumeration(keySet());
* }
*
* // Overrides handleKeySet() so that the getKeys() implementation
* // can rely on the keySet() value.
- * protected Set<String> handleKeySet() {
- * return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));
+ * protected Set handleKeySet() {
+ * return new HashSet(Arrays.asList("okKey", "cancelKey"));
* }
* }
*
@@ -355,16 +350,17 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* public class MyResources_de extends MyResources {
* public Object handleGetObject(String key) {
* // don't need okKey, since parent level handles it.
- * if (key.equals("cancelKey")) return "Abbrechen";
+ * if (key.equals("cancelKey")) {
+ * return "Abbrechen";
+ * }
* return null;
* }
*
- * protected Set<String> handleKeySet() {
- * return new HashSet<String>(Arrays.asList("cancelKey"));
+ * protected Set handleKeySet() {
+ * return new HashSet(Arrays.asList("cancelKey"));
* }
* }
- *
- *
+ * }
* You do not have to restrict yourself to using a single family of
* {@code ResourceBundle}s. For example, you could have a set of bundles for
* exception messages, {@code ExceptionResources}
@@ -512,9 +508,10 @@ public abstract class ResourceBundle {
/**
* Gets a string for the given key from this resource bundle or one of its parents.
* Calling this method is equivalent to calling
- *
- * (String) {@link #getObject(java.lang.String) getObject}(key).
- *
+ * {@snippet lang=java :
+ * // @link substring="getObject" target="#getObject(java.lang.String)"
+ * (String[]) getObject(key);
+ * }
*
* @param key the key for the desired string
* @throws NullPointerException if {@code key} is {@code null}
@@ -529,9 +526,10 @@ public abstract class ResourceBundle {
/**
* Gets a string array for the given key from this resource bundle or one of its parents.
* Calling this method is equivalent to calling
- *
- * (String[]) {@link #getObject(java.lang.String) getObject}(key).
- *
+ * {@snippet lang=java :
+ * // @link substring="getObject" target="#getObject(java.lang.String)"
+ * (String[]) getObject(key);
+ * }
*
* @param key the key for the desired string array
* @throws NullPointerException if {@code key} is {@code null}
@@ -842,9 +840,9 @@ public abstract class ResourceBundle {
/**
* Gets a resource bundle using the specified base name, the default locale,
* and the caller module. Calling this method is equivalent to calling
- * - * {@code getBundle(baseName, Locale.getDefault(), callerModule)}, - *+ * {@snippet lang=java : + * getBundle(baseName, Locale.getDefault(), callerModule); + * } * * @param baseName the base name of the resource bundle, a fully qualified class name * @throws java.lang.NullPointerException @@ -868,10 +866,10 @@ public abstract class ResourceBundle { * Returns a resource bundle using the specified base name, the * default locale and the specified control. Calling this method * is equivalent to calling - *
+ * {@snippet lang=java :
* getBundle(baseName, Locale.getDefault(),
- * this.getClass().getClassLoader(), control),
- *
+ * this.getClass().getClassLoader(), control);
+ * }
* except that {@code getClassLoader()} is run with the security
* privileges of {@code ResourceBundle}. See {@link
* #getBundle(String, Locale, ClassLoader, Control) getBundle} for the
@@ -912,9 +910,9 @@ public abstract class ResourceBundle {
/**
* Gets a resource bundle using the specified base name and locale,
* and the caller module. Calling this method is equivalent to calling
- * - * {@code getBundle(baseName, locale, callerModule)}, - *+ * {@snippet lang=java : + * getBundle(baseName, locale, callerModule); + * } * * @param baseName * the base name of the resource bundle, a fully qualified class name @@ -941,9 +939,9 @@ public abstract class ResourceBundle { /** * Gets a resource bundle using the specified base name and the default locale * on behalf of the specified module. This method is equivalent to calling - *
- * {@code getBundle(baseName, Locale.getDefault(), module)} - *+ * {@snippet lang=java : + * getBundle(baseName, Locale.getDefault(), module); + * } * * @param baseName the base name of the resource bundle, * a fully qualified class name @@ -1024,10 +1022,10 @@ public abstract class ResourceBundle { * Returns a resource bundle using the specified base name, target * locale and control, and the caller's class loader. Calling this * method is equivalent to calling - *
+ * {@snippet lang=java :
* getBundle(baseName, targetLocale, this.getClass().getClassLoader(),
- * control),
- *
+ * control);
+ * }
* except that {@code getClassLoader()} is run with the security
* privileges of {@code ResourceBundle}. See {@link
* #getBundle(String, Locale, ClassLoader, Control) getBundle} for the
@@ -1075,14 +1073,14 @@ public abstract class ResourceBundle {
* When this method is called from a named module and the given * loader is the class loader of the caller module, this is equivalent * to calling: - *
+ * {@snippet lang=java : + * getBundle(baseName, targetLocale, callerModule); + * } * * otherwise, this is equivalent to calling: - *- * getBundle(baseName, targetLocale, callerModule) - *
+ * {@snippet lang=java : + * getBundle(baseName, targetLocale, loader, control); + * } * where {@code control} is the default instance of {@link Control} unless * a {@code Control} instance is provided by * {@link ResourceBundleControlProvider} SPI. Refer to the @@ -2432,14 +2430,14 @@ public abstract class ResourceBundle { *- * getBundle(baseName, targetLocale, loader, control) - *
The following code lets {@code ResourceBundle.getBundle} look * up only properties-based resources. * - *
+ * {@snippet lang=java :
* import java.util.*;
* import static java.util.ResourceBundle.Control.*;
- * ...
+ * code: // @replace substring="code:" replacement="..."
* ResourceBundle bundle =
* ResourceBundle.getBundle("MyResources", Locale.forLanguageTag("fr-CH"),
* ResourceBundle.Control.getControl(FORMAT_PROPERTIES));
- *
+ * }
*
* Given the resource bundles in the example in
@@ -2456,10 +2454,10 @@ public abstract class ResourceBundle {
* using {@link Properties#loadFromXML(java.io.InputStream)
* Properties.loadFromXML}.
*
- *
+ * {@snippet lang=java :
* ResourceBundle rb = ResourceBundle.getBundle("Messages",
* new ResourceBundle.Control() {
- * public List<String> getFormats(String baseName) {
+ * public List getFormats(String baseName) {
* if (baseName == null)
* throw new NullPointerException();
* return Arrays.asList("xml");
@@ -2504,7 +2502,7 @@ public abstract class ResourceBundle {
* }
* });
*
- * ...
+ * code: // @replace substring="code:" replacement="..."
*
* private static class XMLResourceBundle extends ResourceBundle {
* private Properties props;
@@ -2515,11 +2513,11 @@ public abstract class ResourceBundle {
* protected Object handleGetObject(String key) {
* return props.getProperty(key);
* }
- * public Enumeration<String> getKeys() {
- * ...
+ * public Enumeration getKeys() {
+ * code: // @replace substring="code:" replacement="..."
* }
* }
- *
+ * }
*
* @apiNote {@code ResourceBundle.Control} is not supported
* in named modules. If the {@code ResourceBundle.getBundle} method with