public abstract class

CalendarSystem

extends Object
java.lang.Object
   ↳ sun.util.calendar.CalendarSystem
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

CalendarSystem is an abstract class that defines the programming interface to deal with calendar date and time.

CalendarSystem instances are singletons. For example, there exists only one Gregorian calendar instance in the Java runtime environment. A singleton instance can be obtained calling one of the static factory methods.

CalendarDate

For the methods in a CalendarSystem that manipulate a CalendarDate, CalendarDates that have been created by the CalendarSystem must be specified. Otherwise, the methods throw an exception. This is because, for example, a Chinese calendar date can't be understood by the Hebrew calendar system.

Calendar names

Each calendar system has a unique name to be identified. The Java runtime in this release supports the following calendar systems. 
  Name          Calendar System
  ---------------------------------------
  gregorian     Gregorian Calendar
  julian        Julian Calendar
  japanese      Japanese Imperial Calendar

See Also

Summary

Public Constructors
CalendarSystem()
Public Methods
static CalendarSystem forName(String calendarName)
Returns a CalendarSystem specified by the calendar name.
abstract CalendarDate getCalendarDate(long millis)
Calculates calendar fields from the specified number of milliseconds since the Epoch, January 1, 1970 00:00:00 UTC (Gregorian).
abstract CalendarDate getCalendarDate(long millis, CalendarDate date)
abstract CalendarDate getCalendarDate(long millis, TimeZone zone)
abstract CalendarDate getCalendarDate()
abstract Era getEra(String eraName)
Returns the Era designated by the era name that has to be known to this calendar system.
abstract Era[] getEras()
Returns valid Eras of this calendar system.
static Gregorian getGregorianCalendar()
Returns the singleton instance of the Gregorian calendar system.
abstract int getMonthLength(CalendarDate date)
Returns the length in days of the month specified by the calendar date.
abstract String getName()
Returns the name of this calendar system.
abstract CalendarDate getNthDayOfWeek(int nth, int dayOfWeek, CalendarDate date)
Returns a CalendarDate of the n-th day of week which is on, after or before the specified date.
abstract long getTime(CalendarDate date)
Returns the number of milliseconds since the Epoch, January 1, 1970 00:00:00 UTC (Gregorian), represented by the specified CalendarDate.
abstract int getWeekLength()
Returns the length in days of a week in this calendar system.
abstract int getYearLength(CalendarDate date)
Returns the length in days of the specified year by date.
abstract int getYearLengthInMonths(CalendarDate date)
Returns the number of months of the specified year.
abstract CalendarDate newCalendarDate()
Constructs a CalendarDate that is specific to this calendar system.
abstract CalendarDate newCalendarDate(TimeZone zone)
abstract boolean normalize(CalendarDate date)
Normalizes calendar fields in the specified date.
abstract void setEra(CalendarDate date, String eraName)
abstract CalendarDate setTimeOfDay(CalendarDate date, int timeOfDay)
abstract boolean validate(CalendarDate date)
Checks whether the calendar fields specified by date represents a valid date and time in this calendar system.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public CalendarSystem ()

Public Methods

public static CalendarSystem forName (String calendarName)

Returns a CalendarSystem specified by the calendar name. The calendar name has to be one of the supported calendar names.

Parameters
calendarName the calendar name
Returns
  • the CalendarSystem specified by calendarName, or null if there is no CalendarSystem associated with the given calendar name.

public abstract CalendarDate getCalendarDate (long millis)

Calculates calendar fields from the specified number of milliseconds since the Epoch, January 1, 1970 00:00:00 UTC (Gregorian). This method doesn't check overflow or underflow when adjusting the millisecond value (representing UTC) with the time zone offsets (i.e., the GMT offset and amount of daylight saving).

Parameters
millis the offset value in milliseconds from January 1, 1970 00:00:00 UTC (Gregorian).
Returns
  • a CalendarDate instance that contains the calculated calendar field values.

public abstract CalendarDate getCalendarDate (long millis, CalendarDate date)

public abstract CalendarDate getCalendarDate (long millis, TimeZone zone)

public abstract CalendarDate getCalendarDate ()

public abstract Era getEra (String eraName)

Returns the Era designated by the era name that has to be known to this calendar system. If no Era is applicable to this calendar system, null is returned.

Parameters
eraName the name of the era
Returns
  • the Era designated by eraName, or null if no Era is applicable to this calendar system or the specified era name is not known to this calendar system.

public abstract Era[] getEras ()

Returns valid Eras of this calendar system. The return value is sorted in the descendant order. (i.e., the first element of the returned array is the oldest era.) If no era is applicable to this calendar system, null is returned.

Returns
  • an array of valid Eras, or null if no era is applicable to this calendar system.

public static Gregorian getGregorianCalendar ()

Returns the singleton instance of the Gregorian calendar system.

Returns
  • the Gregorian instance

public abstract int getMonthLength (CalendarDate date)

Returns the length in days of the month specified by the calendar date. This method does not perform the normalization with the specified calendar date. The CalendarDate must be normalized to get a correct value.

Parameters
date the date from which the month value is obtained
Returns
  • the number of days in the month
Throws
IllegalArgumentException if the specified calendar date doesn't have a valid month value in this calendar system.

public abstract String getName ()

Returns the name of this calendar system.

public abstract CalendarDate getNthDayOfWeek (int nth, int dayOfWeek, CalendarDate date)

Returns a CalendarDate of the n-th day of week which is on, after or before the specified date. For example, the first Sunday in April 2002 (Gregorian) can be obtained as below: 


 Gregorian cal = CalendarSystem.getGregorianCalendar();
 CalendarDate date = cal.newCalendarDate();
 date.setDate(2004, cal.APRIL, 1);
 CalendarDate firstSun = cal.getNthDayOfWeek(1, cal.SUNDAY, date);
 // firstSun represents April 4, 2004.
This method returns a new CalendarDate instance and doesn't modify the original date.

Parameters
nth specifies the n-th one. A positive number specifies on or after the date. A non-positive number specifies on or before the date.
dayOfWeek the day of week
date the date
Returns
  • the date of the nth dayOfWeek after or before the specified CalendarDate

public abstract long getTime (CalendarDate date)

Returns the number of milliseconds since the Epoch, January 1, 1970 00:00:00 UTC (Gregorian), represented by the specified CalendarDate.

Parameters
date the CalendarDate from which the time value is calculated
Returns
  • the number of milliseconds since the Epoch.

public abstract int getWeekLength ()

Returns the length in days of a week in this calendar system. If this calendar system has multiple radix weeks, this method returns only one of them.

public abstract int getYearLength (CalendarDate date)

Returns the length in days of the specified year by date. This method does not perform the normalization with the specified CalendarDate. The CalendarDate must be normalized to get a correct value.

public abstract int getYearLengthInMonths (CalendarDate date)

Returns the number of months of the specified year. This method does not perform the normalization with the specified CalendarDate. The CalendarDate must be normalized to get a correct value.

public abstract CalendarDate newCalendarDate ()

Constructs a CalendarDate that is specific to this calendar system. All calendar fields have their initial values. The default time zone is set to the instance.

Returns
  • a CalendarDate instance that contains the initial calendar field values.

public abstract CalendarDate newCalendarDate (TimeZone zone)

public abstract boolean normalize (CalendarDate date)

Normalizes calendar fields in the specified date. Also all undefined fields are set to correct values. The actual normalization process is calendar system dependent.

Parameters
date the calendar date to be validated
Returns
  • true if all fields have been normalized; false otherwise.
Throws
NullPointerException if the specified date is null

public abstract void setEra (CalendarDate date, String eraName)

Throws
IllegalArgumentException if the specified era name is unknown to this calendar system.
See Also

public abstract CalendarDate setTimeOfDay (CalendarDate date, int timeOfDay)

public abstract boolean validate (CalendarDate date)

Checks whether the calendar fields specified by date represents a valid date and time in this calendar system. If the given date is valid, date is marked as normalized.

Parameters
date the CalendarDate to be validated
Returns
  • true if all the calendar fields are consistent, otherwise, false is returned.
Throws
NullPointerException if the specified date is null