1 /* 2 * Copyright (c) 2012, 2017, 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 class="plain"> 50 * <caption style="display:none">Field values</caption> 51 * <thead> 52 * <tr> 53 * <th>Field</th> 54 * <th>Value</th> 55 * <th>Description</th> 56 * </tr> 57 * </thead> 58 * <tbody> 59 * <tr> 60 * <td style="vertical-align:top">{@link Calendar#MONTH}</td> 61 * <td style="vertical-align:top">{@link Calendar#JANUARY} to {@link Calendar#UNDECIMBER}</td> 62 * <td>Month numbering is 0-based (e.g., 0 - January, ..., 11 - 63 * December). Some calendar systems have 13 months. Month 64 * names need to be supported in both the formatting and 65 * stand-alone forms if required by the supported locales. If there's 66 * no distinction in the two forms, the same names should be returned 67 * in both of the forms.</td> 68 * </tr> 69 * <tr> 70 * <td style="vertical-align:top">{@link Calendar#DAY_OF_WEEK}</td> 71 * <td style="vertical-align:top">{@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}</td> 72 * <td>Day-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday, 73 * ..., 7 - Saturday).</td> 74 * </tr> 75 * <tr> 76 * <td style="vertical-align:top">{@link Calendar#AM_PM}</td> 77 * <td style="vertical-align:top">{@link Calendar#AM} to {@link Calendar#PM}</td> 78 * <td>0 - AM, 1 - PM</td> 79 * </tr> 80 * </tbody> 81 * </table> 82 * 83 * <p style="margin-top:20px">The following are calendar-specific fields and their values to be supported. 84 * 85 * <table class="plain"> 86 * <caption style="display:none">Calendar type and field values</caption> 87 * <thead> 88 * <tr> 89 * <th>Calendar Type</th> 90 * <th>Field</th> 91 * <th>Value</th> 92 * <th>Description</th> 93 * </tr> 94 * </thead> 95 * <tbody> 96 * <tr> 97 * <td rowspan="2" style="vertical-align:top">{@code "gregory"}</td> 98 * <td rowspan="2" style="vertical-align:top">{@link Calendar#ERA}</td> 99 * <td>0</td> 100 * <td>{@link java.util.GregorianCalendar#BC} (BCE)</td> 101 * </tr> 102 * <tr> 103 * <td>1</td> 104 * <td>{@link java.util.GregorianCalendar#AD} (CE)</td> 105 * </tr> 106 * <tr> 107 * <td rowspan="2" style="vertical-align:top">{@code "buddhist"}</td> 108 * <td rowspan="2" style="vertical-align:top">{@link Calendar#ERA}</td> 109 * <td>0</td> 110 * <td>BC (BCE)</td> 111 * </tr> 112 * <tr> 113 * <td>1</td> 114 * <td>B.E. (Buddhist Era)</td> 115 * </tr> 116 * <tr> 117 * <td rowspan="6" style="vertical-align:top">{@code "japanese"}</td> 118 * <td rowspan="5" style="vertical-align:top">{@link Calendar#ERA}</td> 119 * <td>0</td> 120 * <td>Seireki (Before Meiji)</td> 121 * </tr> 122 * <tr> 123 * <td>1</td> 124 * <td>Meiji</td> 125 * </tr> 126 * <tr> 127 * <td>2</td> 128 * <td>Taisho</td> 129 * </tr> 130 * <tr> 131 * <td>3</td> 132 * <td>Showa</td> 133 * </tr> 134 * <tr> 135 * <td>4</td> 136 * <td >Heisei</td> 137 * </tr> 138 * <tr> 139 * <td>{@link Calendar#YEAR}</td> 140 * <td>1</td> 141 * <td>the first year in each era. It should be returned when a long 142 * style ({@link Calendar#LONG_FORMAT} or {@link Calendar#LONG_STANDALONE}) is 143 * specified. See also the <a href="../../text/SimpleDateFormat.html#year"> 144 * Year representation in {@code SimpleDateFormat}</a>.</td> 145 * </tr> 146 * <tr> 147 * <td rowspan="2" style="vertical-align:top">{@code "roc"}</td> 148 * <td rowspan="2" style="vertical-align:top">{@link Calendar#ERA}</td> 149 * <td>0</td> 150 * <td>Before R.O.C.</td> 151 * </tr> 152 * <tr> 153 * <td>1</td> 154 * <td>R.O.C.</td> 155 * </tr> 156 * <tr> 157 * <td rowspan="2" style="vertical-align:top">{@code "islamic"}</td> 158 * <td rowspan="2" style="vertical-align:top">{@link Calendar#ERA}</td> 159 * <td>0</td> 160 * <td>Before AH</td> 161 * </tr> 162 * <tr> 163 * <td>1</td> 164 * <td>Anno Hijrah (AH)</td> 165 * </tr> 166 * </tbody> 167 * </table> 168 * 169 * <p>Calendar field value names for {@code "gregory"} must be consistent with 170 * the date-time symbols provided by {@link java.text.spi.DateFormatSymbolsProvider}. 171 * 172 * <p>Time zone names are supported by {@link TimeZoneNameProvider}. 173 * 174 * @author Masayoshi Okutsu 175 * @since 1.8 176 * @see CalendarDataProvider 177 * @see Locale#getUnicodeLocaleType(String) 178 */ 179 public abstract class CalendarNameProvider extends LocaleServiceProvider { 180 /** 181 * Sole constructor. (For invocation by subclass constructors, typically 182 * implicit.) 183 */ 184 protected CalendarNameProvider() { 185 } 186 187 /** 188 * Returns the string representation (display name) of the calendar 189 * <code>field value</code> in the given <code>style</code> and 190 * <code>locale</code>. If no string representation is 191 * applicable, <code>null</code> is returned. 192 * 193 * <p>{@code field} is a {@code Calendar} field index, such as {@link 194 * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and 195 * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this 196 * method. {@code null} must be returned if any time zone fields are 197 * specified. 198 * 199 * <p>{@code value} is the numeric representation of the {@code field} value. 200 * For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid 201 * values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY} 202 * (inclusive). 203 * 204 * <p>{@code style} gives the style of the string representation. It is one 205 * of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}), 206 * {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT} 207 * ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE}, 208 * {@link Calendar#NARROW_FORMAT}, or {@link Calendar#NARROW_STANDALONE}. 209 * 210 * <p>For example, the following call will return {@code "Sunday"}. 211 * <pre> 212 * getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY, 213 * Calendar.LONG_STANDALONE, Locale.ENGLISH); 214 * </pre> 215 * 216 * @param calendarType 217 * the calendar type. (Any calendar type given by {@code locale} 218 * is ignored.) 219 * @param field 220 * the {@code Calendar} field index, 221 * such as {@link Calendar#DAY_OF_WEEK} 222 * @param value 223 * the value of the {@code Calendar field}, 224 * such as {@link Calendar#MONDAY} 225 * @param style 226 * the string representation style: one of {@link 227 * Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}), 228 * {@link Calendar#SHORT_STANDALONE}, {@link 229 * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), 230 * {@link Calendar#LONG_STANDALONE}, 231 * {@link Calendar#NARROW_FORMAT}, 232 * or {@link Calendar#NARROW_STANDALONE} 233 * @param locale 234 * the desired locale 235 * @return the string representation of the {@code field value}, or {@code 236 * null} if the string representation is not applicable or 237 * the given calendar type is unknown 238 * @throws IllegalArgumentException 239 * if {@code field} or {@code style} is invalid 240 * @throws NullPointerException if {@code locale} is {@code null} 241 * @see TimeZoneNameProvider 242 * @see java.util.Calendar#get(int) 243 * @see java.util.Calendar#getDisplayName(int, int, Locale) 244 */ 245 public abstract String getDisplayName(String calendarType, 246 int field, int value, 247 int style, Locale locale); 248 249 /** 250 * Returns a {@code Map} containing all string representations (display 251 * names) of the {@code Calendar} {@code field} in the given {@code style} 252 * and {@code locale} and their corresponding field values. 253 * 254 * <p>{@code field} is a {@code Calendar} field index, such as {@link 255 * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and 256 * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this 257 * method. {@code null} must be returned if any time zone fields are specified. 258 * 259 * <p>{@code style} gives the style of the string representation. It must be 260 * one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link 261 * Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link 262 * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), {@link 263 * Calendar#LONG_STANDALONE}, {@link Calendar#NARROW_FORMAT}, or 264 * {@link Calendar#NARROW_STANDALONE}. Note that narrow names may 265 * not be unique due to use of single characters, such as "S" for Sunday 266 * and Saturday, and that no narrow names are included in that case. 267 * 268 * <p>For example, the following call will return a {@code Map} containing 269 * {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link 270 * Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY}, 271 * {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on. 272 * <pre> 273 * getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH); 274 * </pre> 275 * 276 * @param calendarType 277 * the calendar type. (Any calendar type given by {@code locale} 278 * is ignored.) 279 * @param field 280 * the calendar field for which the display names are returned 281 * @param style 282 * the style applied to the display names; one of 283 * {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} 284 * ({@link Calendar#SHORT SHORT}), {@link 285 * Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT} 286 * ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE}, 287 * {@link Calendar#NARROW_FORMAT}, 288 * or {@link Calendar#NARROW_STANDALONE} 289 * @param locale 290 * the desired locale 291 * @return a {@code Map} containing all display names of {@code field} in 292 * {@code style} and {@code locale} and their {@code field} values, 293 * or {@code null} if no display names are defined for {@code field} 294 * @throws NullPointerException 295 * if {@code locale} is {@code null} 296 * @see Calendar#getDisplayNames(int, int, Locale) 297 */ 298 public abstract Map<String, Integer> getDisplayNames(String calendarType, 299 int field, int style, 300 Locale locale); 301 }