291 * <p><strong>Usage model</strong>. To motivate the behavior of
292 * <code>add()</code> and <code>roll()</code>, consider a user interface
293 * component with increment and decrement buttons for the month, day, and
294 * year, and an underlying <code>GregorianCalendar</code>. If the
295 * interface reads January 31, 1999 and the user presses the month
296 * increment button, what should it read? If the underlying
297 * implementation uses <code>set()</code>, it might read March 3, 1999. A
298 * better result would be February 28, 1999. Furthermore, if the user
299 * presses the month increment button again, it should read March 31,
300 * 1999, not March 28, 1999. By saving the original date and using either
301 * <code>add()</code> or <code>roll()</code>, depending on whether larger
302 * fields should be affected, the user interface can behave as most users
303 * will intuitively expect.</p>
304 *
305 * @see java.lang.System#currentTimeMillis()
306 * @see Date
307 * @see GregorianCalendar
308 * @see TimeZone
309 * @see java.text.DateFormat
310 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
311 * @since JDK1.1
312 */
313 public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
314
315 // Data flow in Calendar
316 // ---------------------
317
318 // The current time is represented in two ways by Calendar: as UTC
319 // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
320 // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the
321 // millis from the fields, and vice versa. The data needed to do this
322 // conversion is encapsulated by a TimeZone object owned by the Calendar.
323 // The data provided by the TimeZone object may also be overridden if the
324 // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
325 // keeps track of what information was most recently set by the caller, and
326 // uses that to compute any other information as needed.
327
328 // If the user sets the fields using set(), the data flow is as follows.
329 // This is implemented by the Calendar subclass's computeTime() method.
330 // During this process, certain fields may be ignored. The disambiguation
331 // algorithm for resolving which fields to pay attention to is described
977 static final int currentSerialVersion = 1;
978
979 /**
980 * The version of the serialized data on the stream. Possible values:
981 * <dl>
982 * <dt><b>0</b> or not present on stream</dt>
983 * <dd>
984 * JDK 1.1.5 or earlier.
985 * </dd>
986 * <dt><b>1</b></dt>
987 * <dd>
988 * JDK 1.1.6 or later. Writes a correct 'time' value
989 * as well as compatible values for other fields. This is a
990 * transitional format.
991 * </dd>
992 * </dl>
993 * When streaming out this class, the most recent format
994 * and the highest allowable <code>serialVersionOnStream</code>
995 * is written.
996 * @serial
997 * @since JDK1.1.6
998 */
999 private int serialVersionOnStream = currentSerialVersion;
1000
1001 // Proclaim serialization compatibility with JDK 1.1
1002 static final long serialVersionUID = -1807547505821590642L;
1003
1004 // Mask values for calendar fields
1005 @SuppressWarnings("PointlessBitwiseExpression")
1006 final static int ERA_MASK = (1 << ERA);
1007 final static int YEAR_MASK = (1 << YEAR);
1008 final static int MONTH_MASK = (1 << MONTH);
1009 final static int WEEK_OF_YEAR_MASK = (1 << WEEK_OF_YEAR);
1010 final static int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
1011 final static int DAY_OF_MONTH_MASK = (1 << DAY_OF_MONTH);
1012 final static int DATE_MASK = DAY_OF_MONTH_MASK;
1013 final static int DAY_OF_YEAR_MASK = (1 << DAY_OF_YEAR);
1014 final static int DAY_OF_WEEK_MASK = (1 << DAY_OF_WEEK);
1015 final static int DAY_OF_WEEK_IN_MONTH_MASK = (1 << DAY_OF_WEEK_IN_MONTH);
1016 final static int AM_PM_MASK = (1 << AM_PM);
1017 final static int HOUR_MASK = (1 << HOUR);
|
291 * <p><strong>Usage model</strong>. To motivate the behavior of
292 * <code>add()</code> and <code>roll()</code>, consider a user interface
293 * component with increment and decrement buttons for the month, day, and
294 * year, and an underlying <code>GregorianCalendar</code>. If the
295 * interface reads January 31, 1999 and the user presses the month
296 * increment button, what should it read? If the underlying
297 * implementation uses <code>set()</code>, it might read March 3, 1999. A
298 * better result would be February 28, 1999. Furthermore, if the user
299 * presses the month increment button again, it should read March 31,
300 * 1999, not March 28, 1999. By saving the original date and using either
301 * <code>add()</code> or <code>roll()</code>, depending on whether larger
302 * fields should be affected, the user interface can behave as most users
303 * will intuitively expect.</p>
304 *
305 * @see java.lang.System#currentTimeMillis()
306 * @see Date
307 * @see GregorianCalendar
308 * @see TimeZone
309 * @see java.text.DateFormat
310 * @author Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu
311 * @since 1.1
312 */
313 public abstract class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
314
315 // Data flow in Calendar
316 // ---------------------
317
318 // The current time is represented in two ways by Calendar: as UTC
319 // milliseconds from the epoch (1 January 1970 0:00 UTC), and as local
320 // fields such as MONTH, HOUR, AM_PM, etc. It is possible to compute the
321 // millis from the fields, and vice versa. The data needed to do this
322 // conversion is encapsulated by a TimeZone object owned by the Calendar.
323 // The data provided by the TimeZone object may also be overridden if the
324 // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
325 // keeps track of what information was most recently set by the caller, and
326 // uses that to compute any other information as needed.
327
328 // If the user sets the fields using set(), the data flow is as follows.
329 // This is implemented by the Calendar subclass's computeTime() method.
330 // During this process, certain fields may be ignored. The disambiguation
331 // algorithm for resolving which fields to pay attention to is described
977 static final int currentSerialVersion = 1;
978
979 /**
980 * The version of the serialized data on the stream. Possible values:
981 * <dl>
982 * <dt><b>0</b> or not present on stream</dt>
983 * <dd>
984 * JDK 1.1.5 or earlier.
985 * </dd>
986 * <dt><b>1</b></dt>
987 * <dd>
988 * JDK 1.1.6 or later. Writes a correct 'time' value
989 * as well as compatible values for other fields. This is a
990 * transitional format.
991 * </dd>
992 * </dl>
993 * When streaming out this class, the most recent format
994 * and the highest allowable <code>serialVersionOnStream</code>
995 * is written.
996 * @serial
997 * @since 1.1.6
998 */
999 private int serialVersionOnStream = currentSerialVersion;
1000
1001 // Proclaim serialization compatibility with JDK 1.1
1002 static final long serialVersionUID = -1807547505821590642L;
1003
1004 // Mask values for calendar fields
1005 @SuppressWarnings("PointlessBitwiseExpression")
1006 final static int ERA_MASK = (1 << ERA);
1007 final static int YEAR_MASK = (1 << YEAR);
1008 final static int MONTH_MASK = (1 << MONTH);
1009 final static int WEEK_OF_YEAR_MASK = (1 << WEEK_OF_YEAR);
1010 final static int WEEK_OF_MONTH_MASK = (1 << WEEK_OF_MONTH);
1011 final static int DAY_OF_MONTH_MASK = (1 << DAY_OF_MONTH);
1012 final static int DATE_MASK = DAY_OF_MONTH_MASK;
1013 final static int DAY_OF_YEAR_MASK = (1 << DAY_OF_YEAR);
1014 final static int DAY_OF_WEEK_MASK = (1 << DAY_OF_WEEK);
1015 final static int DAY_OF_WEEK_IN_MONTH_MASK = (1 << DAY_OF_WEEK_IN_MONTH);
1016 final static int AM_PM_MASK = (1 << AM_PM);
1017 final static int HOUR_MASK = (1 << HOUR);
|