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

API: Calendar field time stamps



    • Type: Enhancement
    • Status: Closed
    • Priority: P4
    • Resolution: Won't Fix
    • Affects Version/s: 1.2.0
    • Fix Version/s: None
    • Component/s: core-libs
    • Labels:


      Name: bb33257 Date: 02/17/98

      Java API Change Request

       Name: Calendar field time stamps
       Priority: High
       Submitted On: 2/17/98
       Contact: Alan Liu, IBM JTC
                      ###@###.### 650-335-6651


      One of the functions of Calendar is to convert between two representations of a moment in time. One representation is milliseconds from the start
      of the epoch, January 1, 1970 0:00:00 GMT. This is the same representation used by Date, and is effectively equivalent to a Date object. The
      other representation is a set of seventeen fields representing numeric quantities such as the year, month, day of the month, day of the year, day of
      the week, and so forth, expressed within a local calendar system.

      Conversion from the milliseconds to the fields is unambiguous and does not present a problem. Conversion from fields to milliseconds is more
      difficult. Some or all of the fields may be set, and fields may not be set to consonant values. If insufficient fields are set, then the algorithm cannot
      determine the specified time. This problem is handled by assuming documented defaults; in general, these are those of the epoch start. E.g., iif
      only the MONTH field is set to March, then March 1, 1970 is assumed.

      What happens, however, if multiple fields are set, and these fields conflict? For instance, suppose the following fields are set:

           MONTH = January
           DAY_OF_MONTH = 15
           DAY_OF_YEAR = 32

      They specified date may either be January 15 or February 1, depending on which fields are obeyed.

      Calendar should disambiguate between the fields in this situation by using a most-recently modified algorithm. That is, if the sequence of calls

           cal.set(Calendar.MONTH, Calendar.JANUARY);
           cal.set(Calendar.DAY_OF_MONTH, 15);
           cal.set(Calendar.DAY_OF_YEAR, 32);

      then most users will expect the DAY_OF_YEAR to take precedence. On the other hand, if the sequence is:

           cal.set(Calendar.DAY_OF_YEAR, 32);
           cal.set(Calendar.MONTH, Calendar.JANUARY);
           cal.set(Calendar.DAY_OF_MONTH, 15);

      then most users will expect the Calendar to be set to January 15.

      Calendar doesn't do any computations itself; this is handled in concrete subclasses. In order to support this functionality, Calendar needs to have
      additional API which lets subclasses obtain the time stamp for a given field.

      Proposed API

      Add the following method and field to java.util.Calendar.

            * Return the pseudo-time-stamp indicating when this field was set.
            * @param field the field
            * @return a non-negative integer which is larger for fields set more recently.
            * A value of UNSET indicates that the field has not been set.
           protected int getTimeStamp(int field);

            * Special value returned by getTimeStamp() for fields which have not been set.
           protected static int UNSET;.



      Risk assessment

      API addition - minimal risk.

      SQE (product testing) impact

      JTC will contribute the unit tests for this new functionality.

      JCK (compatibility testing) impact

      New compatibility tests will be needed for this new API. They can be based on the unit tests from JTC.

      Doc impact

      Minor changes to the javadoc are sufficient documentation for this change.



          Issue Links



              okutsu Masayoshi Okutsu
              bcbeck Brian Beck (Inactive)
              0 Vote for this issue
              0 Start watching this issue