jdk-sandbox: comparison src/java.base/share/classes/java/util/ResourceBundle.java

equal deleted inserted replaced

-:b95b08f3e1a8
+:b6fc9a193661
 * if it's simultaneously used by multiple threads. The default implementations
 * of the non-abstract methods in this class, and the methods in the direct
 * known concrete subclasses {@code ListResourceBundle} and
 * {@code PropertyResourceBundle} are thread-safe.
 *
-* <h3><a id="bundleprovider">Resource Bundles in Named Modules</a></h3>
+* <h3><a id="resource-bundle-modules">Resource Bundles and Named Modules</a></h3>
 *
-* When resource bundles are deployed in named modules, the following
+* Resource bundles can be deployed in modules in the following ways:
-* module-specific requirements and restrictions are applied.
+*
-*
+* <h4>Resource bundles together with an application</h4>
-* <ul>
+*
-* <li>Code in a named module that calls {@link #getBundle(String, Locale)}
+* Resource bundles can be deployed together with an application in the same
-* will locate resource bundles in the caller's module (<em>caller module</em>).</li>
+* module.  In that case, the resource bundles are loaded
-* <li>If resource bundles are deployed in named modules separate from
+* by code in the module by calling the {@link #getBundle(String)}
-* the caller module, those resource bundles need to be loaded from service
+* or {@link #getBundle(String, Locale)} method.
-* providers of {@link ResourceBundleProvider}. The caller module must declare
+*
-* "{@code uses}" and the service interface name is the concatenation of the
+* <h4><a id="service-providers">Resource bundles as service providers</a></h4>
-* package name of the base name, string "{@code .spi.}", the simple class
+*
-* name of the base name, and the string "{@code Provider}". The
+* Resource bundles can be deployed in one or more <em>service provider modules</em>
-* <em>bundle provider modules</em> containing resource bundles must
+* and they can be located using {@link ServiceLoader}.
-* declare "{@code provides}" with the service interface name and
+* A {@linkplain ResourceBundleProvider service} interface or class must be
-* its implementation class name. For example, if the base name is
+* defined. The caller module declares that it uses the service, the service
-* "{@code com.example.app.MyResources}", the caller module must declare
+* provider modules declare that they provide implementations of the service.
-* "{@code uses com.example.app.spi.MyResourcesProvider;}" and a module containing resource
+* Refer to {@link ResourceBundleProvider} for developing resource bundle
-* bundles must declare "{@code provides com.example.app.spi.MyResourcesProvider
+* services and deploying resource bundle providers.
-* with com.example.app.internal.MyResourcesProviderImpl;}"
+* The module obtaining the resource bundle can be a resource bundle
-* where {@code com.example.app.internal.MyResourcesProviderImpl} is an
+* provider itself; in which case this module only locates the resource bundle
-* implementation class of {@code com.example.app.spi.MyResourcesProvider}.</li>
+* via service provider mechanism.
-* <li>If you want to use non-standard formats in named modules, such as XML,
+*
-* {@link ResourceBundleProvider} needs to be used.</li>
+* <p>A {@linkplain ResourceBundleProvider resource bundle provider} can
-* <li>The {@code getBundle} method with a {@code ClassLoader} may not be able to
+* provide resource bundles in any format such XML which replaces the need
-* find resource bundles using the given {@code ClassLoader} in named modules.
+* of {@link Control ResourceBundle.Control}.
-* The {@code getBundle} method with a {@code Module} can be used, instead.</li>
+*
-* <li>{@code ResourceBundle.Control} is <em>not</em> supported in named modules.
+* <h4><a id="other-modules">Resource bundles in other modules and class path</a></h4>
-* If the {@code getBundle} method with a {@code ResourceBundle.Control} is called
+*
-* in a named module, the method will throw an {@code UnsupportedOperationException}.
+* Resource bundles in a named module may be <em>encapsulated</em> so that
-* Any service providers of {@link ResourceBundleControlProvider} are ignored in
+* it cannot be located by code in other modules.  Resource bundles
-* named modules.
+* in unnamed modules and class path are open for any module to access.
-* </li>
+* Resource bundle follows the resource encapsulation rules as specified
-* </ul>
+* in {@link Module#getResourceAsStream(String)}.
 *
-* <h3><a id="RBP_support">ResourceBundleProvider Service Providers</a></h3>
+* <p>The {@code getBundle} factory methods with no {@code Control} parameter
-*
+* locate and load resource bundles from
-* The {@code getBundle} factory methods load service providers of
+* {@linkplain ResourceBundleProvider service providers}.
-* {@link ResourceBundleProvider}, if available, using {@link ServiceLoader}.
+* It may continue the search as if calling {@link Module#getResourceAsStream(String)}
-* The service type is designated by
+* to find the named resource from a given module and calling
-* {@code <package name> + ".spi." + <simple name> + "Provider"}. For
+* {@link ClassLoader#getResourceAsStream(String)}; refer to
-* example, if the base name is "{@code com.example.app.MyResources}", the service
+* the specification of the {@code getBundle} method for details.
-* type is {@code com.example.app.spi.MyResourcesProvider}.
+* Only non-encapsulated resource bundles of "{@code java.class}"
-* <p>
+* or "{@code java.properties}" format are searched.
-* In named modules, the loaded service providers for the given base name are
+*
-* used to load resource bundles. If no service provider is available, or if
+* <p>If the caller module is a
-* none of the service providers returns a resource bundle and the caller module
+* <a href="{@docRoot}/java/util/spi/ResourceBundleProvider.html#obtain-resource-bundle">
-* doesn't have its own service provider, the {@code getBundle} factory method
+* resource bundle provider</a>, it does not fall back to the
-* searches for resource bundles that are local in the caller module and that
+* class loader search.
-* are visible to the class loader of the caller module.  The resource bundle
+*
-* formats for local module searching are "java.class" and "java.properties".
+* <h4>Resource bundles in automatic modules</h4>
+*
+* A common format of resource bundles is in {@linkplain PropertyResourceBundle
+* .properties} file format.  Typically {@code .properties} resource bundles
+* are packaged in a JAR file.  Resource bundle only JAR file can be readily
+* deployed as an <a href="{@docRoot}/java/lang/module/ModuleFinder.html#automatic-modules">
+* automatic module</a>.  For example, if the JAR file contains the
+* entry "{@code p/q/Foo_ja.properties}" and no {@code .class} entry,
+* when resolved and defined as an automatic module, no package is derived
+* for this module.  This allows resource bundles in {@code .properties}
+* format packaged in one or more JAR files that may contain entries
+* in the same directory and can be resolved successfully as
+* automatic modules.
 *
 * <h3>ResourceBundle.Control</h3>
 *
 * The {@link ResourceBundle.Control} class provides information necessary
 * to perform the bundle loading process by the <code>getBundle</code>
 * instance. You can implement your own subclass in order to enable
 * non-standard resource bundle formats, change the search strategy, or
 * define caching parameters. Refer to the descriptions of the class and the
 * {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}
 * factory method for details.
+*
+* <p> {@link ResourceBundle.Control} is designed for an application deployed
+* in an unnamed module, for example to support resource bundles in
+* non-standard formats or package localized resources in a non-traditional
+* convention. {@link ResourceBundleProvider} is the replacement for
+* {@code ResourceBundle.Control} when migrating to modules.
+* {@code UnsupportedOperationException} will be thrown when a factory
+* method that takes the {@code ResourceBundle.Control} parameter is called.
 *
 * <p><a id="modify_default_behavior">For the {@code getBundle} factory</a>
 * methods that take no {@link Control} instance, their <a
 * href="#default_behavior"> default behavior</a> of resource bundle loading
 * can be modified with custom {@link
 }
 }
 /**
 * Gets a resource bundle using the specified base name, the default locale,
-* and the caller's class loader. Calling this method is equivalent to calling
+* and the caller module. Calling this method is equivalent to calling
 * <blockquote>
-* <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>,
+* <code>getBundle(baseName, Locale.getDefault(), callerModule)</code>,
 * </blockquote>
-* except that <code>getClassLoader()</code> is run with the security
-* privileges of <code>ResourceBundle</code>.
-* See {@link #getBundle(String, Locale, ClassLoader) getBundle}
-* for a complete description of the search and instantiation strategy.
 *
 * @param baseName the base name of the resource bundle, a fully qualified class name
 * @exception java.lang.NullPointerException
 *     if <code>baseName</code> is <code>null</code>
 * @exception MissingResourceException
 *     if no resource bundle for the specified base name can be found
 * @return a resource bundle for the given base name and the default locale
+*
+* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
 */
 @CallerSensitive
 public static final ResourceBundle getBundle(String baseName)
 {
 Class<?> caller = Reflection.getCallerClass();
 return getBundleImpl(baseName, targetLocale, caller, control);
 }
 /**
 * Gets a resource bundle using the specified base name and locale,
-* and the caller's class loader. Calling this method is equivalent to calling
+* and the caller module. Calling this method is equivalent to calling
 * <blockquote>
-* <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>,
+* <code>getBundle(baseName, locale, callerModule)</code>,
 * </blockquote>
-* except that <code>getClassLoader()</code> is run with the security
-* privileges of <code>ResourceBundle</code>.
-* See {@link #getBundle(String, Locale, ClassLoader) getBundle}
-* for a complete description of the search and instantiation strategy.
 *
 * @param baseName
 *        the base name of the resource bundle, a fully qualified class name
 * @param locale
 *        the locale for which a resource bundle is desired
 * @exception NullPointerException
 *        if <code>baseName</code> or <code>locale</code> is <code>null</code>
 * @exception MissingResourceException
 *        if no resource bundle for the specified base name can be found
 * @return a resource bundle for the given base name and locale
+*
+* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
 */
 @CallerSensitive
 public static final ResourceBundle getBundle(String baseName,
 Locale locale)
 {
 * 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
 * <blockquote>
 * <code>getBundle(baseName, Locale.getDefault(), module)</code>
 * </blockquote>
-*
-* <p> Resource bundles in named modules may be encapsulated.  When
-* the resource bundle is loaded from a provider, the caller module
-* must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
-* to declare that the module uses implementations of
-* {@code <package name> + ".spi." + <simple name> + "Provider"}.
-* Otherwise, it will load the resource bundles that are local in the
-* given module or that are visible to the class loader of the given module
-* (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
-* section for details).
-* When the resource bundle is loaded from the specified module, it is
-* subject to the encapsulation rules specified by
-* {@link Module#getResourceAsStream Module.getResourceAsStream}.
 *
 * @param baseName the base name of the resource bundle,
 *                 a fully qualified class name
 * @param module   the module for which the resource bundle is searched
 * @throws NullPointerException
 *         specified module
 * @return a resource bundle for the given base name and the default locale
 * @since 9
 * @spec JPMS
 * @see ResourceBundleProvider
+* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
 */
 @CallerSensitive
 public static ResourceBundle getBundle(String baseName, Module module) {
 return getBundleFromModule(Reflection.getCallerClass(), module, baseName,
 Locale.getDefault(),
 /**
 * Gets a resource bundle using the specified base name and locale
 * on behalf of the specified module.
 *
 * <p> Resource bundles in named modules may be encapsulated.  When
-* the resource bundle is loaded from a provider, the caller module
+* the resource bundle is loaded from a
+* {@linkplain ResourceBundleProvider service provider}, the caller module
 * must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
-* to declare that the module uses implementations of
+* to declare that the module uses of {@link ResourceBundleProvider}
-* {@code <package name> + ".spi." + <simple name> + "Provider"}.
+* for the named resource bundle.
 * Otherwise, it will load the resource bundles that are local in the
-* given module or that are visible to the class loader of the given module
+* given module as if calling {@link Module#getResourceAsStream(String)}
-* (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
+* or that are visible to the class loader of the given module
-* section for details).
+* as if calling {@link ClassLoader#getResourceAsStream(String)}.
 * When the resource bundle is loaded from the specified module, it is
 * subject to the encapsulation rules specified by
 * {@link Module#getResourceAsStream Module.getResourceAsStream}.
 *
 * <p>
 *         if no resource bundle for the specified base name and locale can
 *         be found in the specified {@code module}
 * @return a resource bundle for the given base name and locale in the module
 * @since 9
 * @spec JPMS
+* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
 */
 @CallerSensitive
 public static ResourceBundle getBundle(String baseName, Locale targetLocale, Module module) {
 return getBundleFromModule(Reflection.getCallerClass(), module, baseName, targetLocale,
 getDefaultControl(module, baseName));
 /**
 * Gets a resource bundle using the specified base name, locale, and class
 * loader.
 *
-* <p>This method behaves the same as calling
+* <p>When this method is called from a named module and the given
-* {@link #getBundle(String, Locale, ClassLoader, Control)} passing a
+* loader is the class loader of the caller module, this is equivalent
-* default instance of {@link Control} unless another {@link Control} is
+* to calling:
-* provided with the {@link ResourceBundleControlProvider} SPI. Refer to the
+* <blockquote><pre>
+* getBundle(baseName, targetLocale, callerModule)
+* </pre></blockquote>
+*
+* otherwise, this is equivalent to calling:
+* <blockquote><pre>
+* getBundle(baseName, targetLocale, loader, control)
+* </pre></blockquote>
+* where {@code control} is the default instance of {@link Control} unless
+* a {@code Control} instance is provided by
+* {@link ResourceBundleControlProvider} SPI.  Refer to the
 * description of <a href="#modify_default_behavior">modifying the default
-* behavior</a>.
+* behavior</a>. The following describes the default behavior.
-*
-* <p><a id="default_behavior">The following describes the default
-* behavior</a>.
 *
 * <p>
-* Resource bundles in a named module are private to that module.  If
+* <b><a id="default_behavior">Resource Bundle Search and Loading Strategy</a></b>
-* the caller is in a named module, this method will find resource bundles
-* from the service providers of {@link java.util.spi.ResourceBundleProvider}
-* if any. Otherwise, it will load the resource bundles that are visible to
-* the given {@code loader} (refer to the
-* <a href="#bundleprovider">Resource Bundles in Named Modules</a> section
-* for details).
-* If the caller is in a named module and the given {@code loader} is
-* different than the caller's class loader, or if the caller is not in
-* a named module, this method will not find resource bundles from named
-* modules.
 *
 * <p><code>getBundle</code> uses the base name, the specified locale, and
 * the default locale (obtained from {@link java.util.Locale#getDefault()
 * Locale.getDefault}) to generate a sequence of <a
 * id="candidates"><em>candidate bundle names</em></a>.  If the specified
 * <p><b>Note:</b> <code>getBundle</code> caches instantiated resource
 * bundles and might return the same resource bundle instance multiple times.
 *
 * <p><b>Note:</b>The <code>baseName</code> argument should be a fully
 * qualified class name. However, for compatibility with earlier versions,
-* Sun's Java SE Runtime Environments do not verify this, and so it is
+* Java SE Runtime Environments do not verify this, and so it is
 * possible to access <code>PropertyResourceBundle</code>s by specifying a
 * path name (using "/") instead of a fully qualified class name (using
 * ".").
 *
 * <p><a id="default_behavior_example">
 * hidden by the MyResources_fr_CH.class. Likewise, MyResources.properties
 * is also hidden by MyResources.class.
 *
 * @apiNote If the caller module is a named module and the given
 * {@code loader} is the caller module's class loader, this method is
-* equivalent to {@code getBundle(baseName, locale)}; otherwise, it will not
+* equivalent to {@code getBundle(baseName, locale)}; otherwise, it may not
 * find resource bundles from named modules.
 * Use {@link #getBundle(String, Locale, Module)} to load resource bundles
 * on behalf on a specific module instead.
 *
 * @param baseName the base name of the resource bundle, a fully qualified class name
 * @exception MissingResourceException
 *        if no resource bundle for the specified base name can be found
 * @since 1.2
 * @revised 9
 * @spec JPMS
+* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
 */
 @CallerSensitive
 public static ResourceBundle getBundle(String baseName, Locale locale,
 ClassLoader loader)
 {
 return getBundleImpl(baseName, locale, caller, loader, getDefaultControl(caller, baseName));
 }
 /**
 * Returns a resource bundle using the specified base name, target
-* locale, class loader and control. Unlike the {@linkplain
+* locale, class loader and control. Unlike the {@link
-* #getBundle(String, Locale, ClassLoader) <code>getBundle</code>
+* #getBundle(String, Locale, ClassLoader) getBundle}
-* factory methods with no <code>control</code> argument}, the given
+* factory methods with no {@code control} argument, the given
 * <code>control</code> specifies how to locate and instantiate resource
 * bundles. Conceptually, the bundle loading process with the given
 * <code>control</code> is performed in the following steps.
 *
 * <ol>
 * <code>ResourceBundle.Control</code> collaborates with the factory
 * methods for loading resource bundles. The default implementation of
 * the callback methods provides the information necessary for the
 * factory methods to perform the <a
 * href="./ResourceBundle.html#default_behavior">default behavior</a>.
-* <a href="#note">Note that this class is not supported in named modules.</a>
+*
+* <p> {@link ResourceBundle.Control} is designed for an application deployed
+* in an unnamed module, for example to support resource bundles in
+* non-standard formats or package localized resources in a non-traditional
+* convention. {@link ResourceBundleProvider} is the replacement for
+* {@code ResourceBundle.Control} when migrating to modules.
+* {@code UnsupportedOperationException} will be thrown when a factory
+* method that takes the {@code ResourceBundle.Control} parameter is called.
 *
 * <p>In addition to the callback methods, the {@link
 * #toBundleName(String, Locale) toBundleName} and {@link
 * #toResourceName(String, String) toResourceName} methods are defined
 * primarily for convenience in implementing the callback
 *         ...
 *     }
 * }
 * </pre>
 *
-* @apiNote <a id="note">{@code ResourceBundle.Control} is not supported
+* @apiNote {@code ResourceBundle.Control} is not supported
-* in named modules.</a> If the {@code ResourceBundle.getBundle} method with
+* in named modules. If the {@code ResourceBundle.getBundle} method with
 * a {@code ResourceBundle.Control} is called in a named module, the method
 * will throw an {@link UnsupportedOperationException}. Any service providers
 * of {@link ResourceBundleControlProvider} are ignored in named modules.
 *
 * @since 1.6

changeset 48524	b6fc9a193661
parent 47478	438e0c9f2f17
child 48591	ca245f9f70db