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.

        Issue Links

          Activity

          Hide
          darcy Joe Darcy added a comment -

          Moving to approved.

          Show
          darcy Joe Darcy added a comment - Moving to approved.
          Hide
          mchung Mandy Chung added a comment -

          This is a doc-only fix. Re-target and re-finalize this CSR to JDK 10.

          Show
          mchung Mandy Chung added a comment - This is a doc-only fix. Re-target and re-finalize this CSR to JDK 10.
          Hide
          darcy Joe Darcy added a comment -

          Re-approving the fix for JDK 10; I trust any additional approval procedures will be handled.

          Show
          darcy Joe Darcy added a comment - Re-approving the fix for JDK 10; I trust any additional approval procedures will be handled.
          Hide
          mchung Mandy Chung added a comment -

          It's a P3 noreg-doc fix that does not require additional approval.

          Show
          mchung Mandy Chung added a comment - It's a P3 noreg-doc fix that does not require additional approval.

            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: