1 /*
2 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util.spi;
27
28 import java.util.Calendar;
29 import java.util.Locale;
30 import java.util.Map;
31
32 /**
33 * An abstract class for service providers that provide localized string
34 * representations (display names) of {@code Calendar} field values.
35 *
36 * <p><a id="calendartypes"><b>Calendar Types</b></a>
37 *
38 * <p>Calendar types are used to specify calendar systems for which the {@link
39 * #getDisplayName(String, int, int, int, Locale) getDisplayName} and {@link
40 * #getDisplayNames(String, int, int, Locale) getDisplayNames} methods provide
41 * calendar field value names. See {@link Calendar#getCalendarType()} for details.
42 *
43 * <p><b>Calendar Fields</b>
44 *
45 * <p>Calendar fields are specified with the constants defined in {@link
46 * Calendar}. The following are calendar-common fields and their values to be
47 * supported for each calendar system.
48 *
49 * <table style="border-bottom:1px solid" border="1" cellpadding="3" cellspacing="0" summary="Field values">
50 * <tr>
51 * <th>Field</th>
52 * <th>Value</th>
53 * <th>Description</th>
54 * </tr>
55 * <tr>
56 * <td valign="top">{@link Calendar#MONTH}</td>
57 * <td valign="top">{@link Calendar#JANUARY} to {@link Calendar#UNDECIMBER}</td>
58 * <td>Month numbering is 0-based (e.g., 0 - January, ..., 11 -
59 * December). Some calendar systems have 13 months. Month
60 * names need to be supported in both the formatting and
61 * stand-alone forms if required by the supported locales. If there's
62 * no distinction in the two forms, the same names should be returned
63 * in both of the forms.</td>
64 * </tr>
65 * <tr>
66 * <td valign="top">{@link Calendar#DAY_OF_WEEK}</td>
67 * <td valign="top">{@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}</td>
68 * <td>Day-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday,
69 * ..., 7 - Saturday).</td>
70 * </tr>
71 * <tr>
72 * <td valign="top">{@link Calendar#AM_PM}</td>
73 * <td valign="top">{@link Calendar#AM} to {@link Calendar#PM}</td>
74 * <td>0 - AM, 1 - PM</td>
75 * </tr>
76 * </table>
77 *
78 * <p style="margin-top:20px">The following are calendar-specific fields and their values to be supported.
79 *
80 * <table style="border-bottom:1px solid" border="1" cellpadding="3" cellspacing="0" summary="Calendar type and field values">
81 * <tr>
82 * <th>Calendar Type</th>
83 * <th>Field</th>
84 * <th>Value</th>
85 * <th>Description</th>
86 * </tr>
87 * <tr>
88 * <td rowspan="2" valign="top">{@code "gregory"}</td>
89 * <td rowspan="2" valign="top">{@link Calendar#ERA}</td>
90 * <td>0</td>
91 * <td>{@link java.util.GregorianCalendar#BC} (BCE)</td>
92 * </tr>
93 * <tr>
94 * <td>1</td>
95 * <td>{@link java.util.GregorianCalendar#AD} (CE)</td>
96 * </tr>
97 * <tr>
98 * <td rowspan="2" valign="top">{@code "buddhist"}</td>
99 * <td rowspan="2" valign="top">{@link Calendar#ERA}</td>
100 * <td>0</td>
101 * <td>BC (BCE)</td>
102 * </tr>
103 * <tr>
104 * <td>1</td>
105 * <td>B.E. (Buddhist Era)</td>
106 * </tr>
107 * <tr>
108 * <td rowspan="6" valign="top">{@code "japanese"}</td>
109 * <td rowspan="5" valign="top">{@link Calendar#ERA}</td>
110 * <td>0</td>
111 * <td>Seireki (Before Meiji)</td>
112 * </tr>
113 * <tr>
114 * <td>1</td>
115 * <td>Meiji</td>
116 * </tr>
117 * <tr>
118 * <td>2</td>
119 * <td>Taisho</td>
120 * </tr>
121 * <tr>
122 * <td>3</td>
123 * <td>Showa</td>
124 * </tr>
125 * <tr>
126 * <td>4</td>
127 * <td >Heisei</td>
128 * </tr>
129 * <tr>
130 * <td>{@link Calendar#YEAR}</td>
131 * <td>1</td>
132 * <td>the first year in each era. It should be returned when a long
133 * style ({@link Calendar#LONG_FORMAT} or {@link Calendar#LONG_STANDALONE}) is
134 * specified. See also the <a href="../../text/SimpleDateFormat.html#year">
135 * Year representation in {@code SimpleDateFormat}</a>.</td>
136 * </tr>
137 * <tr>
138 * <td rowspan="2" valign="top">{@code "roc"}</td>
139 * <td rowspan="2" valign="top">{@link Calendar#ERA}</td>
140 * <td>0</td>
141 * <td>Before R.O.C.</td>
142 * </tr>
143 * <tr>
144 * <td>1</td>
145 * <td>R.O.C.</td>
146 * </tr>
147 * <tr>
148 * <td rowspan="2" valign="top">{@code "islamic"}</td>
149 * <td rowspan="2" valign="top">{@link Calendar#ERA}</td>
150 * <td>0</td>
151 * <td>Before AH</td>
152 * </tr>
153 * <tr>
154 * <td>1</td>
155 * <td>Anno Hijrah (AH)</td>
156 * </tr>
157 * </table>
158 *
159 * <p>Calendar field value names for {@code "gregory"} must be consistent with
160 * the date-time symbols provided by {@link java.text.spi.DateFormatSymbolsProvider}.
161 *
162 * <p>Time zone names are supported by {@link TimeZoneNameProvider}.
163 *
164 * @author Masayoshi Okutsu
165 * @since 1.8
166 * @see CalendarDataProvider
167 * @see Locale#getUnicodeLocaleType(String)
168 */
169 public abstract class CalendarNameProvider extends LocaleServiceProvider {
170 /**
171 * Sole constructor. (For invocation by subclass constructors, typically
172 * implicit.)
173 */
174 protected CalendarNameProvider() {
175 }
176
177 /**
178 * Returns the string representation (display name) of the calendar
179 * <code>field value</code> in the given <code>style</code> and
180 * <code>locale</code>. If no string representation is
181 * applicable, <code>null</code> is returned.
182 *
183 * <p>{@code field} is a {@code Calendar} field index, such as {@link
184 * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
185 * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
186 * method. {@code null} must be returned if any time zone fields are
187 * specified.
188 *
189 * <p>{@code value} is the numeric representation of the {@code field} value.
190 * For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid
191 * values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
192 * (inclusive).
193 *
194 * <p>{@code style} gives the style of the string representation. It is one
195 * of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
196 * {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
197 * ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
198 * {@link Calendar#NARROW_FORMAT}, or {@link Calendar#NARROW_STANDALONE}.
199 *
200 * <p>For example, the following call will return {@code "Sunday"}.
201 * <pre>
202 * getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
203 * Calendar.LONG_STANDALONE, Locale.ENGLISH);
204 * </pre>
205 *
206 * @param calendarType
207 * the calendar type. (Any calendar type given by {@code locale}
208 * is ignored.)
209 * @param field
210 * the {@code Calendar} field index,
211 * such as {@link Calendar#DAY_OF_WEEK}
212 * @param value
213 * the value of the {@code Calendar field},
214 * such as {@link Calendar#MONDAY}
215 * @param style
216 * the string representation style: one of {@link
217 * Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
218 * {@link Calendar#SHORT_STANDALONE}, {@link
219 * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}),
220 * {@link Calendar#LONG_STANDALONE},
221 * {@link Calendar#NARROW_FORMAT},
222 * or {@link Calendar#NARROW_STANDALONE}
223 * @param locale
224 * the desired locale
225 * @return the string representation of the {@code field value}, or {@code
226 * null} if the string representation is not applicable or
227 * the given calendar type is unknown
228 * @throws IllegalArgumentException
229 * if {@code field} or {@code style} is invalid
230 * @throws NullPointerException if {@code locale} is {@code null}
231 * @see TimeZoneNameProvider
232 * @see java.util.Calendar#get(int)
233 * @see java.util.Calendar#getDisplayName(int, int, Locale)
234 */
235 public abstract String getDisplayName(String calendarType,
236 int field, int value,
237 int style, Locale locale);
238
239 /**
240 * Returns a {@code Map} containing all string representations (display
241 * names) of the {@code Calendar} {@code field} in the given {@code style}
242 * and {@code locale} and their corresponding field values.
243 *
244 * <p>{@code field} is a {@code Calendar} field index, such as {@link
245 * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
246 * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
247 * method. {@code null} must be returned if any time zone fields are specified.
248 *
249 * <p>{@code style} gives the style of the string representation. It must be
250 * one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link
251 * Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link
252 * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), {@link
253 * Calendar#LONG_STANDALONE}, {@link Calendar#NARROW_FORMAT}, or
254 * {@link Calendar#NARROW_STANDALONE}. Note that narrow names may
255 * not be unique due to use of single characters, such as "S" for Sunday
256 * and Saturday, and that no narrow names are included in that case.
257 *
258 * <p>For example, the following call will return a {@code Map} containing
259 * {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link
260 * Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY},
261 * {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on.
262 * <pre>
263 * getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
264 * </pre>
265 *
266 * @param calendarType
267 * the calendar type. (Any calendar type given by {@code locale}
268 * is ignored.)
269 * @param field
270 * the calendar field for which the display names are returned
271 * @param style
272 * the style applied to the display names; one of
273 * {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT}
274 * ({@link Calendar#SHORT SHORT}), {@link
275 * Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
276 * ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
277 * {@link Calendar#NARROW_FORMAT},
278 * or {@link Calendar#NARROW_STANDALONE}
279 * @param locale
280 * the desired locale
281 * @return a {@code Map} containing all display names of {@code field} in
282 * {@code style} and {@code locale} and their {@code field} values,
283 * or {@code null} if no display names are defined for {@code field}
284 * @throws NullPointerException
285 * if {@code locale} is {@code null}
286 * @see Calendar#getDisplayNames(int, int, Locale)
287 */
288 public abstract Map<String, Integer> getDisplayNames(String calendarType,
289 int field, int style,
290 Locale locale);
291 }