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


Background

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
was:

     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;.

Implementation

Simple.

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.

======================================================================