src/share/classes/java/util/spi/CalendarNameProvider.java

Print this page




 157     /**
 158      * Returns the string representation (display name) of the calendar
 159      * <code>field value</code> in the given <code>style</code> and
 160      * <code>locale</code>.  If no string representation is
 161      * applicable, <code>null</code> is returned.
 162      *
 163      * <p>{@code field} is a {@code Calendar} field index, such as {@link
 164      * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
 165      * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
 166      * method. {@code null} must be returned if any time zone fields are
 167      * specified.
 168      *
 169      * <p>{@code value} is the numeric representation of the {@code field} value.
 170      * For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid
 171      * values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
 172      * (inclusive).
 173      *
 174      * <p>{@code style} gives the style of the string representation. It is one
 175      * of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
 176      * {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
 177      * ({@link Calendar#LONG LONG}), or {@link Calendar#LONG_STANDALONE}.

 178      *
 179      * <p>For example, the following call will return {@code "Sunday"}.
 180      * <pre>
 181      * getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
 182      *                Calendar.LONG_STANDALONE, Locale.ENGLISH);
 183      * </pre>
 184      *
 185      * @param calendarType
 186      *              the calendar type. (Any calendar type given by {@code locale}
 187      *              is ignored.)
 188      * @param field
 189      *              the {@code Calendar} field index,
 190      *              such as {@link Calendar#DAY_OF_WEEK}
 191      * @param value
 192      *              the value of the {@code Calendar field},
 193      *              such as {@link Calendar#MONDAY}
 194      * @param style
 195      *              the string representation style: one of {@link
 196      *              Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
 197      *              {@link Calendar#SHORT_STANDALONE}, {@link
 198      *              Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), or
 199      *              {@link Calendar#LONG_STANDALONE}


 200      * @param locale
 201      *              the desired locale
 202      * @return the string representation of the {@code field value}, or {@code
 203      *         null} if the string representation is not applicable or
 204      *         the given calendar type is unknown
 205      * @throws IllegalArgumentException
 206      *         if {@code field} or {@code style} is invalid
 207      * @throws NullPointerException if {@code locale} is {@code null}
 208      * @see TimeZoneNameProvider
 209      * @see java.util.Calendar#get(int)
 210      * @see java.util.Calendar#getDisplayName(int, int, Locale)
 211      */
 212     public abstract String getDisplayName(String calendarType,
 213                                           int field, int value,
 214                                           int style, Locale locale);
 215 
 216     /**
 217      * Returns a {@code Map} containing all string representations (display
 218      * names) of the {@code Calendar} {@code field} in the given {@code style}
 219      * and {@code locale} and their corresponding field values.
 220      *
 221      * <p>{@code field} is a {@code Calendar} field index, such as {@link
 222      * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
 223      * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
 224      * method. {@code null} must be returned if any time zone fields are specified.
 225      *
 226      * <p>{@code style} gives the style of the string representation. It must be
 227      * one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link
 228      * Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link
 229      * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), or {@link
 230      * Calendar#LONG_STANDALONE}.



 231      *
 232      * <p>For example, the following call will return a {@code Map} containing
 233      * {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link
 234      * Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY},
 235      * {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on.
 236      * <pre>
 237      * getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
 238      * </pre>
 239      *
 240      * @param calendarType
 241      *              the calendar type. (Any calendar type given by {@code locale}
 242      *              is ignored.)
 243      * @param field
 244      *              the calendar field for which the display names are returned
 245      * @param style
 246      *              the style applied to the display names; one of
 247      *              {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT}
 248      *              ({@link Calendar#SHORT SHORT}), {@link
 249      *              Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
 250      *              ({@link Calendar#LONG LONG}), or {@link
 251      *              Calendar#LONG_STANDALONE}.

 252      * @param locale
 253      *              the desired locale
 254      * @return a {@code Map} containing all display names of {@code field} in
 255      *         {@code style} and {@code locale} and their {@code field} values,
 256      *         or {@code null} if no display names are defined for {@code field}
 257      * @throws NullPointerException
 258      *         if {@code locale} is {@code null}
 259      * @see Calendar#getDisplayNames(int, int, Locale)
 260      */
 261     public abstract Map<String, Integer> getDisplayNames(String calendarType,
 262                                                          int field, int style,
 263                                                          Locale locale);
 264 }


 157     /**
 158      * Returns the string representation (display name) of the calendar
 159      * <code>field value</code> in the given <code>style</code> and
 160      * <code>locale</code>.  If no string representation is
 161      * applicable, <code>null</code> is returned.
 162      *
 163      * <p>{@code field} is a {@code Calendar} field index, such as {@link
 164      * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
 165      * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
 166      * method. {@code null} must be returned if any time zone fields are
 167      * specified.
 168      *
 169      * <p>{@code value} is the numeric representation of the {@code field} value.
 170      * For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid
 171      * values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
 172      * (inclusive).
 173      *
 174      * <p>{@code style} gives the style of the string representation. It is one
 175      * of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
 176      * {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
 177      * ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
 178      * {@link Calendar#NARROW_FORMAT}, or {@link Calendar#NARROW_STANDALONE}.
 179      *
 180      * <p>For example, the following call will return {@code "Sunday"}.
 181      * <pre>
 182      * getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
 183      *                Calendar.LONG_STANDALONE, Locale.ENGLISH);
 184      * </pre>
 185      *
 186      * @param calendarType
 187      *              the calendar type. (Any calendar type given by {@code locale}
 188      *              is ignored.)
 189      * @param field
 190      *              the {@code Calendar} field index,
 191      *              such as {@link Calendar#DAY_OF_WEEK}
 192      * @param value
 193      *              the value of the {@code Calendar field},
 194      *              such as {@link Calendar#MONDAY}
 195      * @param style
 196      *              the string representation style: one of {@link
 197      *              Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
 198      *              {@link Calendar#SHORT_STANDALONE}, {@link
 199      *              Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}),
 200      *              {@link Calendar#LONG_STANDALONE},
 201      *              {@link Calendar#NARROW_FORMAT},
 202      *              or {@link Calendar#NARROW_STANDALONE}
 203      * @param locale
 204      *              the desired locale
 205      * @return the string representation of the {@code field value}, or {@code
 206      *         null} if the string representation is not applicable or
 207      *         the given calendar type is unknown
 208      * @throws IllegalArgumentException
 209      *         if {@code field} or {@code style} is invalid
 210      * @throws NullPointerException if {@code locale} is {@code null}
 211      * @see TimeZoneNameProvider
 212      * @see java.util.Calendar#get(int)
 213      * @see java.util.Calendar#getDisplayName(int, int, Locale)
 214      */
 215     public abstract String getDisplayName(String calendarType,
 216                                           int field, int value,
 217                                           int style, Locale locale);
 218 
 219     /**
 220      * Returns a {@code Map} containing all string representations (display
 221      * names) of the {@code Calendar} {@code field} in the given {@code style}
 222      * and {@code locale} and their corresponding field values.
 223      *
 224      * <p>{@code field} is a {@code Calendar} field index, such as {@link
 225      * Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
 226      * {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
 227      * method. {@code null} must be returned if any time zone fields are specified.
 228      *
 229      * <p>{@code style} gives the style of the string representation. It must be
 230      * one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link
 231      * Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link
 232      * Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), {@link
 233      * Calendar#LONG_STANDALONE}, {@link Calendar#NARROW_FORMAT}, or
 234      * {@link Calendar#NARROW_STANDALONE}. Note that narrow names may
 235      * not be unique due to use of single characters, such as "S" for Sunday
 236      * and Saturday, and that no narrow names are included in that case.
 237      *
 238      * <p>For example, the following call will return a {@code Map} containing
 239      * {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link
 240      * Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY},
 241      * {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on.
 242      * <pre>
 243      * getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
 244      * </pre>
 245      *
 246      * @param calendarType
 247      *              the calendar type. (Any calendar type given by {@code locale}
 248      *              is ignored.)
 249      * @param field
 250      *              the calendar field for which the display names are returned
 251      * @param style
 252      *              the style applied to the display names; one of
 253      *              {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT}
 254      *              ({@link Calendar#SHORT SHORT}), {@link
 255      *              Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
 256      *              ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
 257      *              {@link Calendar#NARROW_FORMAT},
 258      *              or {@link Calendar#NARROW_STANDALONE}
 259      * @param locale
 260      *              the desired locale
 261      * @return a {@code Map} containing all display names of {@code field} in
 262      *         {@code style} and {@code locale} and their {@code field} values,
 263      *         or {@code null} if no display names are defined for {@code field}
 264      * @throws NullPointerException
 265      *         if {@code locale} is {@code null}
 266      * @see Calendar#getDisplayNames(int, int, Locale)
 267      */
 268     public abstract Map<String, Integer> getDisplayNames(String calendarType,
 269                                                          int field, int style,
 270                                                          Locale locale);
 271 }