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

[Doc] Wrong Months Array for DateFormatSymbols

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Clarify the API Doc of DateFormatSymbols.getMonths/getShortMonths to describe the 13th element returned in the months array.

      Problem

      DateFormatSymbols class was designed considering future support for Lunisolar Calendar Systems, such as Chinese which have 13th Month such as Calendar.UNDECIMBER. For other calendar systems, this 13th month name will be an empty string. Thus, methods getMonths() and getShortMonths() return an empty string as 13th element for other calendar systems. However, this is perceived as a bug from end user.

      Solution

      Solution is to clarify API Doc of DateFormatSymbols's methods getMonths() and getShortMonths().

      Specification

      Here is the proposed spec change :

      changing specification of java.text.DateFormatSymbols.getMonths()

      from:

       /**
        * Gets month strings. For example: "January", "February", etc.
        *
        * <p>If the language requires different forms for formatting and
        * stand-alone usages, this method returns month names in the
        * Calendar Elements in the Unicode Locale Data Markup Language
        * (LDML) specification</a> for more details.
        *
        * @return the month strings. Use
        * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
        * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
        * etc. to index the result array. 
        */

      to

                 /**
                 * Gets month strings. For example: "January", "February", etc.
      +         * An array with either 12 or 13 elements will be returned depending
      +         * on whether or not {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER}
      +         * is supported. Use
      +         * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
      +         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
      +         * etc. to index the result array.
                *
                * <p>If the language requires different forms for formatting and
                * stand-alone usages, this method returns month names in the
                * Calendar Elements in the Unicode Locale Data Markup Language
                * (LDML) specification</a> for more details.
                *
                * @return the month strings.
      -         * Use {@link java.util.Calendar#JANUARY Calendar.JANUARY},
      -         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
      -         * etc. to index the result array.
      +         * @implSpec This method returns 13 elements since 
      +         * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported.
      +         * @return the month strings. 
                 */

      Changing specification of java.text.DateFormatSymbols.getShortMonths() from

      from:

       /**
        * Gets short month strings. For example: "January", "February", etc.
        *
        * <p>If the language requires different forms for formatting and
        * stand-alone usages, this method returns short month names in the
        * Calendar Elements in the Unicode Locale Data Markup Language
        * (LDML) specification</a> for more details.
        *
        * @return the short month strings. Use
        * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
        * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
        * etc. to index the result array. 
        */

      to

                 /**
                 * Gets short month strings. For example: "January", "February", etc.
      +         * An array with either 12 or 13 elements will be returned depending
      +         * on whether or not {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER}
      +         * is supported. Use
      +         * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
      +         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
      +         * etc. to index the result array.
                *
                * <p>If the language requires different forms for formatting and
                * stand-alone usages, this method returns short month names in the
                * Calendar Elements in the Unicode Locale Data Markup Language
                * (LDML) specification</a> for more details.
                *
                * @return the short month strings.
      -         * Use  {@link java.util.Calendar#JANUARY Calendar.JANUARY},
      -         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
      -         * etc. to index the result array.
      +         * @implSpec This method returns 13 elements since 
      +         * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported.
      +         * @return the month strings. 
                 */

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                rgoel Rachna Goel (Inactive)
                Reporter:
                webbuggrp Webbug Group
                Reviewed By:
                Naoto Sato
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: