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}. | *|
| {@code "roc"} | *{@link Calendar#ERA} | *0 | *Before R.O.C. | *
| 1 | *R.O.C. | *||
| {@code "islamic"} | *{@link Calendar#ERA} | *0 | *Before AH | *
| 1 | *Anno Hijrah (AH) | *
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 CalendarDataProvider
* @see Locale#getUnicodeLocaleType(String)
*/
public abstract class CalendarNameProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected CalendarNameProvider() {
}
/**
* 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}), {@link Calendar#LONG_STANDALONE}, * {@link Calendar#NARROW_FORMAT}, or {@link Calendar#NARROW_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}),
* {@link Calendar#LONG_STANDALONE},
* {@link Calendar#NARROW_FORMAT},
* or {@link Calendar#NARROW_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}), {@link * Calendar#LONG_STANDALONE}, {@link Calendar#NARROW_FORMAT}, or * {@link Calendar#NARROW_STANDALONE}. Note that narrow names may * not be unique due to use of single characters, such as "S" for Sunday * and Saturday, and that no narrow names are included in that case. * *
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}), {@link Calendar#LONG_STANDALONE},
* {@link Calendar#NARROW_FORMAT},
* or {@link Calendar#NARROW_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