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