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 }