Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8193817

Improve javadoc in ResourceBundle working with modules

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 10
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No behavioral change. The change improves the specification to refer to modules that cover both unnamed and name module case.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Update javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) to specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module.

      Problem

      The javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, ClassLoader loader) where loader is the caller's class loader. It's equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module. It is easier to understand the specification if it's updated to refer to the getBundle variant taking the module parameter.

      Solution

      Update javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) to specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module.

      In addition, the documentation (ResourceBundle, ResourceBundleProvider, and AbstractResourceBundleProvider class description) is improved to make it clear the several options in deploying resource bundles in modules.

      Specification

           /**
            * 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
      @@ -830,6 +846,9 @@
            * @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)
      
           /**
            * 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
      @@ -905,6 +920,9 @@
            * @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)

      Attached is the specdiff for the entire JDK-8193767 doc update which mostly documentation improvement and not a spec change.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                mchung Mandy Chung
                Reporter:
                mchung Mandy Chung
                Reviewed By:
                Alan Bateman, Naoto Sato
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: