/*
* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Calendar;
import java.util.Locale;
import java.util.Map;
An abstract class for service providers that provide localized string representations (display names) of Calendar field values. Calendar types are used to specify calendar systems for which the getDisplayName and getDisplayNames methods provide calendar field value names. See Calendar.getCalendarType() for details.
Calendar Fields
Calendar fields are specified with the constants defined in Calendar. The following are calendar-common fields and their values to be supported for each calendar system.
Field values
Field
Value
Description
Calendar.MONTHCalendar.JANUARY to Calendar.UNDECIMBERMonth 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.
Calendar.DAY_OF_WEEKCalendar.SUNDAY to Calendar.SATURDAYDay-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday,
..., 7 - Saturday).
Calendar.AM_PMCalendar.AM to Calendar.PM0 - AM, 1 - PM
The following are calendar-specific fields and their values to be supported.
Calendar type and field values
Calendar Type
Field
Value
Description
"gregory"Calendar.ERA0
GregorianCalendar.BC (BCE)
1
GregorianCalendar.AD (CE)
"buddhist"Calendar.ERA0
BC (BCE)
1
B.E. (Buddhist Era)
"japanese"Calendar.ERA0
Seireki (Before Meiji)
1
Meiji
2
Taisho
3
Showa
4
Heisei
Calendar.YEAR1
the first year in each era. It should be returned when a long style (Calendar.LONG_FORMAT or Calendar.LONG_STANDALONE) is specified. See also the Year representation in SimpleDateFormat.
"roc"Calendar.ERA0
Before R.O.C.
1
R.O.C.
"islamic"Calendar.ERA0
Before AH
1
Anno Hijrah (AH)
Calendar field value names for "gregory" must be consistent with the date-time symbols provided by DateFormatSymbolsProvider.
Time zone names are supported by TimeZoneNameProvider.
Author: Masayoshi Okutsu See Also: Since: 1.8
/**
* An abstract class for service providers that provide localized string
* representations (display names) of {@code Calendar} field values.
*
* <p><a id="calendartypes"><b>Calendar Types</b></a>
*
* <p>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.
*
* <p><b>Calendar Fields</b>
*
* <p>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.
*
* <table class="striped">
* <caption style="display:none">Field values</caption>
* <thead>
* <tr>
* <th scope="col">Field</th>
* <th scope="col">Value</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#MONTH}</th>
* <td style="vertical-align:top">{@link Calendar#JANUARY} to {@link Calendar#UNDECIMBER}</td>
* <td>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.</td>
* </tr>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#DAY_OF_WEEK}</th>
* <td style="vertical-align:top">{@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}</td>
* <td>Day-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday,
* ..., 7 - Saturday).</td>
* </tr>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#AM_PM}</th>
* <td style="vertical-align:top">{@link Calendar#AM} to {@link Calendar#PM}</td>
* <td>0 - AM, 1 - PM</td>
* </tr>
* </tbody>
* </table>
*
* <p style="margin-top:20px">The following are calendar-specific fields and their values to be supported.
*
* <table class="plain">
* <caption style="display:none">Calendar type and field values</caption>
* <thead>
* <tr>
* <th scope="col">Calendar Type</th>
* <th scope="col">Field</th>
* <th scope="col">Value</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "gregory"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>{@link java.util.GregorianCalendar#BC} (BCE)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>{@link java.util.GregorianCalendar#AD} (CE)</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "buddhist"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>BC (BCE)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>B.E. (Buddhist Era)</td>
* </tr>
* <tr>
* <th scope="row" rowspan="6" style="font-weight:normal; text-align:left; vertical-align:top">{@code "japanese"}</th>
* <th scope="row" rowspan="5" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Seireki (Before Meiji)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>Meiji</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">2</th>
* <td>Taisho</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">3</th>
* <td>Showa</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">4</th>
* <td >Heisei</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#YEAR}</th>
* <th scope="row" style="font-weight:normal">1</th>
* <td>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 <a href="../../text/SimpleDateFormat.html#year">
* Year representation in {@code SimpleDateFormat}</a>.</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "roc"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Before R.O.C.</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>R.O.C.</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "islamic"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Before AH</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>Anno Hijrah (AH)</td>
* </tr>
* </tbody>
* </table>
*
* <p>Calendar field value names for {@code "gregory"} must be consistent with
* the date-time symbols provided by {@link java.text.spi.DateFormatSymbolsProvider}.
*
* <p>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.)
/**
* 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.
field is a Calendar field index, such as Calendar.MONTH. The time zone fields, Calendar.ZONE_OFFSET and Calendar.DST_OFFSET, are not supported by this method. null must be returned if any time zone fields are specified.
value is the numeric representation of the field value. For example, if field is Calendar.DAY_OF_WEEK, the valid values are Calendar.SUNDAY to Calendar.SATURDAY (inclusive).
style gives the style of the string representation. It is one of Calendar.SHORT_FORMAT (SHORT), Calendar.SHORT_STANDALONE, Calendar.LONG_FORMAT (LONG), Calendar.LONG_STANDALONE, Calendar.NARROW_FORMAT, or Calendar.NARROW_STANDALONE.
For example, the following call will return "Sunday".
getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
Calendar.LONG_STANDALONE, Locale.ENGLISH);
Params: - calendarType – the calendar type. (Any calendar type given by
locale is ignored.) - field – the
Calendar field index, such as Calendar.DAY_OF_WEEK - value – the value of the
Calendar field, such as Calendar.MONDAY - style – the string representation style: one of
Calendar.SHORT_FORMAT (SHORT), Calendar.SHORT_STANDALONE, Calendar.LONG_FORMAT (LONG), Calendar.LONG_STANDALONE, Calendar.NARROW_FORMAT, or Calendar.NARROW_STANDALONE - locale –
the desired locale
Throws: - IllegalArgumentException – if
field or style is invalid - NullPointerException – if
locale is null
See Also: Returns: the string representation of the field value, or
null if the string representation is not applicable or the given calendar type is unknown
/**
* Returns the string representation (display name) of the calendar
* <code>field value</code> in the given <code>style</code> and
* <code>locale</code>. If no string representation is
* applicable, <code>null</code> is returned.
*
* <p>{@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 <em>not</em> supported by this
* method. {@code null} must be returned if any time zone fields are
* specified.
*
* <p>{@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).
*
* <p>{@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}.
*
* <p>For example, the following call will return {@code "Sunday"}.
* <pre>
* getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
* Calendar.LONG_STANDALONE, Locale.ENGLISH);
* </pre>
*
* @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 Map containing all string representations (display names) of the Calendar field in the given style and locale and their corresponding field values. field is a Calendar field index, such as Calendar.MONTH. The time zone fields, Calendar.ZONE_OFFSET and Calendar.DST_OFFSET, are not supported by this method. null must be returned if any time zone fields are specified.
style gives the style of the string representation. It must be one of Calendar.ALL_STYLES, Calendar.SHORT_FORMAT (SHORT), Calendar.SHORT_STANDALONE, Calendar.LONG_FORMAT (LONG), Calendar.LONG_STANDALONE, Calendar.NARROW_FORMAT, or 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 Map containing "January" to Calendar.JANUARY, "Jan" to Calendar.JANUARY, "February" to Calendar.FEBRUARY, "Feb" to Calendar.FEBRUARY, and so on.
getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
Params: - calendarType – the calendar type. (Any calendar type given by
locale is ignored.) - field –
the calendar field for which the display names are returned
- style – the style applied to the display names; one of
Calendar.ALL_STYLES, Calendar.SHORT_FORMAT (SHORT), Calendar.SHORT_STANDALONE, Calendar.LONG_FORMAT (LONG), Calendar.LONG_STANDALONE, Calendar.NARROW_FORMAT, or Calendar.NARROW_STANDALONE - locale –
the desired locale
Throws: - NullPointerException – if
locale is null
See Also: Returns: a Map containing all display names of field in style and locale and their field values, or null if no display names are defined for field
/**
* 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.
*
* <p>{@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 <em>not</em> supported by this
* method. {@code null} must be returned if any time zone fields are specified.
*
* <p>{@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.
*
* <p>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.
* <pre>
* getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
* </pre>
*
* @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<String, Integer> getDisplayNames(String calendarType,
int field, int style,
Locale locale);
}