You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/07 23:43:44 UTC
svn commit: r772785 [10/12] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java Thu May 7 21:43:41 2009
@@ -27,10 +27,17 @@
import org.apache.harmony.luni.util.Msg;
/**
- * SimpleTimeZone represents a local time zone and its daylight savings time
- * rules for the gregorian calendar.
- *
+ * {@code SimpleTimeZone} is a concrete subclass of {@code TimeZone}
+ * that represents a time zone for use with a Gregorian calendar. This class
+ * does not handle historical changes.
+ * <p>
+ * Use a negative value for {@code dayOfWeekInMonth} to indicate that
+ * {@code SimpleTimeZone} should count from the end of the month
+ * backwards. For example, Daylight Savings Time ends at the last
+ * (dayOfWeekInMonth = -1) Sunday in October, at 2 AM in standard time.
+ *
* @see Calendar
+ * @see GregorianCalendar
* @see TimeZone
*/
public class SimpleTimeZone extends TimeZone {
@@ -56,19 +63,21 @@
private static final int DOM_MODE = 1, DOW_IN_MONTH_MODE = 2,
DOW_GE_DOM_MODE = 3, DOW_LE_DOM_MODE = 4;
- /* Constant for representing start or end time in GMT time mode. */
+ /**
+ * The constant for representing a start or end time in GMT time mode.
+ */
public static final int UTC_TIME = 2;
- /*
- * Constant for representing start or end time in standard local time mode,
- * based on timezone's raw offset from GMT, does not include Daylight
+ /**
+ * The constant for representing a start or end time in standard local time mode,
+ * based on timezone's raw offset from GMT; does not include Daylight
* savings.
*/
public static final int STANDARD_TIME = 1;
- /*
- * Constant for representing start or end time in local wall clock time
- * mode, based on timezone's adjusted offset from GMT, it does include
+ /**
+ * The constant for representing a start or end time in local wall clock time
+ * mode, based on timezone's adjusted offset from GMT; includes
* Daylight savings.
*/
public static final int WALL_TIME = 0;
@@ -84,13 +93,16 @@
private final transient boolean isSimple;
/**
- * Constructs a new SimpleTimeZone using the specified offset for standard
- * time from GMT and the specified time zone ID.
+ * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT
+ * and time zone ID. Timezone IDs can be obtained from
+ * {@code TimeZone.getAvailableIDs}. Normally you should use {@code TimeZone.getDefault} to
+ * construct a {@code TimeZone}.
*
* @param offset
- * the offset from GMT of standard time in milliseconds
+ * the given base time zone offset to GMT.
* @param name
- * the time zone ID
+ * the time zone ID which is obtained from
+ * {@code TimeZone.getAvailableIDs}.
*/
public SimpleTimeZone(int offset, final String name) {
setID(name);
@@ -106,36 +118,73 @@
}
/**
- * Constructs a new SimpleTimeZone using the specified offset for standard
- * time from GMT, the specified time zone ID and the rules for daylight
- * savings time.
- *
+ * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+ * time zone ID, and times to start and end the daylight savings time. Timezone IDs can
+ * be obtained from {@code TimeZone.getAvailableIDs}. Normally you should use
+ * {@code TimeZone.getDefault} to create a {@code TimeZone}. For a time zone that does not
+ * use daylight saving time, do not use this constructor; instead you should
+ * use {@code SimpleTimeZone(rawOffset, ID)}.
+ * <p>
+ * By default, this constructor specifies day-of-week-in-month rules. That
+ * is, if the {@code startDay} is 1, and the {@code startDayOfWeek} is {@code SUNDAY}, then this
+ * indicates the first Sunday in the {@code startMonth}. A {@code startDay} of -1 likewise
+ * indicates the last Sunday. However, by using negative or zero values for
+ * certain parameters, other types of rules can be specified.
+ * <p>
+ * Day of month: To specify an exact day of the month, such as March 1, set
+ * {@code startDayOfWeek} to zero.
+ * <p>
+ * Day of week after day of month: To specify the first day of the week
+ * occurring on or after an exact day of the month, make the day of the week
+ * negative. For example, if {@code startDay} is 5 and {@code startDayOfWeek} is {@code -MONDAY},
+ * this indicates the first Monday on or after the 5th day of the
+ * {@code startMonth}.
+ * <p>
+ * Day of week before day of month: To specify the last day of the week
+ * occurring on or before an exact day of the month, make the day of the
+ * week and the day of the month negative. For example, if {@code startDay} is {@code -21}
+ * and {@code startDayOfWeek} is {@code -WEDNESDAY}, this indicates the last Wednesday on or
+ * before the 21st of the {@code startMonth}.
+ * <p>
+ * The above examples refer to the {@code startMonth}, {@code startDay}, and {@code startDayOfWeek};
+ * the same applies for the {@code endMonth}, {@code endDay}, and {@code endDayOfWeek}.
+ * <p>
+ * The daylight savings time difference is set to the default value: one hour.
+ *
* @param offset
- * the offset from GMT of standard time in milliseconds
+ * the given base time zone offset to GMT.
* @param name
- * the time zone ID
+ * the time zone ID which is obtained from
+ * {@code TimeZone.getAvailableIDs}.
* @param startMonth
- * the Calendar month in which daylight savings time starts
+ * the daylight savings starting month. The month indexing is 0-based. eg, 0
+ * for January.
* @param startDay
- * the occurrence of the day of the week on which daylight
- * savings time starts
+ * the daylight savings starting day-of-week-in-month. Please see
+ * the member description for an example.
* @param startDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * starts
+ * the daylight savings starting day-of-week. Please see the
+ * member description for an example.
* @param startTime
- * the time of day in milliseconds on which daylight savings time
- * starts
+ * the daylight savings starting time in local wall time, which
+ * is standard time in this case. Please see the member
+ * description for an example.
* @param endMonth
- * the Calendar month in which daylight savings time ends
+ * the daylight savings ending month. The month indexing is 0-based. eg, 0 for
+ * January.
* @param endDay
- * the occurrence of the day of the week on which daylight
- * savings time ends
+ * the daylight savings ending day-of-week-in-month. Please see
+ * the member description for an example.
* @param endDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * ends
+ * the daylight savings ending day-of-week. Please see the member
+ * description for an example.
* @param endTime
- * the time of day in milliseconds standard time on which
- * daylight savings time ends
+ * the daylight savings ending time in local wall time, which is
+ * daylight time in this case. Please see the member description
+ * for an example.
+ * @throws IllegalArgumentException
+ * if the month, day, dayOfWeek, or time parameters are out of
+ * range for the start or end rule.
*/
public SimpleTimeZone(int offset, String name, int startMonth,
int startDay, int startDayOfWeek, int startTime, int endMonth,
@@ -145,38 +194,46 @@
}
/**
- * Constructs a new SimpleTimeZone using the specified offset for standard
- * time from GMT, the specified time zone ID and the rules for daylight
- * savings time.
- *
+ * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+ * time zone ID, times to start and end the daylight savings time, and
+ * the daylight savings time difference in milliseconds.
+ *
* @param offset
- * the offset from GMT of standard time in milliseconds
+ * the given base time zone offset to GMT.
* @param name
- * the time zone ID
+ * the time zone ID which is obtained from
+ * {@code TimeZone.getAvailableIDs}.
* @param startMonth
- * the Calendar month in which daylight savings time starts
+ * the daylight savings starting month. Month is 0-based. eg, 0
+ * for January.
* @param startDay
- * the occurrence of the day of the week on which daylight
- * savings time starts
+ * the daylight savings starting day-of-week-in-month. Please see
+ * the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param startDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * starts
+ * the daylight savings starting day-of-week. Please see the
+ * description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param startTime
- * the time of day in milliseconds on which daylight savings time
- * starts
+ * The daylight savings starting time in local wall time, which
+ * is standard time in this case. Please see the description of
+ * {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param endMonth
- * the Calendar month in which daylight savings time ends
+ * the daylight savings ending month. Month is 0-based. eg, 0 for
+ * January.
* @param endDay
- * the occurrence of the day of the week on which daylight
- * savings time ends
+ * the daylight savings ending day-of-week-in-month. Please see
+ * the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param endDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * ends
+ * the daylight savings ending day-of-week. Please see the description of
+ * {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param endTime
- * the time of day in milliseconds standard time on which
- * daylight savings time ends
+ * the daylight savings ending time in local wall time, which is
+ * daylight time in this case. Please see the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)}
+ * for an example.
* @param daylightSavings
- * the daylight savings time difference in milliseconds
+ * the daylight savings time difference in milliseconds.
+ * @throws IllegalArgumentException
+ * if the month, day, dayOfWeek, or time parameters are out of
+ * range for the start or end rule.
*/
public SimpleTimeZone(int offset, String name, int startMonth,
int startDay, int startDayOfWeek, int startTime, int endMonth,
@@ -207,42 +264,50 @@
}
/**
- * Constructs a new SimpleTimeZone using the specified offset for standard
- * time from GMT, the specified time zone ID, the rules for daylight savings
- * time, and the modes indicating UTC, standard, or wall time.
- *
+ * Construct a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+ * time zone ID, times to start and end the daylight savings time including a
+ * mode specifier, the daylight savings time difference in milliseconds.
+ * The mode specifies either {@link #WALL_TIME}, {@link #STANDARD_TIME}, or
+ * {@link #UTC_TIME}.
+ *
* @param offset
- * the offset from GMT of standard time in milliseconds
+ * the given base time zone offset to GMT.
* @param name
- * the time zone ID
+ * the time zone ID which is obtained from
+ * {@code TimeZone.getAvailableIDs}.
* @param startMonth
- * the Calendar month in which daylight savings time starts
+ * the daylight savings starting month. The month indexing is 0-based. eg, 0
+ * for January.
* @param startDay
- * the occurrence of the day of the week on which daylight
- * savings time starts
+ * the daylight savings starting day-of-week-in-month. Please see
+ * the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param startDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * starts
+ * the daylight savings starting day-of-week. Please see the
+ * description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param startTime
- * the time of day in milliseconds on which daylight savings time
- * starts
+ * the time of day in milliseconds on which daylight savings
+ * time starts, based on the {@code startTimeMode}.
* @param startTimeMode
- * the mode (UTC, standard, or wall time) of the start time value
- * @param endMonth
- * the Calendar month in which daylight savings time ends
+ * the mode (UTC, standard, or wall time) of the start time
+ * value.
* @param endDay
- * the occurrence of the day of the week on which daylight
- * savings time ends
+ * the day of the week on which daylight savings time ends.
+ * @param endMonth
+ * the daylight savings ending month. The month indexing is 0-based. eg, 0 for
+ * January.
* @param endDayOfWeek
- * the Calendar day of the week on which daylight savings time
- * ends
+ * the daylight savings ending day-of-week. Please see the description of
+ * {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
* @param endTime
- * the time of day in milliseconds standard time on which
- * daylight savings time ends
+ * the time of day in milliseconds on which daylight savings
+ * time ends, based on the {@code endTimeMode}.
* @param endTimeMode
- * the mode (UTC, standard, or wall time) of the end time value
+ * the mode (UTC, standard, or wall time) of the end time value.
* @param daylightSavings
- * the daylight savings time difference in milliseconds
+ * the daylight savings time difference in milliseconds.
+ * @throws IllegalArgumentException
+ * if the month, day, dayOfWeek, or time parameters are out of
+ * range for the start or end rule.
*/
public SimpleTimeZone(int offset, String name, int startMonth,
int startDay, int startDayOfWeek, int startTime, int startTimeMode,
@@ -256,11 +321,10 @@
}
/**
- * Answers a new SimpleTimeZone with the same ID, rawOffset and daylight
+ * Returns a new {@code SimpleTimeZone} with the same ID, {@code rawOffset} and daylight
* savings time rules as this SimpleTimeZone.
*
- * @return a shallow copy of this SimpleTimeZone
- *
+ * @return a shallow copy of this {@code SimpleTimeZone}.
* @see java.lang.Cloneable
*/
@Override
@@ -273,15 +337,14 @@
}
/**
- * Compares the specified object to this SimpleTimeZone and answer if they
- * are equal. The object must be an instance of SimpleTimeZone and have the
- * same properties.
+ * Compares the specified object to this {@code SimpleTimeZone} and returns whether they
+ * are equal. The object must be an instance of {@code SimpleTimeZone} and have the
+ * same internal data.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this SimpleTimeZone,
- * false otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this
+ * {@code SimpleTimeZone}, {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -303,13 +366,6 @@
&& endTime == tz.endTime && endMode == tz.endMode && dstSavings == tz.dstSavings));
}
- /**
- * Gets the daylight savings offset in milliseconds for this SimpleTimeZone.
- *
- * If this SimpleTimezone does not observe daylight savings, returns 0.
- *
- * @return the daylight savings offset in milliseconds
- */
@Override
public int getDSTSavings() {
if (!useDaylight) {
@@ -318,26 +374,6 @@
return dstSavings;
}
- /**
- * Gets the offset from GMT of this SimpleTimeZone for the specified date
- * and time. The offset includes daylight savings time if the specified date
- * and time are within the daylight savings time period.
- *
- * @param era
- * the GregorianCalendar era, either GregorianCalendar.BC or
- * GregorianCalendar.AD
- * @param year
- * the year
- * @param month
- * the Calendar month
- * @param day
- * the day of the month
- * @param dayOfWeek
- * the Calendar day of the week
- * @param time
- * the time of day in milliseconds
- * @return the offset from GMT in milliseconds
- */
@Override
public int getOffset(int era, int year, int month, int day, int dayOfWeek,
int time) {
@@ -351,36 +387,21 @@
return icuTZ.getOffset(era, year, month, day, dayOfWeek, time);
}
- /**
- * Gets the offset from GMT of this SimpleTimeZone for the specified date.
- * The offset includes daylight savings time if the specified date is within
- * the daylight savings time period.
- *
- * @param time
- * the date in milliseconds since January 1, 1970 00:00:00 GMT
- * @return the offset from GMT in milliseconds
- */
@Override
public int getOffset(long time) {
return icuTZ.getOffset(time);
}
- /**
- * Gets the offset for standard time from GMT for this SimpleTimeZone.
- *
- * @return the offset from GMT of standard time in milliseconds
- */
@Override
public int getRawOffset() {
return rawOffset;
}
/**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
+ * Returns an integer hash code for the receiver. Objects which are equal
+ * return the same value for this method.
*
+ * @return the receiver's hash.
* @see #equals
*/
@Override
@@ -394,15 +415,6 @@
return hashCode;
}
- /**
- * Answers if the specified TimeZone has the same raw offset and daylight
- * savings time rules as this SimpleTimeZone.
- *
- * @param zone
- * a TimeZone
- * @return true when the TimeZones have the same raw offset and daylight
- * savings time rules, false otherwise
- */
@Override
public boolean hasSameRules(TimeZone zone) {
if (!(zone instanceof SimpleTimeZone)) {
@@ -424,15 +436,6 @@
&& endTime == tz.endTime && endMode == tz.endMode;
}
- /**
- * Answers if the specified Date is in the daylight savings time period for
- * this SimpleTimeZone.
- *
- * @param time
- * a Date
- * @return true when the Date is in the daylight savings time period, false
- * otherwise
- */
@Override
public boolean inDaylightTime(Date time) {
return icuTZ.inDaylightTime(time);
@@ -446,10 +449,10 @@
}
/**
- * Sets the daylight savings offset in milliseconds for this SimpleTimeZone.
+ * Sets the daylight savings offset in milliseconds for this {@code SimpleTimeZone}.
*
* @param milliseconds
- * the daylight savings offset in milliseconds
+ * the daylight savings offset in milliseconds.
*/
public void setDSTSavings(int milliseconds) {
if (milliseconds > 0) {
@@ -514,13 +517,13 @@
* Sets the rule which specifies the end of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time ends
+ * the {@code Calendar} month in which daylight savings time ends.
* @param dayOfMonth
- * the Calendar day of the month on which daylight savings time
- * ends
+ * the {@code Calendar} day of the month on which daylight savings time
+ * ends.
* @param time
* the time of day in milliseconds standard time on which
- * daylight savings time ends
+ * daylight savings time ends.
*/
public void setEndRule(int month, int dayOfMonth, int time) {
endMonth = month;
@@ -538,16 +541,16 @@
* Sets the rule which specifies the end of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time ends
+ * the {@code Calendar} month in which daylight savings time ends.
* @param day
* the occurrence of the day of the week on which daylight
- * savings time ends
+ * savings time ends.
* @param dayOfWeek
- * the Calendar day of the week on which daylight savings time
- * ends
+ * the {@code Calendar} day of the week on which daylight savings time
+ * ends.
* @param time
* the time of day in milliseconds standard time on which
- * daylight savings time ends
+ * daylight savings time ends.
*/
public void setEndRule(int month, int day, int dayOfWeek, int time) {
endMonth = month;
@@ -565,17 +568,17 @@
* Sets the rule which specifies the end of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time ends
+ * the {@code Calendar} month in which daylight savings time ends.
* @param day
- * the Calendar day of the month
+ * the {@code Calendar} day of the month.
* @param dayOfWeek
- * the Calendar day of the week on which daylight savings time
- * ends
+ * the {@code Calendar} day of the week on which daylight savings time
+ * ends.
* @param time
* the time of day in milliseconds on which daylight savings time
- * ends
+ * ends.
* @param after
- * selects the day after or before the day of month
+ * selects the day after or before the day of month.
*/
public void setEndRule(int month, int day, int dayOfWeek, int time,
boolean after) {
@@ -591,10 +594,10 @@
}
/**
- * Sets the offset for standard time from GMT for this SimpleTimeZone.
+ * Sets the offset for standard time from GMT for this {@code SimpleTimeZone}.
*
* @param offset
- * the offset from GMT of standard time in milliseconds
+ * the offset from GMT of standard time in milliseconds.
*/
@Override
public void setRawOffset(int offset) {
@@ -638,13 +641,13 @@
* Sets the rule which specifies the start of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time starts
+ * the {@code Calendar} month in which daylight savings time starts.
* @param dayOfMonth
- * the Calendar day of the month on which daylight savings time
- * starts
+ * the {@code Calendar} day of the month on which daylight savings time
+ * starts.
* @param time
* the time of day in milliseconds on which daylight savings time
- * starts
+ * starts.
*/
public void setStartRule(int month, int dayOfMonth, int time) {
startMonth = month;
@@ -662,16 +665,16 @@
* Sets the rule which specifies the start of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time starts
+ * the {@code Calendar} month in which daylight savings time starts.
* @param day
* the occurrence of the day of the week on which daylight
- * savings time starts
+ * savings time starts.
* @param dayOfWeek
- * the Calendar day of the week on which daylight savings time
- * starts
+ * the {@code Calendar} day of the week on which daylight savings time
+ * starts.
* @param time
* the time of day in milliseconds on which daylight savings time
- * starts
+ * starts.
*/
public void setStartRule(int month, int day, int dayOfWeek, int time) {
startMonth = month;
@@ -689,17 +692,17 @@
* Sets the rule which specifies the start of daylight savings time.
*
* @param month
- * the Calendar month in which daylight savings time starts
+ * the {@code Calendar} month in which daylight savings time starts.
* @param day
- * the Calendar day of the month
+ * the {@code Calendar} day of the month.
* @param dayOfWeek
- * the Calendar day of the week on which daylight savings time
- * starts
+ * the {@code Calendar} day of the week on which daylight savings time
+ * starts.
* @param time
* the time of day in milliseconds on which daylight savings time
- * starts
+ * starts.
* @param after
- * selects the day after or before the day of month
+ * selects the day after or before the day of month.
*/
public void setStartRule(int month, int day, int dayOfWeek, int time,
boolean after) {
@@ -715,11 +718,11 @@
}
/**
- * Sets the starting year for daylight savings time in this SimpleTimeZone.
+ * Sets the starting year for daylight savings time in this {@code SimpleTimeZone}.
* Years before this start year will always be in standard time.
*
* @param year
- * the starting year
+ * the starting year.
*/
public void setStartYear(int year) {
startYear = year;
@@ -727,9 +730,9 @@
}
/**
- * Answers the string representation of this SimpleTimeZone.
+ * Returns the string representation of this {@code SimpleTimeZone}.
*
- * @return the string representation of this SimpleTimeZone
+ * @return the string representation of this {@code SimpleTimeZone}.
*/
@Override
public String toString() {
@@ -759,12 +762,6 @@
+ ",endTime=" + endTime + "]"; //$NON-NLS-1$//$NON-NLS-2$
}
- /**
- * Answers if this TimeZone has a daylight savings time period.
- *
- * @return true if this time zone has a daylight savings time period, false
- * otherwise
- */
@Override
public boolean useDaylightTime() {
return useDaylight;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java Thu May 7 21:43:41 2009
@@ -17,99 +17,109 @@
package java.util;
+
/**
- * SortedMap is a Map where the iterators sequence in order of the sorted keys.
+ * A map that has its keys ordered. The sorting is according to either the
+ * natural ordering of its keys or the ordering given by a specified comparator.
*/
-public interface SortedMap<K, V> extends Map<K, V> {
-
+public interface SortedMap<K,V> extends Map<K,V> {
+
/**
- * Answers the Comparator used to compare elements in this SortedMap.
+ * Returns the comparator used to compare keys in this sorted map.
*
- * @return a Comparator or null if the natural order is used
+ * @return the comparator or {@code null} if the natural order is used.
*/
public Comparator<? super K> comparator();
/**
- * Answer the first sorted key in this SortedMap.
+ * Returns the first key in this sorted map.
*
- * @return the first sorted key
- *
- * @exception NoSuchElementException
- * when this SortedMap is empty
+ * @return the first key in this sorted map.
+ * @throws NoSuchElementException
+ * if this sorted map is empty.
*/
public K firstKey();
/**
- * Answers a <code>SortedMap</code> of the specified portion of this
- * <code>SortedMap</code> which contains keys less than the end key. Users
- * should be aware that the return value is actually backed by this
- * <code>SortedMap</code>. Hence any modifications made to one will be
- * immediately visible to the other.
- *
+ * Returns a sorted map over a range of this sorted map with all keys that
+ * are less than the specified {@code endKey}. Changes to the returned
+ * sorted map are reflected in this sorted map and vice versa.
+ * <p>
+ * Note: The returned map will not allow an insertion of a key outside the
+ * specified range.
+ *
* @param endKey
- * the end key
- * @return a submap where the keys are less than <code>endKey</code>
- *
- * @exception ClassCastException
- * when the class of the end key is inappropriate for this
- * SubMap
- * @exception NullPointerException
- * when the end key is null and this SortedMap does not
- * support null keys
- */
- public SortedMap<K, V> headMap(K endKey);
-
- /**
- * Answers the last sorted key in this SortedMap.
- *
- * @return the last sorted key
- *
- * @exception NoSuchElementException
- * when this SortedMap is empty
+ * the high boundary of the range specified.
+ * @return a sorted map where the keys are less than {@code endKey}.
+ * @throws ClassCastException
+ * if the class of the end key is inappropriate for this sorted
+ * map.
+ * @throws NullPointerException
+ * if the end key is {@code null} and this sorted map does not
+ * support {@code null} keys.
+ * @throws IllegalArgumentException
+ * if this map is itself a sorted map over a range of another
+ * map and the specified key is outside of its range.
+ */
+ public SortedMap<K,V> headMap(K endKey);
+
+ /**
+ * Returns the last key in this sorted map.
+ *
+ * @return the last key in this sorted map.
+ * @throws NoSuchElementException
+ * if this sorted map is empty.
*/
public K lastKey();
/**
- * Answers a SortedMap of the specified portion of this SortedMap which
- * contains keys greater or equal to the start key but less than the end
- * key. Users should be aware that the return value is actually backed by
- * this <code>SortedMap</code>. Hence any modifications made to one will
- * be immediately visible to the other.
- *
+ * Returns a sorted map over a range of this sorted map with all keys
+ * greater than or equal to the specified {@code startKey} and less than the
+ * specified {@code endKey}. Changes to the returned sorted map are
+ * reflected in this sorted map and vice versa.
+ * <p>
+ * Note: The returned map will not allow an insertion of a key outside the
+ * specified range.
+ *
* @param startKey
- * the start key
+ * the low boundary of the range (inclusive).
* @param endKey
- * the end key
- * @return a submap where the keys are greater or equal to
- * <code>startKey</code> and less than <code>endKey</code>
- *
- * @exception ClassCastException
- * when the class of the start or end key is inappropriate
- * for this SubMap
- * @exception NullPointerException
- * when the start or end key is null and this SortedMap does
- * not support null keys
- * @exception IllegalArgumentException
- * when the start key is greater than the end key
- */
- public SortedMap<K, V> subMap(K startKey, K endKey);
-
- /**
- * Answers a SortedMap of the specified portion of this SortedMap which
- * contains keys greater or equal to the start key. The returned SortedMap
- * is backed by this SortedMap so changes to one are reflected by the other.
+ * the high boundary of the range (exclusive),
+ * @return a sorted map with the key from the specified range.
+ * @throws ClassCastException
+ * if the class of the start or end key is inappropriate for
+ * this sorted map.
+ * @throws NullPointerException
+ * if the start or end key is {@code null} and this sorted map
+ * does not support {@code null} keys.
+ * @throws IllegalArgumentException
+ * if the start key is greater than the end key, or if this map
+ * is itself a sorted map over a range of another sorted map and
+ * the specified range is outside of its range.
+ */
+ public SortedMap<K,V> subMap(K startKey, K endKey);
+
+ /**
+ * Returns a sorted map over a range of this sorted map with all keys that
+ * are greater than or equal to the specified {@code startKey}. Changes to
+ * the returned sorted map are reflected in this sorted map and vice versa.
+ * <p>
+ * Note: The returned map will not allow an insertion of a key outside the
+ * specified range.
*
* @param startKey
- * the start key
- * @return a submap where the keys are greater or equal to
- * <code>startKey</code>
- *
- * @exception ClassCastException
- * when the class of the start key is inappropriate for this
- * SubMap
- * @exception NullPointerException
- * when the start key is null and this SortedMap does not
- * support null keys
+ * the low boundary of the range specified.
+ * @return a sorted map where the keys are greater or equal to
+ * {@code startKey}.
+ * @throws ClassCastException
+ * if the class of the start key is inappropriate for this
+ * sorted map.
+ * @throws NullPointerException
+ * if the start key is {@code null} and this sorted map does not
+ * support {@code null} keys.
+ * @throws IllegalArgumentException
+ * if this map itself a sorted map over a range of another map
+ * and the specified key is outside of its range.
*/
- public SortedMap<K, V> tailMap(K startKey);
+ public SortedMap<K,V> tailMap(K startKey);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java Thu May 7 21:43:41 2009
@@ -17,97 +17,103 @@
package java.util;
+
/**
- * SortedSet is a Set which iterates its elements in sorted order.
+ * SortedSet is a Set which iterates over its elements in a sorted order. The
+ * order is determined either by the elements natural ordering, or by a
+ * {@link Comparator} which is passed into a concrete implementation at
+ * construction time. All elements in this set must be mutually comparable. The
+ * ordering in this set must be consistent with {@code equals} of its elements.
+ *
+ * @see Comparator
+ * @see Comparable
*/
public interface SortedSet<E> extends Set<E> {
-
+
/**
- * Answers the Comparator used to compare elements in this SortedSet.
+ * Returns the comparator used to compare elements in this {@code SortedSet}.
*
- * @return a Comparator or null if the natural order is used
+ * @return a comparator or null if the natural ordering is used.
*/
public Comparator<? super E> comparator();
/**
- * Answer the first sorted element in this SortedSet.
- *
- * @return the first sorted element
+ * Returns the first element in this {@code SortedSet}. The first element
+ * is the lowest element.
*
- * @exception NoSuchElementException
- * when this SortedSet is empty
+ * @return the first element.
+ * @throws NoSuchElementException
+ * when this {@code SortedSet} is empty.
*/
public E first();
/**
- * Answers a SortedSet of the specified portion of this SortedSet which
- * contains elements less than the end element. The returned SortedSet is
- * backed by this SortedSet so changes to one are reflected by the other.
+ * Returns a {@code SortedSet} of the specified portion of this
+ * {@code SortedSet} which contains elements less than the end element. The
+ * returned {@code SortedSet} is backed by this {@code SortedSet} so changes
+ * to one set are reflected by the other.
*
* @param end
- * the end element
- * @return a subset where the elements are less than <code>end</code>
- *
- * @exception ClassCastException
- * when the class of the end element is inappropriate for
- * this SubSet
- * @exception NullPointerException
- * when the end element is null and this SortedSet does not
- * support null elements
+ * the end element.
+ * @return a subset where the elements are less than {@code end}.
+ * @throws ClassCastException
+ * when the class of the end element is inappropriate for this
+ * SubSet.
+ * @throws NullPointerException
+ * when the end element is null and this {@code SortedSet} does
+ * not support null elements.
*/
public SortedSet<E> headSet(E end);
/**
- * Answer the last sorted element in this SortedSet.
- *
- * @return the last sorted element
+ * Returns the last element in this {@code SortedSet}. The last element is
+ * the highest element.
*
- * @exception NoSuchElementException
- * when this SortedSet is empty
+ * @return the last element.
+ * @throws NoSuchElementException
+ * when this {@code SortedSet} is empty.
*/
public E last();
/**
- * Answers a SortedSet of the specified portion of this SortedSet which
- * contains elements greater or equal to the start element but less than the
- * end element. The returned SortedSet is backed by this SortedMap so
- * changes to one are reflected by the other.
+ * Returns a {@code SortedSet} of the specified portion of this
+ * {@code SortedSet} which contains elements greater or equal to the start
+ * element but less than the end element. The returned {@code SortedSet} is
+ * backed by this SortedMap so changes to one set are reflected by the
+ * other.
*
* @param start
- * the start element
+ * the start element.
* @param end
- * the end element
- * @return a subset where the elements are greater or equal to
- * <code>start</code> and less than <code>end</code>
- *
- * @exception ClassCastException
- * when the class of the start or end element is
- * inappropriate for this SubSet
- * @exception NullPointerException
- * when the start or end element is null and this SortedSet
- * does not support null elements
- * @exception IllegalArgumentException
- * when the start element is greater than the end element
+ * the end element.
+ * @return a subset where the elements are greater or equal to {@code start}
+ * and less than {@code end}.
+ * @throws ClassCastException
+ * when the class of the start or end element is inappropriate
+ * for this SubSet.
+ * @throws NullPointerException
+ * when the start or end element is null and this
+ * {@code SortedSet} does not support null elements.
+ * @throws IllegalArgumentException
+ * when the start element is greater than the end element.
*/
public SortedSet<E> subSet(E start, E end);
/**
- * Answers a SortedSet of the specified portion of this SortedSet which
- * contains elements greater or equal to the start element. The returned
- * SortedSet is backed by this SortedSet so changes to one are reflected by
- * the other.
+ * Returns a {@code SortedSet} of the specified portion of this
+ * {@code SortedSet} which contains elements greater or equal to the start
+ * element. The returned {@code SortedSet} is backed by this
+ * {@code SortedSet} so changes to one set are reflected by the other.
*
* @param start
- * the start element
- * @return a subset where the elements are greater or equal to
- * <code>start</code>
- *
- * @exception ClassCastException
- * when the class of the start element is inappropriate for
- * this SubSet
- * @exception NullPointerException
- * when the start element is null and this SortedSet does not
- * support null elements
+ * the start element.
+ * @return a subset where the elements are greater or equal to {@code start} .
+ * @throws ClassCastException
+ * when the class of the start element is inappropriate for this
+ * SubSet.
+ * @throws NullPointerException
+ * when the start element is null and this {@code SortedSet}
+ * does not support null elements.
*/
public SortedSet<E> tailSet(E start);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java Thu May 7 21:43:41 2009
@@ -18,25 +18,25 @@
package java.util;
/**
- * <code>Stack</code> is a Last-In/First-Out(LIFO) data structure which
- * represents a stack of objects. It enables users to pop and push onto the
- * stack, including null objects. There is no limit to the size of the stack
+ * {@code Stack} is a Last-In/First-Out(LIFO) data structure which represents a
+ * stack of objects. It enables users to pop to and push from the stack,
+ * including null objects. There is no limit to the size of the stack.
*/
public class Stack<E> extends Vector<E> {
private static final long serialVersionUID = 1224463164541339165L;
/**
- * Constructs a stack with the default size of <code>Vector</code>.
+ * Constructs a stack with the default size of {@code Vector}.
*/
public Stack() {
super();
}
/**
- * Determines if the stack is empty or not.
+ * Returns whether the stack is empty or not.
*
- * @return true if the stack is empty, false otherwise
+ * @return {@code true} if the stack is empty, {@code false} otherwise.
*/
public boolean empty() {
return elementCount == 0;
@@ -45,9 +45,9 @@
/**
* Returns the element at the top of the stack without removing it.
*
- * @return the element at the top of the Stack
- * @exception EmptyStackException
- * when empty() is true
+ * @return the element at the top of the stack.
+ * @throws EmptyStackException
+ * if the stack is empty.
* @see #pop
*/
@SuppressWarnings("unchecked")
@@ -63,8 +63,8 @@
* Returns the element at the top of the stack and removes it.
*
* @return the element at the top of the stack.
- * @exception EmptyStackException
- * when empty() is true
+ * @throws EmptyStackException
+ * if the stack is empty.
* @see #peek
* @see #push
*/
@@ -81,13 +81,11 @@
}
/**
- * Pushes the object from the parameter onto the top of the stack.
+ * Pushes the specified object onto the top of the stack.
*
* @param object
- * The object to be added to the stack
- *
- * @return the object argument
- *
+ * The object to be added on top of the stack.
+ * @return the object argument.
* @see #peek
* @see #pop
*/
@@ -97,18 +95,20 @@
}
/**
- * Returns the index of the first occurrence of the object.
+ * Returns the index of the first occurrence of the object, starting from
+ * the top of the stack.
*
- * @return the index of the first occurrence of the object
- * @param object
- * the object to be searched
+ * @return the index of the first occurrence of the object, assuming that
+ * the topmost object on the stack has a distance of one.
+ * @param o
+ * the object to be searched.
*/
- public synchronized int search(Object object) {
+ public synchronized int search(Object o) {
final Object[] dumpArray = elementData;
final int size = elementCount;
- if (object != null) {
+ if (o != null) {
for (int i = size - 1; i >= 0; i--) {
- if (object.equals(dumpArray[i])) {
+ if (o.equals(dumpArray[i])) {
return size - i;
}
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java Thu May 7 21:43:41 2009
@@ -18,14 +18,88 @@
package java.util;
/**
- * String tokenizer is used to break a string apart into tokens.
- *
- * If returnDelimiters is false, successive calls to nextToken() return maximal
- * blocks of characters that do not contain a delimiter.
- *
- * If returnDelimiters is true, delimiters are considered to be tokens, and
- * successive calls to nextToken() return either a one character delimiter, or a
- * maximal block of text between delimiters.
+ * The {@code StringTokenizer} class allows an application to break a string
+ * into tokens by performing code point comparison. The {@code StringTokenizer}
+ * methods do not distinguish among identifiers, numbers, and quoted strings,
+ * nor do they recognize and skip comments.
+ * <p>
+ * The set of delimiters (the codepoints that separate tokens) may be specified
+ * either at creation time or on a per-token basis.
+ * <p>
+ * An instance of {@code StringTokenizer} behaves in one of three ways,
+ * depending on whether it was created with the {@code returnDelimiters} flag
+ * having the value {@code true} or {@code false}:
+ * <ul>
+ * <li>If returnDelims is {@code false}, delimiter code points serve to separate
+ * tokens. A token is a maximal sequence of consecutive code points that are not
+ * delimiters.
+ * <li>If returnDelims is {@code true}, delimiter code points are themselves
+ * considered to be tokens. In this case a token will be received for each
+ * delimiter code point.
+ * </ul>
+ * <p>
+ * A token is thus either one delimiter code point, or a maximal sequence of
+ * consecutive code points that are not delimiters.
+ * <p>
+ * A {@code StringTokenizer} object internally maintains a current position
+ * within the string to be tokenized. Some operations advance this current
+ * position past the code point processed.
+ * <p>
+ * A token is returned by taking a substring of the string that was used to
+ * create the {@code StringTokenizer} object.
+ * <p>
+ * Here's an example of the use of the default delimiter {@code StringTokenizer}
+ * : <blockquote>
+ *
+ * <pre>
+ * StringTokenizer st = new StringTokenizer("this is a test");
+ * while (st.hasMoreTokens()) {
+ * println(st.nextToken());
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * This prints the following output: <blockquote>
+ *
+ * <pre>
+ * this
+ * is
+ * a
+ * test
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Here's an example of how to use a {@code StringTokenizer} with a user
+ * specified delimiter: <blockquote>
+ *
+ * <pre>
+ * StringTokenizer st = new StringTokenizer(
+ * "this is a test with supplementary characters \ud800\ud800\udc00\udc00",
+ * " \ud800\udc00");
+ * while (st.hasMoreTokens()) {
+ * println(st.nextToken());
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * This prints the following output: <blockquote>
+ *
+ * <pre>
+ * this
+ * is
+ * a
+ * test
+ * with
+ * supplementary
+ * characters
+ * \ud800
+ * \udc00
+ * </pre>
+ *
+ * </blockquote>
*/
public class StringTokenizer implements Enumeration<Object> {
@@ -38,39 +112,46 @@
private int position;
/**
- * Constructs a new StringTokenizer for string using whitespace as the
- * delimiter, returnDelimiters is false.
+ * Constructs a new {@code StringTokenizer} for the parameter string using
+ * whitespace as the delimiter. The {@code returnDelimiters} flag is set to
+ * {@code false}.
*
* @param string
- * the string to be tokenized
+ * the string to be tokenized.
*/
public StringTokenizer(String string) {
this(string, " \t\n\r\f", false); //$NON-NLS-1$
}
/**
- * Constructs a new StringTokenizer for string using the specified
- * delimiters, returnDelimiters is false.
+ * Constructs a new {@code StringTokenizer} for the parameter string using
+ * the specified delimiters. The {@code returnDelimiters} flag is set to
+ * {@code false}. If {@code delimiters} is {@code null}, this constructor
+ * doesn't throw an {@code Exception}, but later calls to some methods might
+ * throw a {@code NullPointerException}.
*
* @param string
- * the string to be tokenized
+ * the string to be tokenized.
* @param delimiters
- * the delimiters to use
+ * the delimiters to use.
*/
public StringTokenizer(String string, String delimiters) {
this(string, delimiters, false);
}
/**
- * Constructs a new StringTokenizer for string using the specified
- * delimiters and returning delimiters as tokens when specified.
+ * Constructs a new {@code StringTokenizer} for the parameter string using
+ * the specified delimiters, returning the delimiters as tokens if the
+ * parameter {@code returnDelimiters} is {@code true}. If {@code delimiters}
+ * is null this constructor doesn't throw an {@code Exception}, but later
+ * calls to some methods might throw a {@code NullPointerException}.
*
* @param string
- * the string to be tokenized
+ * the string to be tokenized.
* @param delimiters
- * the delimiters to use
+ * the delimiters to use.
* @param returnDelimiters
- * true to return each delimiter as a token
+ * {@code true} to return each delimiter as a token.
*/
public StringTokenizer(String string, String delimiters,
boolean returnDelimiters) {
@@ -86,8 +167,8 @@
/**
* Returns the number of unprocessed tokens remaining in the string.
*
- * @return number of tokens that can be retreived before an exception will
- * result
+ * @return number of tokens that can be retreived before an {@code
+ * Exception} will result from a call to {@code nextToken()}.
*/
public int countTokens() {
int count = 0;
@@ -110,18 +191,19 @@
}
/**
- * Returns true if unprocessed tokens remain.
+ * Returns {@code true} if unprocessed tokens remain. This method is
+ * implemented in order to satisfy the {@code Enumeration} interface.
*
- * @return true if unprocessed tokens remain
+ * @return {@code true} if unprocessed tokens remain.
*/
public boolean hasMoreElements() {
return hasMoreTokens();
}
/**
- * Returns true if unprocessed tokens remain.
+ * Returns {@code true} if unprocessed tokens remain.
*
- * @return true if unprocessed tokens remain
+ * @return {@code true} if unprocessed tokens remain.
*/
public boolean hasMoreTokens() {
if (delimiters == null) {
@@ -142,22 +224,23 @@
}
/**
- * Returns the next token in the string as an Object.
+ * Returns the next token in the string as an {@code Object}. This method is
+ * implemented in order to satisfy the {@code Enumeration} interface.
*
- * @return next token in the string as an Object
- * @exception NoSuchElementException
- * if no tokens remain
+ * @return next token in the string as an {@code Object}
+ * @throws NoSuchElementException
+ * if no tokens remain.
*/
public Object nextElement() {
return nextToken();
}
/**
- * Returns the next token in the string as a String.
+ * Returns the next token in the string as a {@code String}.
*
- * @return next token in the string as a String
- * @exception NoSuchElementException
- * if no tokens remain
+ * @return next token in the string as a {@code String}.
+ * @throws NoSuchElementException
+ * if no tokens remain.
*/
public String nextToken() {
if (delimiters == null) {
@@ -190,14 +273,14 @@
}
/**
- * Returns the next token in the string as a String. The delimiters used are
- * changed to the specified delimiters.
+ * Returns the next token in the string as a {@code String}. The delimiters
+ * used are changed to the specified delimiters.
*
* @param delims
- * the new delimiters to use
- * @return next token in the string as a String
- * @exception NoSuchElementException
- * if no tokens remain
+ * the new delimiters to use.
+ * @return next token in the string as a {@code String}.
+ * @throws NoSuchElementException
+ * if no tokens remain.
*/
public String nextToken(String delims) {
this.delimiters = delims;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java Thu May 7 21:43:41 2009
@@ -24,22 +24,53 @@
import org.apache.harmony.luni.util.PriviAction;
/**
- * TimeZone is an abstract class which represents a local time zone and its
- * daylight savings time rules. Subclasses support a particular calendar type,
- * such as the gregorian calendar.
- *
- * Please note the type returned by factory methods, i.e.
- * <code>getDefault()</code> and <code>getTimeZone(String)</code>, is
- * implementation dependent, so that it may introduce serialization
- * incompatibility issue between different implementations. Harmony returns
- * instance of {@link SimpleTimeZone SimpleTimeZone} so that the bytes
- * serialized by Harmony can be deserialized on other implementation
- * successfully, but the reverse compatibility cannot be guaranteed.
- *
+ * {@code TimeZone} represents a time zone offset, taking into account
+ * daylight savings.
+ * <p>
+ * Typically, you get a {@code TimeZone} using {@code getDefault}
+ * which creates a {@code TimeZone} based on the time zone where the
+ * program is running. For example, for a program running in Japan,
+ * {@code getDefault} creates a {@code TimeZone} object based on
+ * Japanese Standard Time.
+ * <p>
+ * You can also get a {@code TimeZone} using {@code getTimeZone}
+ * along with a time zone ID. For instance, the time zone ID for the U.S.
+ * Pacific Time zone is "America/Los_Angeles". So, you can get a U.S. Pacific
+ * Time {@code TimeZone} object with the following: <blockquote>
+ *
+ * <pre>
+ * TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
+ * </pre>
+ *
+ * </blockquote> You can use the {@code getAvailableIDs} method to iterate
+ * through all the supported time zone IDs. You can then choose a supported ID
+ * to get a {@code TimeZone}. If the time zone you want is not
+ * represented by one of the supported IDs, then you can create a custom time
+ * zone ID with the following syntax: <blockquote>
+ *
+ * <pre>
+ * GMT[+|-]hh[[:]mm]
+ * </pre>
+ *
+ * </blockquote> For example, you might specify GMT+14:00 as a custom time zone
+ * ID. The {@code TimeZone} that is returned when you specify a custom
+ * time zone ID does not include daylight savings time.
+ * <p>
+ * For compatibility with JDK 1.1.x, some other three-letter time zone IDs (such
+ * as "PST", "CTT", "AST") are also supported. However, <strong>their use is
+ * deprecated</strong> because the same abbreviation is often used for multiple
+ * time zones (for example, "CST" could be U.S. "Central Standard Time" and
+ * "China Standard Time"), and the Java platform can then only recognize one of
+ * them.
+ * <p>
+ * Please note the type returned by factory methods, i.e. {@code getDefault()}
+ * and {@code getTimeZone(String)}, is implementation dependent, so it may
+ * introduce serialization incompatibility issues between different
+ * implementations.
+ *
* @see GregorianCalendar
* @see SimpleTimeZone
*/
-
public abstract class TimeZone implements Serializable, Cloneable {
private static final long serialVersionUID = 3581463369166924961L;
@@ -93,17 +124,15 @@
/**
* Constructs a new instance of this class.
- *
*/
public TimeZone() {
}
/**
- * Answers a new TimeZone with the same ID, rawOffset and daylight savings
- * time rules as this TimeZone.
- *
- * @return a shallow copy of this TimeZone
- *
+ * Returns a new {@code TimeZone} with the same ID, {@code rawOffset} and daylight savings
+ * time rules as this {@code TimeZone}.
+ *
+ * @return a shallow copy of this {@code TimeZone}.
* @see java.lang.Cloneable
*/
@Override
@@ -117,9 +146,10 @@
}
/**
- * Gets the available time zone IDs.
+ * Gets the available time zone IDs. Any one of these IDs can be passed to
+ * {@code get()} to create the corresponding {@code TimeZone} instance.
*
- * @return an array of time zone ID strings
+ * @return an array of time zone ID strings.
*/
public static synchronized String[] getAvailableIDs() {
return com.ibm.icu.util.TimeZone.getAvailableIDs();
@@ -127,11 +157,12 @@
/**
* Gets the available time zone IDs which match the specified offset from
- * GMT.
+ * GMT. Any one of these IDs can be passed to {@code get()} to create the corresponding
+ * {@code TimeZone} instance.
*
* @param offset
- * the offset from GMT in milliseconds
- * @return an array of time zone ID strings
+ * the offset from GMT in milliseconds.
+ * @return an array of time zone ID strings.
*/
public static synchronized String[] getAvailableIDs(int offset) {
String[] availableIDs = com.ibm.icu.util.TimeZone.getAvailableIDs();
@@ -153,7 +184,7 @@
/**
* Gets the default time zone.
*
- * @return the default time zone
+ * @return the default time zone.
*/
public static synchronized TimeZone getDefault() {
if (Default == null) {
@@ -163,56 +194,58 @@
}
/**
- * Gets the LONG name for this TimeZone for the default Locale in standard
+ * Gets the LONG name for this {@code TimeZone} for the default {@code Locale} in standard
* time. If the name is not available, the result is in the format
- * GMT[+-]hh:mm.
+ * {@code GMT[+-]hh:mm}.
*
- * @return the TimeZone name
+ * @return the {@code TimeZone} name.
*/
public final String getDisplayName() {
return getDisplayName(false, LONG, Locale.getDefault());
}
/**
- * Gets the LONG name for this TimeZone for the specified Locale in standard
+ * Gets the LONG name for this {@code TimeZone} for the specified {@code Locale} in standard
* time. If the name is not available, the result is in the format
- * GMT[+-]hh:mm.
+ * {@code GMT[+-]hh:mm}.
*
* @param locale
- * the Locale
- * @return the TimeZone name
+ * the {@code Locale}.
+ * @return the {@code TimeZone} name.
*/
public final String getDisplayName(Locale locale) {
return getDisplayName(false, LONG, locale);
}
/**
- * Gets the specified style of name (LONG or SHORT) for this TimeZone for
- * the default Locale in either standard or daylight time as specified. If
- * the name is not available, the result is in the format GMT[+-]hh:mm.
+ * Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
+ * the default {@code Locale} in either standard or daylight time as specified. If
+ * the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
*
* @param daylightTime
- * true for daylight time, false for standard time
+ * {@code true} for daylight time, {@code false} for standard
+ * time.
* @param style
- * Either LONG or SHORT
- * @return the TimeZone name
+ * either {@code LONG} or {@code SHORT}.
+ * @return the {@code TimeZone} name.
*/
public final String getDisplayName(boolean daylightTime, int style) {
return getDisplayName(daylightTime, style, Locale.getDefault());
}
/**
- * Gets the specified style of name (LONG or SHORT) for this TimeZone for
- * the specified Locale in either standard or daylight time as specified. If
- * the name is not available, the result is in the format GMT[+-]hh:mm.
+ * Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
+ * the specified {@code Locale} in either standard or daylight time as specified. If
+ * the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
*
* @param daylightTime
- * true for daylight time, false for standard time
+ * {@code true} for daylight time, {@code false} for standard
+ * time.
* @param style
- * Either LONG or SHORT
+ * either LONG or SHORT.
* @param locale
- * the Locale
- * @return the TimeZone name
+ * either {@code LONG} or {@code SHORT}.
+ * @return the {@code TimeZone} name.
*/
public String getDisplayName(boolean daylightTime, int style, Locale locale) {
if(icuTimeZone == null || !ID.equals(icuTimeZone.getID())){
@@ -223,16 +256,16 @@
}
/**
- * Gets the ID of this TimeZone.
+ * Gets the ID of this {@code TimeZone}.
*
- * @return the time zone ID string
+ * @return the time zone ID string.
*/
public String getID() {
return ID;
}
/**
- * Gets the daylight savings offset in milliseconds for this TimeZone.
+ * Gets the daylight savings offset in milliseconds for this {@code TimeZone}.
* <p>
* This implementation returns 3600000 (1 hour), or 0 if the time zone does
* not observe daylight savings.
@@ -241,9 +274,8 @@
* hour.
* <p>
*
- * @return the daylight savings offset in milliseconds if this TimeZone
+ * @return the daylight savings offset in milliseconds if this {@code TimeZone}
* observes daylight savings, zero otherwise.
- *
*/
public int getDSTSavings() {
if (useDaylightTime()) {
@@ -253,13 +285,13 @@
}
/**
- * Gets the offset from GMT of this TimeZone for the specified date. The
+ * Gets the offset from GMT of this {@code TimeZone} for the specified date. The
* offset includes daylight savings time if the specified date is within the
* daylight savings time period.
*
* @param time
* the date in milliseconds since January 1, 1970 00:00:00 GMT
- * @return the offset from GMT in milliseconds
+ * @return the offset from GMT in milliseconds.
*/
public int getOffset(long time) {
if (inDaylightTime(new Date(time))) {
@@ -269,42 +301,42 @@
}
/**
- * Gets the offset from GMT of this TimeZone for the specified date and
+ * Gets the offset from GMT of this {@code TimeZone} for the specified date and
* time. The offset includes daylight savings time if the specified date and
* time are within the daylight savings time period.
*
* @param era
- * the GregorianCalendar era, either GregorianCalendar.BC or
- * GregorianCalendar.AD
+ * the {@code GregorianCalendar} era, either {@code GregorianCalendar.BC} or
+ * {@code GregorianCalendar.AD}.
* @param year
- * the year
+ * the year.
* @param month
- * the Calendar month
+ * the {@code Calendar} month.
* @param day
- * the day of the month
+ * the day of the month.
* @param dayOfWeek
- * the Calendar day of the week
+ * the {@code Calendar} day of the week.
* @param time
- * the time of day in milliseconds
- * @return the offset from GMT in milliseconds
+ * the time of day in milliseconds.
+ * @return the offset from GMT in milliseconds.
*/
abstract public int getOffset(int era, int year, int month, int day,
int dayOfWeek, int time);
/**
- * Gets the offset for standard time from GMT for this TimeZone.
+ * Gets the offset for standard time from GMT for this {@code TimeZone}.
*
- * @return the offset from GMT in milliseconds
+ * @return the offset from GMT in milliseconds.
*/
abstract public int getRawOffset();
/**
- * Gets the time zone with the specified ID.
+ * Gets the {@code TimeZone} with the specified ID.
*
* @param name
- * a time zone string ID
- * @return the time zone with the specified ID or null if a time zone with
- * the specified ID does not exist
+ * a time zone string ID.
+ * @return the {@code TimeZone} with the specified ID or null if no {@code TimeZone} with
+ * the specified ID exists.
*/
public static synchronized TimeZone getTimeZone(String name) {
if (AvailableZones == null) {
@@ -382,12 +414,13 @@
}
/**
- * Answers if the specified TimeZone has the same raw offset as this
- * TimeZone.
+ * Returns whether the specified {@code TimeZone} has the same raw offset as this
+ * {@code TimeZone}.
*
* @param zone
- * a TimeZone
- * @return true when the TimeZones have the same raw offset, false otherwise
+ * a {@code TimeZone}.
+ * @return {@code true} when the {@code TimeZone} have the same raw offset, {@code false}
+ * otherwise.
*/
public boolean hasSameRules(TimeZone zone) {
if (zone == null) {
@@ -397,13 +430,13 @@
}
/**
- * Answers if the specified Date is in the daylight savings time period for
- * this TimeZone.
+ * Returns whether the specified {@code Date} is in the daylight savings time period for
+ * this {@code TimeZone}.
*
* @param time
- * a Date
- * @return true when the Date is in the daylight savings time period, false
- * otherwise
+ * a {@code Date}.
+ * @return {@code true} when the {@code Date} is in the daylight savings time period, {@code false}
+ * otherwise.
*/
abstract public boolean inDaylightTime(Date time);
@@ -419,10 +452,13 @@
}
/**
- * Sets the default time zone.
+ * Sets the default time zone. If passed {@code null}, then the next
+ * time {@link #getDefault} is called, the default time zone will be
+ * determined. This behavior is slightly different than the canonical
+ * description of this method, but it follows the spirit of it.
*
* @param timezone
- * a TimeZone object
+ * a {@code TimeZone} object.
*/
public static synchronized void setDefault(TimeZone timezone) {
if (timezone != null) {
@@ -494,10 +530,10 @@
}
/**
- * Sets the ID of this TimeZone.
+ * Sets the ID of this {@code TimeZone}.
*
* @param name
- * a string which is the time zone ID
+ * a string which is the time zone ID.
*/
public void setID(String name) {
if (name == null) {
@@ -507,18 +543,18 @@
}
/**
- * Sets the offset for standard time from GMT for this TimeZone.
+ * Sets the offset for standard time from GMT for this {@code TimeZone}.
*
* @param offset
- * the offset from GMT in milliseconds
+ * the offset from GMT in milliseconds.
*/
abstract public void setRawOffset(int offset);
/**
- * Answers if this TimeZone has a daylight savings time period.
+ * Returns whether this {@code TimeZone} has a daylight savings time period.
*
- * @return true if this time zone has a daylight savings time period, false
- * otherwise
+ * @return {@code true} if this {@code TimeZone} has a daylight savings time period, {@code false}
+ * otherwise.
*/
abstract public boolean useDaylightTime();
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java Thu May 7 21:43:41 2009
@@ -20,23 +20,36 @@
import org.apache.harmony.luni.util.Msg;
/**
- * Timers are used to schedule jobs for execution in a background process. A
+ * {@code Timer}s are used to schedule jobs for execution in a background process. A
* single thread is used for the scheduling and this thread has the option of
- * being a daemon thread. By calling <code>cancel</code> you can terminate a
- * timer and it's associated thread. All tasks which are scheduled to run after
+ * being a daemon thread. By calling {@code cancel} you can terminate a
+ * {@code Timer} and its associated thread. All tasks which are scheduled to run after
* this point are cancelled. Tasks are executed sequentially but are subject to
* the delays from other tasks run methods. If a specific task takes an
* excessive amount of time to run it may impact the time at which subsequent
* tasks may run.
* <p>
*
- * The Timer task does not offer any guarantees about the real-time nature of
- * scheduling tasks as it's underlying implementation relies on the
- * <code>Object.wait(long)</code> method.
+ * The {@code TimerTask} does not offer any guarantees about the real-time nature of
+ * scheduling tasks as its underlying implementation relies on the
+ * {@code Object.wait(long)} method.
* <p>
- *
- * Multiple threads can share a single Timer without the need for their own
+ * Multiple threads can share a single {@code Timer} without the need for their own
* synchronization.
+ * <p>
+ * A {@code Timer} can be set to schedule tasks either at a fixed rate or
+ * with a fixed period. Fixed-period execution is the default.
+ * <p>
+ * The difference between fixed-rate and fixed-period execution
+ * is the following: With fixed-rate execution, the start time of each
+ * successive run of the task is scheduled in absolute terms without regard for when the previous
+ * task run actually took place. This can result in a series of bunched-up runs
+ * (one launched immediately after another) if busy resources or other
+ * system delays prevent the {@code Timer} from firing for an extended time.
+ * With fixed-period execution, each successive run of the
+ * task is scheduled relative to the start time of the previous run of the
+ * task, so two runs of the task are never fired closer together in time than
+ * the specified {@code period}.
*
* @see TimerTask
* @see java.lang.Object#wait(long)
@@ -168,7 +181,7 @@
/**
* Vector consists of scheduled events, sorted according to
- * <code>when</code> field of TaskScheduled object.
+ * {@code when} field of TaskScheduled object.
*/
private TimerHeap tasks = new TimerHeap();
@@ -328,69 +341,61 @@
};
/**
- * Creates a new Timer which may be specified to be run as a Daemon Thread.
+ * Creates a new {@code Timer} which may be specified to be run as a daemon thread.
*
* @param isDaemon
- * true if Timers thread should be a daemon thread.
+ * {@code true} if the {@code Timer}'s thread should be a daemon thread.
*/
public Timer(boolean isDaemon) {
impl = new TimerImpl(isDaemon);
}
/**
- * Creates a new non-daemon Timer.
+ * Creates a new non-daemon {@code Timer}.
*/
public Timer() {
impl = new TimerImpl(false);
}
/**
- * Create a new timer with the given name and daemon status.
- *
- * The name is given the timer's background thread and if the flag is true
- * the thread is run as a daemon.
+ * Creates a new named {@code Timer} which may be specified to be run as a
+ * daemon thread.
*
* @param name
- * a name to associate with the timer thread.
+ * the name of the {@code Timer}.
* @param isDaemon
- * true if the timer thread should be a daemon, or false if it is
- * a regular thread that prevents the application terminating.
+ * true if {@code Timer}'s thread should be a daemon thread.
*/
public Timer(String name, boolean isDaemon) {
impl = new TimerImpl(name, isDaemon);
}
/**
- * Create a new timer whose thread has the given name.
- *
- * The name is given the timer's background thread, that is not run as a
- * daemon.
+ * Creates a new named {@code Timer} which does not run as a daemon thread.
*
* @param name
- * a name to associate with the timer thread.
+ * the name of the Timer.
*/
public Timer(String name) {
impl = new TimerImpl(name, false);
}
/**
- * Cancels the Timer and removed any scheduled tasks. If there is a
- * currently running task it is not effected. No more tasks may be scheduled
- * on this Timer. Subsequent calls do nothing.
+ * Cancels the {@code Timer} and removes any scheduled tasks. If there is a
+ * currently running task it is not affected. No more tasks may be scheduled
+ * on this {@code Timer}. Subsequent calls do nothing.
*/
public void cancel() {
impl.cancel();
}
/**
- * Purging the timer eagerly removes cancelled tasks.
- *
- * When a large number of tasks have been cancelled it may be helpful to
- * explicitly purge them from the timer rather than let them be removed
- * during normal expiry processing. This is a housekeeping task that does
- * not affect the timer's schedule tasks.
+ * Removes all canceled tasks from the task queue. If there are no
+ * other references on the tasks, then after this call they are free
+ * to be garbage collected.
*
- * @return the number of tasks that were purged.
+ * @return the number of canceled tasks that were removed from the task
+ * queue.
*/
public int purge() {
synchronized (impl) {
@@ -399,19 +404,18 @@
}
/**
- * Schedule a task for single execution. If when is less than the current
- * time, it will be scheduled to executed as soon as possible.
+ * Schedule a task for single execution. If {@code when} is less than the
+ * current time, it will be scheduled to be executed as soon as possible.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param when
- * Time of execution
- *
- * @exception IllegalArgumentException
- * if when.getTime() < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * time of execution.
+ * @throws IllegalArgumentException
+ * if {@code when.getTime() < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void schedule(TimerTask task, Date when) {
if (when.getTime() < 0) {
@@ -422,18 +426,17 @@
}
/**
- * Schedule a task for single execution after a specific delay.
+ * Schedule a task for single execution after a specified delay.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param delay
- * Amount of time before execution
- *
- * @exception IllegalArgumentException
- * if delay < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * amount of time before execution.
+ * @throws IllegalArgumentException
+ * if {@code delay < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void schedule(TimerTask task, long delay) {
if (delay < 0) {
@@ -443,20 +446,19 @@
}
/**
- * Schedule a task for repeated fix-delay execution after a specific delay.
+ * Schedule a task for repeated fixed-delay execution after a specific delay.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param delay
- * Amount of time before first execution
+ * amount of time before first execution.
* @param period
- * Amount of time between subsequent executions
- *
- * @exception IllegalArgumentException
- * if delay < 0 or period < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * amount of time between subsequent executions.
+ * @throws IllegalArgumentException
+ * if {@code delay < 0} or {@code period < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void schedule(TimerTask task, long delay, long period) {
if (delay < 0 || period <= 0) {
@@ -466,21 +468,20 @@
}
/**
- * Schedule a task for repeated fix-delay execution after a specific time
+ * Schedule a task for repeated fixed-delay execution after a specific time
* has been reached.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param when
- * Time of first execution
+ * time of first execution.
* @param period
- * Amount of time between subsequent executions
- *
- * @exception IllegalArgumentException
- * if when.getTime() < 0 or period < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * amount of time between subsequent executions.
+ * @throws IllegalArgumentException
+ * if {@code when.getTime() < 0} or {@code period < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void schedule(TimerTask task, Date when, long period) {
if (period <= 0 || when.getTime() < 0) {
@@ -492,22 +493,19 @@
/**
* Schedule a task for repeated fixed-rate execution after a specific delay
- * has been happened. The difference of fixed-rate is that it may bunch up
- * subsequent task runs to try to get the task repeating at it's desired
- * time.
+ * has passed.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param delay
- * Amount of time before first execution
+ * amount of time before first execution.
* @param period
- * Amount of time between subsequent executions
- *
- * @exception IllegalArgumentException
- * if delay < 0 or period < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * amount of time between subsequent executions.
+ * @throws IllegalArgumentException
+ * if {@code delay < 0} or {@code period < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void scheduleAtFixedRate(TimerTask task, long delay, long period) {
if (delay < 0 || period <= 0) {
@@ -518,22 +516,19 @@
/**
* Schedule a task for repeated fixed-rate execution after a specific time
- * has been reached. The difference of fixed-rate is that it may bunch up
- * subsequent task runs to try to get the task repeating at it's desired
- * time.
+ * has been reached.
*
* @param task
- * The task to schedule
+ * the task to schedule.
* @param when
- * Time of first execution
+ * time of first execution.
* @param period
- * Amount of time between subsequent executions
- *
- * @exception IllegalArgumentException
- * if when.getTime() < 0 or period < 0
- * @exception IllegalStateException
- * if the timer has been cancelled, the task has been
- * scheduled or cancelled.
+ * amount of time between subsequent executions.
+ * @throws IllegalArgumentException
+ * if {@code when.getTime() < 0} or {@code period < 0}.
+ * @throws IllegalStateException
+ * if the {@code Timer} has been canceled, or if the task has been
+ * scheduled or canceled.
*/
public void scheduleAtFixedRate(TimerTask task, Date when, long period) {
if (period <= 0 || when.getTime() < 0) {