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 } |