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 class="plain" style="border-bottom:1px solid">
  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 valign="top">{@link Calendar#MONTH}</td>
  61  *     <td valign="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 valign="top">{@link Calendar#DAY_OF_WEEK}</td>
  71  *     <td valign="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 valign="top">{@link Calendar#AM_PM}</td>
  77  *     <td valign="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" style="border-bottom:1px solid">
  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" valign="top">{@code "gregory"}</td>
  98  *     <td rowspan="2" valign="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" valign="top">{@code "buddhist"}</td>
 108  *     <td rowspan="2" valign="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" valign="top">{@code "japanese"}</td>
 118  *     <td rowspan="5" valign="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" valign="top">{@code "roc"}</td>
 148  *     <td rowspan="2" valign="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" valign="top">{@code "islamic"}</td>
 158  *     <td rowspan="2" valign="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 }