2083 *
2084 * <p>The default implementation supports the calendar fields for
2085 * which a {@link DateFormatSymbols} has names in the given
2086 * <code>locale</code>.
2087 *
2088 * @param field
2089 * the calendar field for which the string representation
2090 * is returned
2091 * @param style
2092 * the style applied to the string representation; one of {@link
2093 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2094 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2095 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}.
2096 * @param locale
2097 * the locale for the string representation
2098 * (any calendar types specified by {@code locale} are ignored)
2099 * @return the string representation of the given
2100 * {@code field} in the given {@code style}, or
2101 * {@code null} if no string representation is
2102 * applicable.
2103 * @exception IllegalArgumentException
2104 * if {@code field} or {@code style} is invalid,
2105 * or if this {@code Calendar} is non-lenient and any
2106 * of the calendar fields have invalid values
2107 * @exception NullPointerException
2108 * if {@code locale} is null
2109 * @since 1.6
2110 */
2111 public String getDisplayName(int field, int style, Locale locale) {
2112 if (!checkDisplayNameParams(field, style, SHORT, NARROW_FORMAT, locale,
2113 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2114 return null;
2115 }
2116
2117 String calendarType = getCalendarType();
2118 int fieldValue = get(field);
2119 // the standalone/narrow styles and short era are supported only through
2120 // CalendarNameProviders.
2121 if (isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2122 field == ERA && (style & SHORT) == SHORT) {
2123 String val = CalendarDataUtility.retrieveFieldValueName(calendarType,
2124 field, fieldValue,
2125 style, locale);
2126 // Perform fallback here to follow the CLDR rules
2127 if (val == null) {
2174 * <p>The default implementation supports display names contained in
2175 * a {@link DateFormatSymbols}. For example, if {@code field}
2176 * is {@link #MONTH} and {@code style} is {@link
2177 * #ALL_STYLES}, this method returns a {@code Map} containing
2178 * all strings returned by {@link DateFormatSymbols#getShortMonths()}
2179 * and {@link DateFormatSymbols#getMonths()}.
2180 *
2181 * @param field
2182 * the calendar field for which the display names are returned
2183 * @param style
2184 * the style applied to the string representation; one of {@link
2185 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2186 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2187 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}
2188 * @param locale
2189 * the locale for the display names
2190 * @return a {@code Map} containing all display names in
2191 * {@code style} and {@code locale} and their
2192 * field values, or {@code null} if no display names
2193 * are defined for {@code field}
2194 * @exception IllegalArgumentException
2195 * if {@code field} or {@code style} is invalid,
2196 * or if this {@code Calendar} is non-lenient and any
2197 * of the calendar fields have invalid values
2198 * @exception NullPointerException
2199 * if {@code locale} is null
2200 * @since 1.6
2201 */
2202 public Map<String, Integer> getDisplayNames(int field, int style, Locale locale) {
2203 if (!checkDisplayNameParams(field, style, ALL_STYLES, NARROW_FORMAT, locale,
2204 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2205 return null;
2206 }
2207
2208 String calendarType = getCalendarType();
2209 if (style == ALL_STYLES || isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2210 field == ERA && (style & SHORT) == SHORT) {
2211 Map<String, Integer> map;
2212 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field, style, locale);
2213
2214 // Perform fallback here to follow the CLDR rules
2215 if (map == null) {
2216 if (isNarrowFormatStyle(style)) {
2217 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field,
2218 toStandaloneStyle(style), locale);
2294 * called to calculate all calendar field values.
2295 */
2296 protected void complete()
2297 {
2298 if (!isTimeSet) {
2299 updateTime();
2300 }
2301 if (!areFieldsSet || !areAllFieldsSet) {
2302 computeFields(); // fills in unset fields
2303 areAllFieldsSet = areFieldsSet = true;
2304 }
2305 }
2306
2307 /**
2308 * Returns whether the value of the specified calendar field has been set
2309 * externally by calling one of the setter methods rather than by the
2310 * internal time calculation.
2311 *
2312 * @return <code>true</code> if the field has been set externally,
2313 * <code>false</code> otherwise.
2314 * @exception IndexOutOfBoundsException if the specified
2315 * <code>field</code> is out of range
2316 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2317 * @see #selectFields()
2318 * @see #setFieldsComputed(int)
2319 */
2320 final boolean isExternallySet(int field) {
2321 return stamp[field] >= MINIMUM_USER_STAMP;
2322 }
2323
2324 /**
2325 * Returns a field mask (bit mask) indicating all calendar fields that
2326 * have the state of externally or internally set.
2327 *
2328 * @return a bit mask indicating set state fields
2329 */
2330 final int getSetStateFields() {
2331 int mask = 0;
2332 for (int i = 0; i < fields.length; i++) {
2333 if (stamp[i] != UNSET) {
2334 mask |= 1 << i;
2335 }
2336 }
2337 return mask;
2338 }
2339
2340 /**
2341 * Sets the state of the specified calendar fields to
2342 * <em>computed</em>. This state means that the specified calendar fields
2343 * have valid values that have been set by internal time calculation
2344 * rather than by calling one of the setter methods.
2345 *
2346 * @param fieldMask the field to be marked as computed.
2347 * @exception IndexOutOfBoundsException if the specified
2348 * <code>field</code> is out of range
2349 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2350 * @see #isExternallySet(int)
2351 * @see #selectFields()
2352 */
2353 final void setFieldsComputed(int fieldMask) {
2354 if (fieldMask == ALL_FIELDS) {
2355 for (int i = 0; i < fields.length; i++) {
2356 stamp[i] = COMPUTED;
2357 isSet[i] = true;
2358 }
2359 areFieldsSet = areAllFieldsSet = true;
2360 } else {
2361 for (int i = 0; i < fields.length; i++) {
2362 if ((fieldMask & 1) == 1) {
2363 stamp[i] = COMPUTED;
2364 isSet[i] = true;
2365 } else {
2366 if (areAllFieldsSet && !isSet[i]) {
2367 areAllFieldsSet = false;
2368 }
2369 }
2370 fieldMask >>>= 1;
2371 }
2372 }
2373 }
2374
2375 /**
2376 * Sets the state of the calendar fields that are <em>not</em> specified
2377 * by <code>fieldMask</code> to <em>unset</em>. If <code>fieldMask</code>
2378 * specifies all the calendar fields, then the state of this
2379 * <code>Calendar</code> becomes that all the calendar fields are in sync
2380 * with the time value (millisecond offset from the Epoch).
2381 *
2382 * @param fieldMask the field mask indicating which calendar fields are in
2383 * sync with the time value.
2384 * @exception IndexOutOfBoundsException if the specified
2385 * <code>field</code> is out of range
2386 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2387 * @see #isExternallySet(int)
2388 * @see #selectFields()
2389 */
2390 final void setFieldsNormalized(int fieldMask) {
2391 if (fieldMask != ALL_FIELDS) {
2392 for (int i = 0; i < fields.length; i++) {
2393 if ((fieldMask & 1) == 0) {
2394 stamp[i] = fields[i] = 0; // UNSET == 0
2395 isSet[i] = false;
2396 }
2397 fieldMask >>= 1;
2398 }
2399 }
2400
2401 // Some or all of the fields are in sync with the
2402 // milliseconds, but the stamp values are not normalized yet.
2403 areFieldsSet = true;
2404 areAllFieldsSet = false;
2789 * otherwise.
2790 * @see #compareTo(Calendar)
2791 */
2792 public boolean after(Object when) {
2793 return when instanceof Calendar
2794 && compareTo((Calendar)when) > 0;
2795 }
2796
2797 /**
2798 * Compares the time values (millisecond offsets from the <a
2799 * href="#Epoch">Epoch</a>) represented by two
2800 * <code>Calendar</code> objects.
2801 *
2802 * @param anotherCalendar the <code>Calendar</code> to be compared.
2803 * @return the value <code>0</code> if the time represented by the argument
2804 * is equal to the time represented by this <code>Calendar</code>; a value
2805 * less than <code>0</code> if the time of this <code>Calendar</code> is
2806 * before the time represented by the argument; and a value greater than
2807 * <code>0</code> if the time of this <code>Calendar</code> is after the
2808 * time represented by the argument.
2809 * @exception NullPointerException if the specified <code>Calendar</code> is
2810 * <code>null</code>.
2811 * @exception IllegalArgumentException if the time value of the
2812 * specified <code>Calendar</code> object can't be obtained due to
2813 * any invalid calendar values.
2814 * @since 1.5
2815 */
2816 @Override
2817 public int compareTo(Calendar anotherCalendar) {
2818 return compareTo(getMillisOf(anotherCalendar));
2819 }
2820
2821 /**
2822 * Adds or subtracts the specified amount of time to the given calendar field,
2823 * based on the calendar's rules. For example, to subtract 5 days from
2824 * the current time of the calendar, you can achieve it by calling:
2825 * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
2826 *
2827 * @param field the calendar field.
2828 * @param amount the amount of date or time to be added to the field.
2829 * @see #roll(int,int)
2830 * @see #set(int,int)
2831 */
3037 * {@code false} otherwise.
3038 * @see #getWeekYear()
3039 * @see #setWeekDate(int,int,int)
3040 * @see #getWeeksInWeekYear()
3041 * @since 1.7
3042 */
3043 public boolean isWeekDateSupported() {
3044 return false;
3045 }
3046
3047 /**
3048 * Returns the week year represented by this {@code Calendar}. The
3049 * week year is in sync with the week cycle. The {@linkplain
3050 * #getFirstDayOfWeek() first day of the first week} is the first
3051 * day of the week year.
3052 *
3053 * <p>The default implementation of this method throws an
3054 * {@link UnsupportedOperationException}.
3055 *
3056 * @return the week year of this {@code Calendar}
3057 * @exception UnsupportedOperationException
3058 * if any week year numbering isn't supported
3059 * in this {@code Calendar}.
3060 * @see #isWeekDateSupported()
3061 * @see #getFirstDayOfWeek()
3062 * @see #getMinimalDaysInFirstWeek()
3063 * @since 1.7
3064 */
3065 public int getWeekYear() {
3066 throw new UnsupportedOperationException();
3067 }
3068
3069 /**
3070 * Sets the date of this {@code Calendar} with the given date
3071 * specifiers - week year, week of year, and day of week.
3072 *
3073 * <p>Unlike the {@code set} method, all of the calendar fields
3074 * and {@code time} values are calculated upon return.
3075 *
3076 * <p>If {@code weekOfYear} is out of the valid week-of-year range
3077 * in {@code weekYear}, the {@code weekYear} and {@code
3078 * weekOfYear} values are adjusted in lenient mode, or an {@code
3079 * IllegalArgumentException} is thrown in non-lenient mode.
3080 *
3081 * <p>The default implementation of this method throws an
3082 * {@code UnsupportedOperationException}.
3083 *
3084 * @param weekYear the week year
3085 * @param weekOfYear the week number based on {@code weekYear}
3086 * @param dayOfWeek the day of week value: one of the constants
3087 * for the {@link #DAY_OF_WEEK} field: {@link
3088 * #SUNDAY}, ..., {@link #SATURDAY}.
3089 * @exception IllegalArgumentException
3090 * if any of the given date specifiers is invalid
3091 * or any of the calendar fields are inconsistent
3092 * with the given date specifiers in non-lenient mode
3093 * @exception UnsupportedOperationException
3094 * if any week year numbering isn't supported in this
3095 * {@code Calendar}.
3096 * @see #isWeekDateSupported()
3097 * @see #getFirstDayOfWeek()
3098 * @see #getMinimalDaysInFirstWeek()
3099 * @since 1.7
3100 */
3101 public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek) {
3102 throw new UnsupportedOperationException();
3103 }
3104
3105 /**
3106 * Returns the number of weeks in the week year represented by this
3107 * {@code Calendar}.
3108 *
3109 * <p>The default implementation of this method throws an
3110 * {@code UnsupportedOperationException}.
3111 *
3112 * @return the number of weeks in the week year.
3113 * @exception UnsupportedOperationException
3114 * if any week year numbering isn't supported in this
3115 * {@code Calendar}.
3116 * @see #WEEK_OF_YEAR
3117 * @see #isWeekDateSupported()
3118 * @see #getWeekYear()
3119 * @see #getActualMaximum(int)
3120 * @since 1.7
3121 */
3122 public int getWeeksInWeekYear() {
3123 throw new UnsupportedOperationException();
3124 }
3125
3126 /**
3127 * Returns the minimum value for the given calendar field of this
3128 * <code>Calendar</code> instance. The minimum value is defined as
3129 * the smallest value returned by the {@link #get(int) get} method
3130 * for any possible time value. The minimum value depends on
3131 * calendar system specific parameters of the instance.
3132 *
3133 * @param field the calendar field.
3334 return other;
3335 }
3336 catch (CloneNotSupportedException e) {
3337 // this shouldn't happen, since we are Cloneable
3338 throw new InternalError(e);
3339 }
3340 }
3341
3342 private static final String[] FIELD_NAME = {
3343 "ERA", "YEAR", "MONTH", "WEEK_OF_YEAR", "WEEK_OF_MONTH", "DAY_OF_MONTH",
3344 "DAY_OF_YEAR", "DAY_OF_WEEK", "DAY_OF_WEEK_IN_MONTH", "AM_PM", "HOUR",
3345 "HOUR_OF_DAY", "MINUTE", "SECOND", "MILLISECOND", "ZONE_OFFSET",
3346 "DST_OFFSET"
3347 };
3348
3349 /**
3350 * Returns the name of the specified calendar field.
3351 *
3352 * @param field the calendar field
3353 * @return the calendar field name
3354 * @exception IndexOutOfBoundsException if <code>field</code> is negative,
3355 * equal to or greater than {@code FIELD_COUNT}.
3356 */
3357 static String getFieldName(int field) {
3358 return FIELD_NAME[field];
3359 }
3360
3361 /**
3362 * Return a string representation of this calendar. This method
3363 * is intended to be used only for debugging purposes, and the
3364 * format of the returned string may vary between implementations.
3365 * The returned string may be empty but may not be <code>null</code>.
3366 *
3367 * @return a string representation of this calendar.
3368 */
3369 @Override
3370 public String toString() {
3371 // NOTE: BuddhistCalendar.toString() interprets the string
3372 // produced by this method so that the Gregorian year number
3373 // is substituted by its B.E. year value. It relies on
3374 // "...,YEAR=<year>,..." or "...,YEAR=?,...".
|
2083 *
2084 * <p>The default implementation supports the calendar fields for
2085 * which a {@link DateFormatSymbols} has names in the given
2086 * <code>locale</code>.
2087 *
2088 * @param field
2089 * the calendar field for which the string representation
2090 * is returned
2091 * @param style
2092 * the style applied to the string representation; one of {@link
2093 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2094 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2095 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}.
2096 * @param locale
2097 * the locale for the string representation
2098 * (any calendar types specified by {@code locale} are ignored)
2099 * @return the string representation of the given
2100 * {@code field} in the given {@code style}, or
2101 * {@code null} if no string representation is
2102 * applicable.
2103 * @throws IllegalArgumentException
2104 * if {@code field} or {@code style} is invalid,
2105 * or if this {@code Calendar} is non-lenient and any
2106 * of the calendar fields have invalid values
2107 * @throws NullPointerException
2108 * if {@code locale} is null
2109 * @since 1.6
2110 */
2111 public String getDisplayName(int field, int style, Locale locale) {
2112 if (!checkDisplayNameParams(field, style, SHORT, NARROW_FORMAT, locale,
2113 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2114 return null;
2115 }
2116
2117 String calendarType = getCalendarType();
2118 int fieldValue = get(field);
2119 // the standalone/narrow styles and short era are supported only through
2120 // CalendarNameProviders.
2121 if (isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2122 field == ERA && (style & SHORT) == SHORT) {
2123 String val = CalendarDataUtility.retrieveFieldValueName(calendarType,
2124 field, fieldValue,
2125 style, locale);
2126 // Perform fallback here to follow the CLDR rules
2127 if (val == null) {
2174 * <p>The default implementation supports display names contained in
2175 * a {@link DateFormatSymbols}. For example, if {@code field}
2176 * is {@link #MONTH} and {@code style} is {@link
2177 * #ALL_STYLES}, this method returns a {@code Map} containing
2178 * all strings returned by {@link DateFormatSymbols#getShortMonths()}
2179 * and {@link DateFormatSymbols#getMonths()}.
2180 *
2181 * @param field
2182 * the calendar field for which the display names are returned
2183 * @param style
2184 * the style applied to the string representation; one of {@link
2185 * #SHORT_FORMAT} ({@link #SHORT}), {@link #SHORT_STANDALONE},
2186 * {@link #LONG_FORMAT} ({@link #LONG}), {@link #LONG_STANDALONE},
2187 * {@link #NARROW_FORMAT}, or {@link #NARROW_STANDALONE}
2188 * @param locale
2189 * the locale for the display names
2190 * @return a {@code Map} containing all display names in
2191 * {@code style} and {@code locale} and their
2192 * field values, or {@code null} if no display names
2193 * are defined for {@code field}
2194 * @throws IllegalArgumentException
2195 * if {@code field} or {@code style} is invalid,
2196 * or if this {@code Calendar} is non-lenient and any
2197 * of the calendar fields have invalid values
2198 * @throws NullPointerException
2199 * if {@code locale} is null
2200 * @since 1.6
2201 */
2202 public Map<String, Integer> getDisplayNames(int field, int style, Locale locale) {
2203 if (!checkDisplayNameParams(field, style, ALL_STYLES, NARROW_FORMAT, locale,
2204 ERA_MASK|MONTH_MASK|DAY_OF_WEEK_MASK|AM_PM_MASK)) {
2205 return null;
2206 }
2207
2208 String calendarType = getCalendarType();
2209 if (style == ALL_STYLES || isStandaloneStyle(style) || isNarrowFormatStyle(style) ||
2210 field == ERA && (style & SHORT) == SHORT) {
2211 Map<String, Integer> map;
2212 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field, style, locale);
2213
2214 // Perform fallback here to follow the CLDR rules
2215 if (map == null) {
2216 if (isNarrowFormatStyle(style)) {
2217 map = CalendarDataUtility.retrieveFieldValueNames(calendarType, field,
2218 toStandaloneStyle(style), locale);
2294 * called to calculate all calendar field values.
2295 */
2296 protected void complete()
2297 {
2298 if (!isTimeSet) {
2299 updateTime();
2300 }
2301 if (!areFieldsSet || !areAllFieldsSet) {
2302 computeFields(); // fills in unset fields
2303 areAllFieldsSet = areFieldsSet = true;
2304 }
2305 }
2306
2307 /**
2308 * Returns whether the value of the specified calendar field has been set
2309 * externally by calling one of the setter methods rather than by the
2310 * internal time calculation.
2311 *
2312 * @return <code>true</code> if the field has been set externally,
2313 * <code>false</code> otherwise.
2314 * @throws IndexOutOfBoundsException if the specified
2315 * <code>field</code> is out of range
2316 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2317 * @see #selectFields()
2318 * @see #setFieldsComputed(int)
2319 */
2320 final boolean isExternallySet(int field) {
2321 return stamp[field] >= MINIMUM_USER_STAMP;
2322 }
2323
2324 /**
2325 * Returns a field mask (bit mask) indicating all calendar fields that
2326 * have the state of externally or internally set.
2327 *
2328 * @return a bit mask indicating set state fields
2329 */
2330 final int getSetStateFields() {
2331 int mask = 0;
2332 for (int i = 0; i < fields.length; i++) {
2333 if (stamp[i] != UNSET) {
2334 mask |= 1 << i;
2335 }
2336 }
2337 return mask;
2338 }
2339
2340 /**
2341 * Sets the state of the specified calendar fields to
2342 * <em>computed</em>. This state means that the specified calendar fields
2343 * have valid values that have been set by internal time calculation
2344 * rather than by calling one of the setter methods.
2345 *
2346 * @param fieldMask the field to be marked as computed.
2347 * @throws IndexOutOfBoundsException if the specified
2348 * <code>field</code> is out of range
2349 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2350 * @see #isExternallySet(int)
2351 * @see #selectFields()
2352 */
2353 final void setFieldsComputed(int fieldMask) {
2354 if (fieldMask == ALL_FIELDS) {
2355 for (int i = 0; i < fields.length; i++) {
2356 stamp[i] = COMPUTED;
2357 isSet[i] = true;
2358 }
2359 areFieldsSet = areAllFieldsSet = true;
2360 } else {
2361 for (int i = 0; i < fields.length; i++) {
2362 if ((fieldMask & 1) == 1) {
2363 stamp[i] = COMPUTED;
2364 isSet[i] = true;
2365 } else {
2366 if (areAllFieldsSet && !isSet[i]) {
2367 areAllFieldsSet = false;
2368 }
2369 }
2370 fieldMask >>>= 1;
2371 }
2372 }
2373 }
2374
2375 /**
2376 * Sets the state of the calendar fields that are <em>not</em> specified
2377 * by <code>fieldMask</code> to <em>unset</em>. If <code>fieldMask</code>
2378 * specifies all the calendar fields, then the state of this
2379 * <code>Calendar</code> becomes that all the calendar fields are in sync
2380 * with the time value (millisecond offset from the Epoch).
2381 *
2382 * @param fieldMask the field mask indicating which calendar fields are in
2383 * sync with the time value.
2384 * @throws IndexOutOfBoundsException if the specified
2385 * <code>field</code> is out of range
2386 * (<code>field < 0 || field >= FIELD_COUNT</code>).
2387 * @see #isExternallySet(int)
2388 * @see #selectFields()
2389 */
2390 final void setFieldsNormalized(int fieldMask) {
2391 if (fieldMask != ALL_FIELDS) {
2392 for (int i = 0; i < fields.length; i++) {
2393 if ((fieldMask & 1) == 0) {
2394 stamp[i] = fields[i] = 0; // UNSET == 0
2395 isSet[i] = false;
2396 }
2397 fieldMask >>= 1;
2398 }
2399 }
2400
2401 // Some or all of the fields are in sync with the
2402 // milliseconds, but the stamp values are not normalized yet.
2403 areFieldsSet = true;
2404 areAllFieldsSet = false;
2789 * otherwise.
2790 * @see #compareTo(Calendar)
2791 */
2792 public boolean after(Object when) {
2793 return when instanceof Calendar
2794 && compareTo((Calendar)when) > 0;
2795 }
2796
2797 /**
2798 * Compares the time values (millisecond offsets from the <a
2799 * href="#Epoch">Epoch</a>) represented by two
2800 * <code>Calendar</code> objects.
2801 *
2802 * @param anotherCalendar the <code>Calendar</code> to be compared.
2803 * @return the value <code>0</code> if the time represented by the argument
2804 * is equal to the time represented by this <code>Calendar</code>; a value
2805 * less than <code>0</code> if the time of this <code>Calendar</code> is
2806 * before the time represented by the argument; and a value greater than
2807 * <code>0</code> if the time of this <code>Calendar</code> is after the
2808 * time represented by the argument.
2809 * @throws NullPointerException if the specified <code>Calendar</code> is
2810 * <code>null</code>.
2811 * @throws IllegalArgumentException if the time value of the
2812 * specified <code>Calendar</code> object can't be obtained due to
2813 * any invalid calendar values.
2814 * @since 1.5
2815 */
2816 @Override
2817 public int compareTo(Calendar anotherCalendar) {
2818 return compareTo(getMillisOf(anotherCalendar));
2819 }
2820
2821 /**
2822 * Adds or subtracts the specified amount of time to the given calendar field,
2823 * based on the calendar's rules. For example, to subtract 5 days from
2824 * the current time of the calendar, you can achieve it by calling:
2825 * <p><code>add(Calendar.DAY_OF_MONTH, -5)</code>.
2826 *
2827 * @param field the calendar field.
2828 * @param amount the amount of date or time to be added to the field.
2829 * @see #roll(int,int)
2830 * @see #set(int,int)
2831 */
3037 * {@code false} otherwise.
3038 * @see #getWeekYear()
3039 * @see #setWeekDate(int,int,int)
3040 * @see #getWeeksInWeekYear()
3041 * @since 1.7
3042 */
3043 public boolean isWeekDateSupported() {
3044 return false;
3045 }
3046
3047 /**
3048 * Returns the week year represented by this {@code Calendar}. The
3049 * week year is in sync with the week cycle. The {@linkplain
3050 * #getFirstDayOfWeek() first day of the first week} is the first
3051 * day of the week year.
3052 *
3053 * <p>The default implementation of this method throws an
3054 * {@link UnsupportedOperationException}.
3055 *
3056 * @return the week year of this {@code Calendar}
3057 * @throws UnsupportedOperationException
3058 * if any week year numbering isn't supported
3059 * in this {@code Calendar}.
3060 * @see #isWeekDateSupported()
3061 * @see #getFirstDayOfWeek()
3062 * @see #getMinimalDaysInFirstWeek()
3063 * @since 1.7
3064 */
3065 public int getWeekYear() {
3066 throw new UnsupportedOperationException();
3067 }
3068
3069 /**
3070 * Sets the date of this {@code Calendar} with the given date
3071 * specifiers - week year, week of year, and day of week.
3072 *
3073 * <p>Unlike the {@code set} method, all of the calendar fields
3074 * and {@code time} values are calculated upon return.
3075 *
3076 * <p>If {@code weekOfYear} is out of the valid week-of-year range
3077 * in {@code weekYear}, the {@code weekYear} and {@code
3078 * weekOfYear} values are adjusted in lenient mode, or an {@code
3079 * IllegalArgumentException} is thrown in non-lenient mode.
3080 *
3081 * <p>The default implementation of this method throws an
3082 * {@code UnsupportedOperationException}.
3083 *
3084 * @param weekYear the week year
3085 * @param weekOfYear the week number based on {@code weekYear}
3086 * @param dayOfWeek the day of week value: one of the constants
3087 * for the {@link #DAY_OF_WEEK} field: {@link
3088 * #SUNDAY}, ..., {@link #SATURDAY}.
3089 * @throws IllegalArgumentException
3090 * if any of the given date specifiers is invalid
3091 * or any of the calendar fields are inconsistent
3092 * with the given date specifiers in non-lenient mode
3093 * @throws UnsupportedOperationException
3094 * if any week year numbering isn't supported in this
3095 * {@code Calendar}.
3096 * @see #isWeekDateSupported()
3097 * @see #getFirstDayOfWeek()
3098 * @see #getMinimalDaysInFirstWeek()
3099 * @since 1.7
3100 */
3101 public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek) {
3102 throw new UnsupportedOperationException();
3103 }
3104
3105 /**
3106 * Returns the number of weeks in the week year represented by this
3107 * {@code Calendar}.
3108 *
3109 * <p>The default implementation of this method throws an
3110 * {@code UnsupportedOperationException}.
3111 *
3112 * @return the number of weeks in the week year.
3113 * @throws UnsupportedOperationException
3114 * if any week year numbering isn't supported in this
3115 * {@code Calendar}.
3116 * @see #WEEK_OF_YEAR
3117 * @see #isWeekDateSupported()
3118 * @see #getWeekYear()
3119 * @see #getActualMaximum(int)
3120 * @since 1.7
3121 */
3122 public int getWeeksInWeekYear() {
3123 throw new UnsupportedOperationException();
3124 }
3125
3126 /**
3127 * Returns the minimum value for the given calendar field of this
3128 * <code>Calendar</code> instance. The minimum value is defined as
3129 * the smallest value returned by the {@link #get(int) get} method
3130 * for any possible time value. The minimum value depends on
3131 * calendar system specific parameters of the instance.
3132 *
3133 * @param field the calendar field.
3334 return other;
3335 }
3336 catch (CloneNotSupportedException e) {
3337 // this shouldn't happen, since we are Cloneable
3338 throw new InternalError(e);
3339 }
3340 }
3341
3342 private static final String[] FIELD_NAME = {
3343 "ERA", "YEAR", "MONTH", "WEEK_OF_YEAR", "WEEK_OF_MONTH", "DAY_OF_MONTH",
3344 "DAY_OF_YEAR", "DAY_OF_WEEK", "DAY_OF_WEEK_IN_MONTH", "AM_PM", "HOUR",
3345 "HOUR_OF_DAY", "MINUTE", "SECOND", "MILLISECOND", "ZONE_OFFSET",
3346 "DST_OFFSET"
3347 };
3348
3349 /**
3350 * Returns the name of the specified calendar field.
3351 *
3352 * @param field the calendar field
3353 * @return the calendar field name
3354 * @throws IndexOutOfBoundsException if <code>field</code> is negative,
3355 * equal to or greater than {@code FIELD_COUNT}.
3356 */
3357 static String getFieldName(int field) {
3358 return FIELD_NAME[field];
3359 }
3360
3361 /**
3362 * Return a string representation of this calendar. This method
3363 * is intended to be used only for debugging purposes, and the
3364 * format of the returned string may vary between implementations.
3365 * The returned string may be empty but may not be <code>null</code>.
3366 *
3367 * @return a string representation of this calendar.
3368 */
3369 @Override
3370 public String toString() {
3371 // NOTE: BuddhistCalendar.toString() interprets the string
3372 // produced by this method so that the Gregorian year number
3373 // is substituted by its B.E. year value. It relies on
3374 // "...,YEAR=<year>,..." or "...,YEAR=?,...".
|