Calendar Types + * + *
Calendar types are used to specify calendar systems for which the {@link + * #getDisplayName(String, int, int, int, Locale) getDisplayName} and {@link + * #getDisplayNames(String, int, int, Locale) getDisplayNames} methods provide + * calendar field value names. See {@link Calendar#getCalendarType()} for details. + * + *
Calendar Fields + * + *
Calendar fields are specified with the constants defined in {@link + * Calendar}. The following are calendar-common fields and their values to be + * supported for each calendar system. + * + *
| Field | + *Value | + *Description | + *
|---|---|---|
| {@link Calendar#MONTH} | + *{@link Calendar#JANUARY} to {@link Calendar#UNDECIMBER} | + *Month numbering is 0-based (e.g., 0 - January, ..., 11 - + * December). Some calendar systems have 13 months. Month + * names need to be supported in both the formatting and + * stand-alone forms if required by the supported locales. If there's + * no distinction in the two forms, the same names should be returned + * in both of the forms. | + *
| {@link Calendar#DAY_OF_WEEK} | + *{@link Calendar#SUNDAY} to {@link Calendar#SATURDAY} | + *Day-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday, + * ..., 7 - Saturday). | + *
| {@link Calendar#AM_PM} | + *{@link Calendar#AM} to {@link Calendar#PM} | + *0 - AM, 1 - PM | + *
The following are calendar-specific fields and their values to be supported. + * + *
| Calendar Type | + *Field | + *Value | + *Description | + *
|---|---|---|---|
| {@code "gregory"} | + *{@link Calendar#ERA} | + *0 | + *{@link java.util.GregorianCalendar#BC} (BCE) | + *
| 1 | + *{@link java.util.GregorianCalendar#AD} (CE) | + *||
| {@code "buddhist"} | + *{@link Calendar#ERA} | + *0 | + *BC (BCE) | + *
| 1 | + *B.E. (Buddhist Era) | + *||
| {@code "japanese"} | + *{@link Calendar#ERA} | + *0 | + *Seireki (Before Meiji) | + *
| 1 | + *Meiji | + *||
| 2 | + *Taisho | + *||
| 3 | + *Showa | + *||
| 4 | + *Heisei | + *||
| {@link Calendar#YEAR} | + *1 | + *the first year in each era. It should be returned when a long + * style ({@link Calendar#LONG_FORMAT} or {@link Calendar#LONG_STANDALONE}) is + * specified. See also the + * Year representation in {@code SimpleDateFormat}. | + *
Calendar field value names for {@code "gregory"} must be consistent with + * the date-time symbols provided by {@link java.text.spi.DateFormatSymbolsProvider}. + * + *
Time zone names are supported by {@link TimeZoneNameProvider}.
+ *
+ * @author Masayoshi Okutsu
+ * @since 1.8
+ * @see Locale#getUnicodeLocaleType(String)
+ */
+public abstract class CalendarDataProvider extends LocaleServiceProvider {
+
+ /**
+ * Sole constructor. (For invocation by subclass constructors, typically
+ * implicit.)
+ */
+ protected CalendarDataProvider() {
+ }
+
+ /**
+ * Returns the first day of a week in the given {@code locale}. This
+ * information is required by {@link Calendar} to support operations on the
+ * week-related calendar fields.
+ *
+ * @param locale
+ * the desired locale
+ * @return the first day of a week; one of {@link Calendar#SUNDAY} ..
+ * {@link Calendar#SATURDAY},
+ * or 0 if the value isn't available for the {@code locale}
+ * @throws NullPointerException
+ * if {@code locale} is {@code null}.
+ * @see java.util.Calendar#getFirstDayOfWeek()
+ * @see First Week
+ */
+ public abstract int getFirstDayOfWeek(Locale locale);
+
+ /**
+ * Returns the minimal number of days required in the first week of a
+ * year. This information is required by {@link Calendar} to determine the
+ * first week of a year. Refer to the description of how {@code Calendar} determines
+ * the first week.
+ *
+ * @param locale
+ * the desired locale
+ * @return the minimal number of days of the first week,
+ * or 0 if the value isn't available for the {@code locale}
+ * @throws NullPointerException
+ * if {@code locale} is {@code null}.
+ * @see java.util.Calendar#getMinimalDaysInFirstWeek()
+ */
+ public abstract int getMinimalDaysInFirstWeek(Locale locale);
+
+ /**
+ * Returns the string representation (display name) of the calendar
+ * field value in the given style and
+ * locale. If no string representation is
+ * applicable, null is returned.
+ *
+ *
{@code field} is a {@code Calendar} field index, such as {@link + * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and + * {@link Calendar#DST_OFFSET}, are not supported by this + * method. {@code null} must be returned if any time zone fields are + * specified. + * + *
{@code value} is the numeric representation of the {@code field} value. + * For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid + * values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY} + * (inclusive). + * + *
{@code style} gives the style of the string representation. It is one + * of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}), + * {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT} + * ({@link Calendar#LONG LONG}), or {@link Calendar#LONG_STANDALONE}. + * + *
For example, the following call will return {@code "Sunday"}. + *
+ * getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
+ * Calendar.LONG_STANDALONE, Locale.ENGLISH);
+ *
+ *
+ * @param calendarType
+ * the calendar type. (Any calendar type given by {@code locale}
+ * is ignored.)
+ * @param field
+ * the {@code Calendar} field index,
+ * such as {@link Calendar#DAY_OF_WEEK}
+ * @param value
+ * the value of the {@code Calendar field},
+ * such as {@link Calendar#MONDAY}
+ * @param style
+ * the string representation style: one of {@link
+ * Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
+ * {@link Calendar#SHORT_STANDALONE}, {@link
+ * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), or
+ * {@link Calendar#LONG_STANDALONE}
+ * @param locale
+ * the desired locale
+ * @return the string representation of the {@code field value}, or {@code
+ * null} if the string representation is not applicable or
+ * the given calendar type is unknown
+ * @throws IllegalArgumentException
+ * if {@code field} or {@code style} is invalid
+ * @throws NullPointerException if {@code locale} is {@code null}
+ * @see TimeZoneNameProvider
+ * @see java.util.Calendar#get(int)
+ * @see java.util.Calendar#getDisplayName(int, int, Locale)
+ */
+ public abstract String getDisplayName(String calendarType,
+ int field, int value,
+ int style, Locale locale);
+
+ /**
+ * Returns a {@code Map} containing all string representations (display
+ * names) of the {@code Calendar} {@code field} in the given {@code style}
+ * and {@code locale} and their corresponding field values.
+ *
+ * {@code field} is a {@code Calendar} field index, such as {@link + * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and + * {@link Calendar#DST_OFFSET}, are not supported by this + * method. {@code null} must be returned if any time zone fields are specified. + * + *
{@code style} gives the style of the string representation. It must be + * one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link + * Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link + * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), or {@link + * Calendar#LONG_STANDALONE}. + * + *
For example, the following call will return a {@code Map} containing + * {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link + * Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY}, + * {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on. + *
+ * getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
+ *
+ *
+ * @param calendarType
+ * the calendar type. (Any calendar type given by {@code locale}
+ * is ignored.)
+ * @param field
+ * the calendar field for which the display names are returned
+ * @param style
+ * the style applied to the display names; one of
+ * {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT}
+ * ({@link Calendar#SHORT SHORT}), {@link
+ * Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
+ * ({@link Calendar#LONG LONG}), or {@link
+ * Calendar#LONG_STANDALONE}.
+ * @param locale
+ * the desired locale
+ * @return a {@code Map} containing all display names of {@code field} in
+ * {@code style} and {@code locale} and their {@code field} values,
+ * or {@code null} if no display names are defined for {@code field}
+ * @throws NullPointerException
+ * if {@code locale} is {@code null}
+ * @see Calendar#getDisplayNames(int, int, Locale)
+ */
+ public abstract Map