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 [6/12] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/GregorianCalendar.java Thu May 7 21:43:41 2009
@@ -22,13 +22,164 @@
import java.io.ObjectOutputStream;
/**
- * GregorianCalendar provides the conversion between Dates and integer calendar
- * fields, such as the month, year or minute, for the Gregorian calendar. See
- * Calendar for the defined fields.
- *
+ * {@code GregorianCalendar} is a concrete subclass of {@link Calendar}
+ * and provides the standard calendar used by most of the world.
+ *
+ * <p>
+ * The standard (Gregorian) calendar has 2 eras, BC and AD.
+ *
+ * <p>
+ * This implementation handles a single discontinuity, which corresponds by
+ * default to the date the Gregorian calendar was instituted (October 15, 1582
+ * in some countries, later in others). The cutover date may be changed by the
+ * caller by calling {@code setGregorianChange()}.
+ *
+ * <p>
+ * Historically, in those countries which adopted the Gregorian calendar first,
+ * October 4, 1582 was thus followed by October 15, 1582. This calendar models
+ * this correctly. Before the Gregorian cutover, {@code GregorianCalendar}
+ * implements the Julian calendar. The only difference between the Gregorian and
+ * the Julian calendar is the leap year rule. The Julian calendar specifies leap
+ * years every four years, whereas the Gregorian calendar omits century years
+ * which are not divisible by 400.
+ *
+ * <p>
+ * {@code GregorianCalendar} implements <em>proleptic</em> Gregorian
+ * and Julian calendars. That is, dates are computed by extrapolating the
+ * current rules indefinitely far backward and forward in time. As a result,
+ * {@code GregorianCalendar} may be used for all years to generate
+ * meaningful and consistent results. However, dates obtained using
+ * {@code GregorianCalendar} are historically accurate only from March 1,
+ * 4 AD onward, when modern Julian calendar rules were adopted. Before this
+ * date, leap year rules were applied irregularly, and before 45 BC the Julian
+ * calendar did not even exist.
+ *
+ * <p>
+ * Prior to the institution of the Gregorian calendar, New Year's Day was March
+ * 25. To avoid confusion, this calendar always uses January 1. A manual
+ * adjustment may be made if desired for dates that are prior to the Gregorian
+ * changeover and which fall between January 1 and March 24.
+ *
+ * <p>
+ * Values calculated for the {@code WEEK_OF_YEAR} field range from 1 to
+ * 53. Week 1 for a year is the earliest seven day period starting on
+ * {@code getFirstDayOfWeek()} that contains at least
+ * {@code getMinimalDaysInFirstWeek()} days from that year. It thus
+ * depends on the values of {@code getMinimalDaysInFirstWeek()},
+ * {@code getFirstDayOfWeek()}, and the day of the week of January 1.
+ * Weeks between week 1 of one year and week 1 of the following year are
+ * numbered sequentially from 2 to 52 or 53 (as needed).
+ *
+ * <p>
+ * For example, January 1, 1998 was a Thursday. If
+ * {@code getFirstDayOfWeek()} is {@code MONDAY} and
+ * {@code getMinimalDaysInFirstWeek()} is 4 (these are the values
+ * reflecting ISO 8601 and many national standards), then week 1 of 1998 starts
+ * on December 29, 1997, and ends on January 4, 1998. If, however,
+ * {@code getFirstDayOfWeek()} is {@code SUNDAY}, then week 1 of
+ * 1998 starts on January 4, 1998, and ends on January 10, 1998; the first three
+ * days of 1998 then are part of week 53 of 1997.
+ *
+ * <p>
+ * Values calculated for the {@code WEEK_OF_MONTH} field range from 0 or
+ * 1 to 4 or 5. Week 1 of a month (the days with <code>WEEK_OF_MONTH =
+ * 1</code>)
+ * is the earliest set of at least {@code getMinimalDaysInFirstWeek()}
+ * contiguous days in that month, ending on the day before
+ * {@code getFirstDayOfWeek()}. Unlike week 1 of a year, week 1 of a
+ * month may be shorter than 7 days, need not start on
+ * {@code getFirstDayOfWeek()}, and will not include days of the
+ * previous month. Days of a month before week 1 have a
+ * {@code WEEK_OF_MONTH} of 0.
+ *
+ * <p>
+ * For example, if {@code getFirstDayOfWeek()} is {@code SUNDAY}
+ * and {@code getMinimalDaysInFirstWeek()} is 4, then the first week of
+ * January 1998 is Sunday, January 4 through Saturday, January 10. These days
+ * have a {@code WEEK_OF_MONTH} of 1. Thursday, January 1 through
+ * Saturday, January 3 have a {@code WEEK_OF_MONTH} of 0. If
+ * {@code getMinimalDaysInFirstWeek()} is changed to 3, then January 1
+ * through January 3 have a {@code WEEK_OF_MONTH} of 1.
+ *
+ * <p>
+ * <strong>Example:</strong> <blockquote>
+ *
+ * <pre>
+ * // get the supported ids for GMT-08:00 (Pacific Standard Time)
+ * String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
+ * // if no ids were returned, something is wrong. get out.
+ * if (ids.length == 0)
+ * System.exit(0);
+ *
+ * // begin output
+ * System.out.println("Current Time");
+ *
+ * // create a Pacific Standard Time time zone
+ * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
+ *
+ * // set up rules for daylight savings time
+ * pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ * pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ *
+ * // create a GregorianCalendar with the Pacific Daylight time zone
+ * // and the current date and time
+ * Calendar calendar = new GregorianCalendar(pdt);
+ * Date trialTime = new Date();
+ * calendar.setTime(trialTime);
+ *
+ * // print out a bunch of interesting things
+ * System.out.println("ERA: " + calendar.get(Calendar.ERA));
+ * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
+ * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
+ * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
+ * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
+ * System.out.println("DATE: " + calendar.get(Calendar.DATE));
+ * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
+ * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
+ * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
+ * System.out.println("DAY_OF_WEEK_IN_MONTH: "
+ * + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
+ * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
+ * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
+ * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
+ * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
+ * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
+ * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
+ * System.out.println("ZONE_OFFSET: "
+ * + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
+ * System.out.println("DST_OFFSET: "
+ * + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
+
+ * System.out.println("Current Time, with hour reset to 3");
+ * calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
+ * calendar.set(Calendar.HOUR, 3);
+ * System.out.println("ERA: " + calendar.get(Calendar.ERA));
+ * System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
+ * System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
+ * System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
+ * System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
+ * System.out.println("DATE: " + calendar.get(Calendar.DATE));
+ * System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
+ * System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
+ * System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
+ * System.out.println("DAY_OF_WEEK_IN_MONTH: "
+ * + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
+ * System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
+ * System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
+ * System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
+ * System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
+ * System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
+ * System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
+ * System.out.println("ZONE_OFFSET: "
+ * + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
+ * System.out.println("DST_OFFSET: "
+ * + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
+ * </pre>
+ *
+ * </blockquote>
+ *
* @see Calendar
* @see TimeZone
- * @see SimpleTimeZone
*/
public class GregorianCalendar extends Calendar {
@@ -81,23 +232,23 @@
private int lastYearSkew = 0;
/**
- * Constructs a new GregorianCalendar initialized to the current date and
- * time.
+ * Constructs a new {@code GregorianCalendar} initialized to the current date and
+ * time with the default {@code Locale} and {@code TimeZone}.
*/
public GregorianCalendar() {
this(TimeZone.getDefault(), Locale.getDefault());
}
/**
- * Constructs a new GregorianCalendar initialized to midnight in the default
- * time zone on the specified date.
+ * Constructs a new {@code GregorianCalendar} initialized to midnight in the default
+ * {@code TimeZone} and {@code Locale} on the specified date.
*
* @param year
- * the year
+ * the year.
* @param month
- * the month
+ * the month.
* @param day
- * the day of the month
+ * the day of the month.
*/
public GregorianCalendar(int year, int month, int day) {
super(TimeZone.getDefault(), Locale.getDefault());
@@ -105,19 +256,19 @@
}
/**
- * Constructs a new GregorianCalendar initialized to the specified date and
- * time.
- *
+ * Constructs a new {@code GregorianCalendar} initialized to the specified date and
+ * time in the default {@code TimeZone} and {@code Locale}.
+ *
* @param year
- * the year
+ * the year.
* @param month
- * the month
+ * the month.
* @param day
- * the day of the month
+ * the day of the month.
* @param hour
- * the hour
+ * the hour.
* @param minute
- * the minute
+ * the minute.
*/
public GregorianCalendar(int year, int month, int day, int hour, int minute) {
super(TimeZone.getDefault(), Locale.getDefault());
@@ -125,21 +276,21 @@
}
/**
- * Constructs a new GregorianCalendar initialized to the specified date and
- * time.
+ * Constructs a new {@code GregorianCalendar} initialized to the specified date and
+ * time in the default {@code TimeZone} and {@code Locale}.
*
* @param year
- * the year
+ * the year.
* @param month
- * the month
+ * the month.
* @param day
- * the day of the month
+ * the day of the month.
* @param hour
- * the hour
+ * the hour.
* @param minute
- * the minute
+ * the minute.
* @param second
- * the second
+ * the second.
*/
public GregorianCalendar(int year, int month, int day, int hour,
int minute, int second) {
@@ -153,35 +304,35 @@
}
/**
- * Constructs a new GregorianCalendar initialized to the current date and
- * time and using the specified Locale.
+ * Constructs a new {@code GregorianCalendar} initialized to the current date and
+ * time and using the specified {@code Locale} and the default {@code TimeZone}.
*
* @param locale
- * the Locale
+ * the {@code Locale}.
*/
public GregorianCalendar(Locale locale) {
this(TimeZone.getDefault(), locale);
}
/**
- * Constructs a new GregorianCalendar initialized to the current date and
- * time and using the specified TimeZone.
+ * Constructs a new {@code GregorianCalendar} initialized to the current date and
+ * time and using the specified {@code TimeZone} and the default {@code Locale}.
*
* @param timezone
- * the TimeZone
+ * the {@code TimeZone}.
*/
public GregorianCalendar(TimeZone timezone) {
this(timezone, Locale.getDefault());
}
/**
- * Constructs a new GregorianCalendar initialized to the current date and
- * time and using the specified TimeZone and Locale.
+ * Constructs a new {@code GregorianCalendar} initialized to the current date and
+ * time and using the specified {@code TimeZone} and {@code Locale}.
*
* @param timezone
- * the TimeZone
+ * the {@code TimeZone}.
* @param locale
- * the Locale
+ * the {@code Locale}.
*/
public GregorianCalendar(TimeZone timezone, Locale locale) {
super(timezone, locale);
@@ -195,15 +346,15 @@
}
/**
- * Adds the specified amount to a Calendar field.
+ * Adds the specified amount to a {@code Calendar} field.
*
* @param field
- * the Calendar field to modify
+ * the {@code Calendar} field to modify.
* @param value
- * the amount to add to the field
+ * the amount to add to the field.
*
- * @exception IllegalArgumentException
- * when the specified field is DST_OFFSET or ZONE_OFFSET.
+ * @throws IllegalArgumentException
+ * if the specified field is DST_OFFSET or ZONE_OFFSET.
*/
@Override
public void add(int field, int value) {
@@ -299,9 +450,9 @@
}
/**
- * Creates new instance of GregorianCalendar with the same properties.
+ * Creates new instance of {@code GregorianCalendar} with the same properties.
*
- * @return a shallow copy of this GregorianCalendar
+ * @return a shallow copy of this {@code GregorianCalendar}.
*/
@Override
public Object clone() {
@@ -439,9 +590,6 @@
}
}
- /**
- * Computes the Calendar fields from the time.
- */
@Override
protected void computeFields() {
int zoneOffset = getTimeZone().getRawOffset();
@@ -544,13 +692,6 @@
}
}
- /**
- * Computes the time from the Calendar fields.
- *
- * @exception IllegalArgumentException
- * when the time cannot be computed from the current field
- * values
- */
@Override
protected void computeTime() {
if (!isLenient()) {
@@ -835,19 +976,17 @@
}
/**
- * Compares the specified object to this GregorianCalendar and answer if
- * they are equal. The object must be an instance of GregorianCalendar and
+ * Compares the specified {@code Object} to this {@code GregorianCalendar} and returns whether
+ * they are equal. To be equal, the {@code Object} must be an instance of {@code GregorianCalendar} and
* have the same properties.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this GregorianCalendar,
- * false otherwise
- *
- * @exception IllegalArgumentException
- * when the time is not set and the time cannot be computed
- * from the current field values
- *
+ * the {@code Object} to compare with this {@code GregorianCalendar}.
+ * @return {@code true} if {@code object} is equal to this
+ * {@code GregorianCalendar}, {@code false} otherwise.
+ * @throws IllegalArgumentException
+ * if the time is not set and the time cannot be computed
+ * from the current field values.
* @see #hashCode
*/
@Override
@@ -861,8 +1000,8 @@
* example, the maximum number of days in the current month.
*
* @param field
- * the field
- * @return the maximum value of the specified field
+ * the field.
+ * @return the maximum value of the specified field.
*/
@Override
public int getActualMaximum(int field) {
@@ -929,11 +1068,11 @@
/**
* Gets the minimum value of the specified field for the current date. For
* the gregorian calendar, this value is the same as
- * <code>getMinimum()</code>.
+ * {@code getMinimum()}.
*
* @param field
- * the field
- * @return the minimum value of the specified field
+ * the field.
+ * @return the minimum value of the specified field.
*/
@Override
public int getActualMinimum(int field) {
@@ -942,11 +1081,11 @@
/**
* Gets the greatest minimum value of the specified field. For the gregorian
- * calendar, this value is the same as <code>getMinimum()</code>.
+ * calendar, this value is the same as {@code getMinimum()}.
*
* @param field
- * the field
- * @return the greatest minimum value of the specified field
+ * the field.
+ * @return the greatest minimum value of the specified field.
*/
@Override
public int getGreatestMinimum(int field) {
@@ -954,10 +1093,10 @@
}
/**
- * Answers the gregorian change date of this calendar. This is the date on
+ * Returns the gregorian change date of this calendar. This is the date on
* which the gregorian calendar came into effect.
*
- * @return a Date which represents the gregorian change date
+ * @return a {@code Date} which represents the gregorian change date.
*/
public final Date getGregorianChange() {
return new Date(gregorianCutover);
@@ -968,8 +1107,8 @@
* for the day of month field.
*
* @param field
- * the field
- * @return the smallest maximum value of the specified field
+ * the field.
+ * @return the smallest maximum value of the specified field.
*/
@Override
public int getLeastMaximum(int field) {
@@ -991,8 +1130,8 @@
* for the day of month field.
*
* @param field
- * the field
- * @return the greatest maximum value of the specified field
+ * the field.
+ * @return the greatest maximum value of the specified field.
*/
@Override
public int getMaximum(int field) {
@@ -1003,8 +1142,8 @@
* Gets the smallest minimum value of the specified field.
*
* @param field
- * the field
- * @return the smallest minimum value of the specified field
+ * the field.
+ * @return the smallest minimum value of the specified field.
*/
@Override
public int getMinimum(int field) {
@@ -1061,10 +1200,10 @@
}
/**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
+ * Returns an integer hash code for the receiver. Objects which are equal
+ * return the same value for this method.
*
- * @return the receiver's hash
+ * @return the receiver's hash.
*
* @see #equals
*/
@@ -1075,11 +1214,12 @@
}
/**
- * Answers if the specified year is a leap year.
+ * Returns whether the specified year is a leap year.
*
* @param year
- * the year
- * @return true if the specified year is a leap year, false otherwise
+ * the year.
+ * @return {@code true} if the specified year is a leap year, {@code false}
+ * otherwise.
*/
public boolean isLeapYear(int year) {
if (year > changeYear) {
@@ -1110,18 +1250,18 @@
}
/**
- * Adds the specified amount the specified field and wrap the value of the
+ * Adds the specified amount the specified field and wraps the value of the
* field when it goes beyond the maximum or minimum value for the current
* date. Other fields will be adjusted as required to maintain a consistent
* date.
*
* @param field
- * the field to roll
+ * the field to roll.
* @param value
- * the amount to add
+ * the amount to add.
*
- * @exception IllegalArgumentException
- * when an invalid field is specified
+ * @throws IllegalArgumentException
+ * if an invalid field is specified.
*/
@Override
public void roll(int field, int value) {
@@ -1227,19 +1367,19 @@
}
/**
- * Increment or decrement the specified field and wrap the value of the
+ * Increments or decrements the specified field and wraps the value of the
* field when it goes beyond the maximum or minimum value for the current
* date. Other fields will be adjusted as required to maintain a consistent
* date. For example, March 31 will roll to April 30 when rolling the month
* field.
*
* @param field
- * the field to roll
+ * the field to roll.
* @param increment
- * true to increment the field, false to decrement
- *
- * @exception IllegalArgumentException
- * when an invalid field is specified
+ * {@code true} to increment the field, {@code false} to
+ * decrement.
+ * @throws IllegalArgumentException
+ * if an invalid field is specified.
*/
@Override
public void roll(int field, boolean increment) {
@@ -1250,7 +1390,7 @@
* Sets the gregorian change date of this calendar.
*
* @param date
- * a Date which represents the gregorian change date
+ * a {@code Date} which represents the gregorian change date.
*/
public void setGregorianChange(Date date) {
gregorianCutover = date.getTime();
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashMap.java Thu May 7 21:43:41 2009
@@ -23,11 +23,8 @@
import java.io.Serializable;
/**
- * HashMap is the hash table based implementation of the Map interface.
- *
- * This implementation provides all of the optional map operations, and permits
- * null values and the null key. (The HashMap class is roughly equivalent to
- * Hashtable, except that it is unsynchronized and permits nulls.)
+ * HashMap is an implementation of Map. All optional operations (adding and
+ * removing) are supported. Keys and values can be any objects.
*/
public class HashMap<K, V> extends AbstractMap<K, V> implements Map<K, V>,
Cloneable, Serializable {
@@ -272,21 +269,19 @@
}
/**
- * Constructs a new empty instance of HashMap.
- *
+ * Constructs a new empty {@code HashMap} instance.
*/
public HashMap() {
this(DEFAULT_SIZE);
}
/**
- * Constructs a new instance of HashMap with the specified capacity.
+ * Constructs a new {@code HashMap} instance with the specified capacity.
*
* @param capacity
- * the initial capacity of this HashMap
- *
- * @exception IllegalArgumentException
- * when the capacity is less than zero
+ * the initial capacity of this hash map.
+ * @throws IllegalArgumentException
+ * when the capacity is less than zero.
*/
public HashMap(int capacity) {
this(capacity, 0.75f); // default load factor of 0.75
@@ -317,18 +312,16 @@
}
/**
- * Constructs a new instance of HashMap with the specified capacity and load
- * factor.
- *
+ * Constructs a new {@code HashMap} instance with the specified capacity and
+ * load factor.
*
* @param capacity
- * the initial capacity
+ * the initial capacity of this hash map.
* @param loadFactor
- * the initial load factor
- *
- * @exception IllegalArgumentException
+ * the initial load factor.
+ * @throws IllegalArgumentException
* when the capacity is less than zero or the load factor is
- * less or equal to zero
+ * less or equal to zero.
*/
public HashMap(int capacity, float loadFactor) {
if (capacity >= 0 && loadFactor > 0) {
@@ -343,11 +336,11 @@
}
/**
- * Constructs a new instance of HashMap containing the mappings from the
- * specified Map.
+ * Constructs a new {@code HashMap} instance containing the mappings from
+ * the specified map.
*
* @param map
- * the mappings to add
+ * the mappings to add.
*/
public HashMap(Map<? extends K, ? extends V> map) {
this(calculateCapacity(map.size()));
@@ -355,7 +348,7 @@
}
/**
- * Removes all mappings from this HashMap, leaving it empty.
+ * Removes all mappings from this hash map, leaving it empty.
*
* @see #isEmpty
* @see #size
@@ -370,11 +363,9 @@
}
/**
- * Answers a new HashMap with the same mappings and size as this HashMap.
+ * Returns a shallow copy of this map.
*
- * @return a shallow copy of this HashMap
- *
- * @see java.lang.Cloneable
+ * @return a shallow copy of this map.
*/
@Override
@SuppressWarnings("unchecked")
@@ -399,12 +390,12 @@
}
/**
- * Searches this HashMap for the specified key.
+ * Returns whether this map contains the specified key.
*
* @param key
- * the object to search for
- * @return true if <code>key</code> is a key of this HashMap, false
- * otherwise
+ * the key to search for.
+ * @return {@code true} if this map contains the specified key,
+ * {@code false} otherwise.
*/
@Override
public boolean containsKey(Object key) {
@@ -413,12 +404,12 @@
}
/**
- * Searches this HashMap for the specified value.
+ * Returns whether this map contains the specified value.
*
* @param value
- * the object to search for
- * @return true if <code>value</code> is a value of this HashMap, false
- * otherwise
+ * the value to search for.
+ * @return {@code true} if this map contains the specified value,
+ * {@code false} otherwise.
*/
@Override
public boolean containsValue(Object value) {
@@ -447,11 +438,11 @@
}
/**
- * Answers a Set of the mappings contained in this HashMap. Each element in
- * the set is a Map.Entry. The set is backed by this HashMap so changes to
- * one are reflected by the other. The set does not support adding.
+ * Returns a set containing all of the mappings in this map. Each mapping is
+ * an instance of {@link Map.Entry}. As the set is backed by this map,
+ * changes in one will be reflected in the other.
*
- * @return a Set of the mappings
+ * @return a set of the mappings.
*/
@Override
public Set<Map.Entry<K, V>> entrySet() {
@@ -459,11 +450,12 @@
}
/**
- * Answers the value of the mapping with the specified key.
+ * Returns the value of the mapping with the specified key.
*
* @param key
- * the key
- * @return the value of the mapping with the specified key
+ * the key.
+ * @return the value of the mapping with the specified key, or {@code null}
+ * if no mapping for the specified key is found.
*/
@Override
public V get(Object key) {
@@ -502,11 +494,11 @@
}
/**
- * Answers if this HashMap has no elements, a size of zero.
- *
- * @return true if this HashMap has no elements, false otherwise
+ * Returns whether this map is empty.
*
- * @see #size
+ * @return {@code true} if this map has no elements, {@code false}
+ * otherwise.
+ * @see #size()
*/
@Override
public boolean isEmpty() {
@@ -514,11 +506,11 @@
}
/**
- * Answers a Set of the keys contained in this HashMap. The set is backed by
- * this HashMap so changes to one are reflected by the other. The set does
- * not support adding.
+ * Returns a set of the keys contained in this map. The set is backed by
+ * this map so changes to one are reflected by the other. The set does not
+ * support adding.
*
- * @return a Set of the keys
+ * @return a set of the keys.
*/
@Override
public Set<K> keySet() {
@@ -558,11 +550,11 @@
* Maps the specified key to the specified value.
*
* @param key
- * the key
+ * the key.
* @param value
- * the value
- * @return the value of any previous mapping with the specified key or null
- * if there was no mapping
+ * the value.
+ * @return the value of any previous mapping with the specified key or
+ * {@code null} if there was no such mapping.
*/
@Override
public V put(K key, V value) {
@@ -614,14 +606,14 @@
}
/**
- * Copies all the mappings in the given map to this map. These mappings will
- * replace all mappings that this map had for any of the keys currently in
- * the given map.
+ * Copies all the mappings in the specified map to this map. These mappings
+ * will replace all mappings that this map had for any of the keys currently
+ * in the given map.
*
* @param map
- * the Map to copy mappings from
+ * the map to copy mappings from.
* @throws NullPointerException
- * if the given map is null
+ * if {@code map} is {@code null}.
*/
@Override
public void putAll(Map<? extends K, ? extends V> map) {
@@ -663,12 +655,12 @@
}
/**
- * Removes a mapping with the specified key from this HashMap.
+ * Removes the mapping with the specified key from this map.
*
* @param key
- * the key of the mapping to remove
- * @return the value of the removed mapping or null if key is not a key in
- * this HashMap
+ * the key of the mapping to remove.
+ * @return the value of the removed mapping or {@code null} if no mapping
+ * for the specified key was found.
*/
@Override
public V remove(Object key) {
@@ -732,9 +724,9 @@
}
/**
- * Answers the number of mappings in this HashMap.
+ * Returns the number of elements in this map.
*
- * @return the number of mappings in this HashMap
+ * @return the number of elements in this map.
*/
@Override
public int size() {
@@ -742,11 +734,23 @@
}
/**
- * Answers a Collection of the values contained in this HashMap. The
- * collection is backed by this HashMap so changes to one are reflected by
- * the other. The collection does not support adding.
+ * Returns a collection of the values contained in this map. The collection
+ * is backed by this map so changes to one are reflected by the other. The
+ * collection supports remove, removeAll, retainAll and clear operations,
+ * and it does not support add or addAll operations.
+ * <p>
+ * This method returns a collection which is the subclass of
+ * AbstractCollection. The iterator method of this subclass returns a
+ * "wrapper object" over the iterator of map's entrySet(). The {@code size}
+ * method wraps the map's size method and the {@code contains} method wraps
+ * the map's containsValue method.
+ * <p>
+ * The collection is created when this method is called for the first time
+ * and returned in response to all subsequent calls. This method may return
+ * different collections when multiple concurrent calls occur, since no
+ * synchronization is performed.
*
- * @return a Collection of the values
+ * @return a collection of the values contained in this map.
*/
@Override
public Collection<V> values() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/HashSet.java Thu May 7 21:43:41 2009
@@ -23,8 +23,8 @@
import java.io.Serializable;
/**
- * HashSet is an implementation of Set. All optional operations are supported,
- * adding and removing. The elements can be any objects.
+ * HashSet is an implementation of a Set. All optional operations (adding and
+ * removing) are supported. The elements can be any objects.
*/
public class HashSet<E> extends AbstractSet<E> implements Set<E>, Cloneable,
Serializable {
@@ -34,41 +34,41 @@
transient HashMap<E, HashSet<E>> backingMap;
/**
- * Constructs a new empty instance of HashSet.
+ * Constructs a new empty instance of {@code HashSet}.
*/
public HashSet() {
this(new HashMap<E, HashSet<E>>());
}
/**
- * Constructs a new instance of HashSet with the specified capacity.
+ * Constructs a new instance of {@code HashSet} with the specified capacity.
*
* @param capacity
- * the initial capacity of this HashSet
+ * the initial capacity of this {@code HashSet}.
*/
public HashSet(int capacity) {
this(new HashMap<E, HashSet<E>>(capacity));
}
/**
- * Constructs a new instance of HashSet with the specified capacity and load
- * factor.
+ * Constructs a new instance of {@code HashSet} with the specified capacity
+ * and load factor.
*
* @param capacity
- * the initial capacity
+ * the initial capacity.
* @param loadFactor
- * the initial load factor
+ * the initial load factor.
*/
public HashSet(int capacity, float loadFactor) {
this(new HashMap<E, HashSet<E>>(capacity, loadFactor));
}
/**
- * Constructs a new instance of HashSet containing the unique elements in
- * the specified collection.
+ * Constructs a new instance of {@code HashSet} containing the unique
+ * elements in the specified collection.
*
* @param collection
- * the collection of elements to add
+ * the collection of elements to add.
*/
public HashSet(Collection<? extends E> collection) {
this(new HashMap<E, HashSet<E>>(collection.size() < 6 ? 11 : collection
@@ -83,12 +83,12 @@
}
/**
- * Adds the specified object to this HashSet.
+ * Adds the specified object to this {@code HashSet} if not already present.
*
* @param object
- * the object to add
- * @return true when this HashSet did not already contain the object, false
- * otherwise
+ * the object to add.
+ * @return {@code true} when this {@code HashSet} did not already contain
+ * the object, {@code false} otherwise
*/
@Override
public boolean add(E object) {
@@ -96,7 +96,7 @@
}
/**
- * Removes all elements from this HashSet, leaving it empty.
+ * Removes all elements from this {@code HashSet}, leaving it empty.
*
* @see #isEmpty
* @see #size
@@ -107,10 +107,10 @@
}
/**
- * Answers a new HashSet with the same elements and size as this HashSet.
- *
- * @return a shallow copy of this HashSet
+ * Returns a new {@code HashSet} with the same elements and size as this
+ * {@code HashSet}.
*
+ * @return a shallow copy of this {@code HashSet}.
* @see java.lang.Cloneable
*/
@Override
@@ -126,12 +126,12 @@
}
/**
- * Searches this HashSet for the specified object.
+ * Searches this {@code HashSet} for the specified object.
*
* @param object
- * the object to search for
- * @return true if <code>object</code> is an element of this HashSet,
- * false otherwise
+ * the object to search for.
+ * @return {@code true} if {@code object} is an element of this
+ * {@code HashSet}, {@code false} otherwise.
*/
@Override
public boolean contains(Object object) {
@@ -139,10 +139,10 @@
}
/**
- * Answers if this HashSet has no elements, a size of zero.
- *
- * @return true if this HashSet has no elements, false otherwise
+ * Returns true if this {@code HashSet} has no elements, false otherwise.
*
+ * @return {@code true} if this {@code HashSet} has no elements,
+ * {@code false} otherwise.
* @see #size
*/
@Override
@@ -151,10 +151,9 @@
}
/**
- * Answers an Iterator on the elements of this HashSet.
- *
- * @return an Iterator on the elements of this HashSet
+ * Returns an Iterator on the elements of this {@code HashSet}.
*
+ * @return an Iterator on the elements of this {@code HashSet}.
* @see Iterator
*/
@Override
@@ -163,11 +162,11 @@
}
/**
- * Removes an occurrence of the specified object from this HashSet.
+ * Removes the specified object from this {@code HashSet}.
*
* @param object
- * the object to remove
- * @return true if this HashSet is modified, false otherwise
+ * the object to remove.
+ * @return {@code true} if the object was removed, {@code false} otherwise.
*/
@Override
public boolean remove(Object object) {
@@ -175,9 +174,9 @@
}
/**
- * Answers the number of elements in this HashSet.
+ * Returns the number of elements in this {@code HashSet}.
*
- * @return the number of elements in this HashSet
+ * @return the number of elements in this {@code HashSet}.
*/
@Override
public int size() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Hashtable.java Thu May 7 21:43:41 2009
@@ -25,8 +25,8 @@
import org.apache.harmony.luni.internal.nls.Messages;
/**
- * Hashtable associates keys with values. Keys and values cannot be null. The
- * size of the Hashtable is the number of key/value pairs it contains. The
+ * Hashtable associates keys with values. Both keys and values cannot be null.
+ * The size of the Hashtable is the number of key/value pairs it contains. The
* capacity is the number of key/value pairs the Hashtable can hold. The load
* factor is a float value which determines how full the Hashtable gets before
* expanding the capacity. If the load factor of the Hashtable is exceeded, the
@@ -228,18 +228,19 @@
}
/**
- * Constructs a new Hashtable using the default capacity and load factor.
+ * Constructs a new {@code Hashtable} using the default capacity and load
+ * factor.
*/
public Hashtable() {
this(11);
}
/**
- * Constructs a new Hashtable using the specified capacity and the default
- * load factor.
+ * Constructs a new {@code Hashtable} using the specified capacity and the
+ * default load factor.
*
* @param capacity
- * the initial capacity
+ * the initial capacity.
*/
public Hashtable(int capacity) {
if (capacity >= 0) {
@@ -254,12 +255,13 @@
}
/**
- * Constructs a new Hashtable using the specified capacity and load factor.
+ * Constructs a new {@code Hashtable} using the specified capacity and load
+ * factor.
*
* @param capacity
- * the initial capacity
+ * the initial capacity.
* @param loadFactor
- * the initial load factor
+ * the initial load factor.
*/
public Hashtable(int capacity, float loadFactor) {
if (capacity >= 0 && loadFactor > 0) {
@@ -274,11 +276,11 @@
}
/**
- * Constructs a new instance of Hashtable containing the mappings from the
- * specified Map.
+ * Constructs a new instance of {@code Hashtable} containing the mappings
+ * from the specified map.
*
* @param map
- * the mappings to add
+ * the mappings to add.
*/
public Hashtable(Map<? extends K, ? extends V> map) {
this(map.size() < 6 ? 11 : (map.size() * 4 / 3) + 11);
@@ -291,8 +293,8 @@
}
/**
- * Removes all key/value pairs from this Hashtable, leaving the size zero
- * and the capacity unchanged.
+ * Removes all key/value pairs from this {@code Hashtable}, leaving the
+ * size zero and the capacity unchanged.
*
* @see #isEmpty
* @see #size
@@ -304,11 +306,10 @@
}
/**
- * Answers a new Hashtable with the same key/value pairs, capacity and load
- * factor.
- *
- * @return a shallow copy of this Hashtable
+ * Returns a new {@code Hashtable} with the same key/value pairs, capacity
+ * and load factor.
*
+ * @return a shallow copy of this {@code Hashtable}.
* @see java.lang.Cloneable
*/
@Override
@@ -334,13 +335,13 @@
}
/**
- * Answers if this Hashtable contains the specified object as the value of
- * at least one of the key/value pairs.
+ * Returns true if this {@code Hashtable} contains the specified object as
+ * the value of at least one of the key/value pairs.
*
* @param value
- * the object to look for as a value in this Hashtable
- * @return true if object is a value in this Hashtable, false otherwise
- *
+ * the object to look for as a value in this {@code Hashtable}.
+ * @return {@code true} if object is a value in this {@code Hashtable},
+ * {@code false} otherwise.
* @see #containsKey
* @see java.lang.Object#equals
*/
@@ -362,13 +363,13 @@
}
/**
- * Answers if this Hashtable contains the specified object as a key of one
- * of the key/value pairs.
+ * Returns true if this {@code Hashtable} contains the specified object as a
+ * key of one of the key/value pairs.
*
* @param key
- * the object to look for as a key in this Hashtable
- * @return true if object is a key in this Hashtable, false otherwise
- *
+ * the object to look for as a key in this {@code Hashtable}.
+ * @return {@code true} if object is a key in this {@code Hashtable},
+ * {@code false} otherwise.
* @see #contains
* @see java.lang.Object#equals
*/
@@ -377,24 +378,23 @@
}
/**
- * Searches this Hashtable for the specified value.
+ * Searches this {@code Hashtable} for the specified value.
*
* @param value
- * the object to search for
- * @return true if <code>value</code> is a value of this Hashtable, false
- * otherwise
+ * the object to search for.
+ * @return {@code true} if {@code value} is a value of this
+ * {@code Hashtable}, {@code false} otherwise.
*/
public boolean containsValue(Object value) {
return contains(value);
}
/**
- * Answers an Enumeration on the values of this Hashtable. The results of
- * the Enumeration may be affected if the contents of this Hashtable are
- * modified.
- *
- * @return an Enumeration of the values of this Hashtable
+ * Returns an enumeration on the values of this {@code Hashtable}. The
+ * results of the Enumeration may be affected if the contents of this
+ * {@code Hashtable} are modified.
*
+ * @return an enumeration of the values of this {@code Hashtable}.
* @see #keys
* @see #size
* @see Enumeration
@@ -413,11 +413,12 @@
}
/**
- * Answers a Set of the mappings contained in this Hashtable. Each element
- * in the set is a Map.Entry. The set is backed by this Hashtable so changes
- * to one are reflected by the other. The set does not support adding.
+ * Returns a set of the mappings contained in this {@code Hashtable}. Each
+ * element in the set is a {@link Map.Entry}. The set is backed by this
+ * {@code Hashtable} so changes to one are reflected by the other. The set
+ * does not support adding.
*
- * @return a Set of the mappings
+ * @return a set of the mappings.
*/
public Set<Map.Entry<K, V>> entrySet() {
return new Collections.SynchronizedSet<Map.Entry<K, V>>(
@@ -465,15 +466,14 @@
}
/**
- * Compares the specified object to this Hashtable and answer if they are
- * equal. The object must be an instance of Map and contain the same
- * key/value pairs.
+ * Compares this {@code Hashtable} with the specified object and indicates
+ * if they are equal. In order to be equal, {@code object} must be an
+ * instance of Map and contain the same key/value pairs.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this Map, false
- * otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this Map,
+ * {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -499,13 +499,13 @@
}
/**
- * Answers the value associated with the specified key in this Hashtable.
+ * Returns the value associated with the specified key in this
+ * {@code Hashtable}.
*
* @param key
- * the key of the value returned
- * @return the value associated with the specified key, null if the
- * specified key does not exist
- *
+ * the key of the value returned.
+ * @return the value associated with the specified key, or {@code null} if
+ * the specified key does not exist.
* @see #put
*/
@Override
@@ -535,14 +535,6 @@
return null;
}
- /**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public synchronized int hashCode() {
int result = 0;
@@ -560,10 +552,10 @@
}
/**
- * Answers if this Hashtable has no key/value pairs, a size of zero.
- *
- * @return true if this Hashtable has no key/value pairs, false otherwise
+ * Returns true if this {@code Hashtable} has no key/value pairs.
*
+ * @return {@code true} if this {@code Hashtable} has no key/value pairs,
+ * {@code false} otherwise.
* @see #size
*/
@Override
@@ -572,12 +564,11 @@
}
/**
- * Answers an Enumeration on the keys of this Hashtable. The results of the
- * Enumeration may be affected if the contents of this Hashtable are
- * modified.
- *
- * @return an Enumeration of the keys of this Hashtable
+ * Returns an enumeration on the keys of this {@code Hashtable} instance.
+ * The results of the enumeration may be affected if the contents of this
+ * {@code Hashtable} are modified.
*
+ * @return an enumeration of the keys of this {@code Hashtable}.
* @see #elements
* @see #size
* @see Enumeration
@@ -596,11 +587,11 @@
}
/**
- * Answers a Set of the keys contained in this Hashtable. The set is backed
- * by this Hashtable so changes to one are reflected by the other. The set
- * does not support adding.
+ * Returns a set of the keys contained in this {@code Hashtable}. The set
+ * is backed by this {@code Hashtable} so changes to one are reflected by
+ * the other. The set does not support adding.
*
- * @return a Set of the keys
+ * @return a set of the keys.
*/
public Set<K> keySet() {
return new Collections.SynchronizedSet<K>(new AbstractSet<K>() {
@@ -721,17 +712,16 @@
}
/**
- * Associate the specified value with the specified key in this Hashtable.
- * If the key already exists, the old value is replaced. The key and value
- * cannot be null.
+ * Associate the specified value with the specified key in this
+ * {@code Hashtable}. If the key already exists, the old value is replaced.
+ * The key and value cannot be null.
*
* @param key
- * the key to add
+ * the key to add.
* @param value
- * the value to add
- * @return the old value associated with the specified key, null if the key
- * did not exist
- *
+ * the value to add.
+ * @return the old value associated with the specified key, or {@code null}
+ * if the key did not exist.
* @see #elements
* @see #get
* @see #keys
@@ -771,10 +761,10 @@
}
/**
- * Copies every mapping in the specified Map to this Hashtable.
+ * Copies every mapping to this {@code Hashtable} from the specified map.
*
* @param map
- * the Map to copy mappings from
+ * the map to copy mappings from.
*/
public synchronized void putAll(Map<? extends K, ? extends V> map) {
for (Map.Entry<? extends K, ? extends V> entry : map.entrySet()) {
@@ -783,8 +773,8 @@
}
/**
- * Increases the capacity of this Hashtable. This method is sent when the
- * size of this Hashtable exceeds the load factor.
+ * Increases the capacity of this {@code Hashtable}. This method is called
+ * when the size of this {@code Hashtable} exceeds the load factor.
*/
protected void rehash() {
int length = (elementData.length << 1) + 1;
@@ -817,13 +807,13 @@
}
/**
- * Remove the key/value pair with the specified key from this Hashtable.
+ * Removes the key/value pair with the specified key from this
+ * {@code Hashtable}.
*
* @param key
- * the key to remove
- * @return the value associated with the specified key, null if the
- * specified key did not exist
- *
+ * the key to remove.
+ * @return the value associated with the specified key, or {@code null} if
+ * the specified key did not exist.
* @see #get
* @see #put
*/
@@ -853,10 +843,9 @@
}
/**
- * Answers the number of key/value pairs in this Hashtable.
- *
- * @return the number of key/value pairs in this Hashtable
+ * Returns the number of key/value pairs in this {@code Hashtable}.
*
+ * @return the number of key/value pairs in this {@code Hashtable}.
* @see #elements
* @see #keys
*/
@@ -866,9 +855,9 @@
}
/**
- * Answers the string representation of this Hashtable.
+ * Returns the string representation of this {@code Hashtable}.
*
- * @return the string representation of this Hashtable
+ * @return the string representation of this {@code Hashtable}.
*/
@Override
public synchronized String toString() {
@@ -907,11 +896,11 @@
}
/**
- * Answers a Collection of the values contained in this Hashtable. The
- * collection is backed by this Hashtable so changes to one are reflected by
- * the other. The collection does not support adding.
+ * Returns a collection of the values contained in this {@code Hashtable}.
+ * The collection is backed by this {@code Hashtable} so changes to one are
+ * reflected by the other. The collection does not support adding.
*
- * @return a Collection of the values
+ * @return a collection of the values.
*/
public Collection<V> values() {
return new Collections.SynchronizedCollection<V>(
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IdentityHashMap.java Thu May 7 21:43:41 2009
@@ -23,15 +23,17 @@
import java.io.Serializable;
/**
- * IdentityHashMap
- *
- * This is a variant on HashMap which tests equality by reference instead of by
- * value. Basically, keys and values are compared for equality by checking if
- * their references are equal rather than by calling the "equals" function.
- *
+ * IdentityHashMap is a variant on HashMap which tests equality by reference
+ * instead of equality by value. Basically, keys and values are compared for
+ * equality by checking if their references are equal rather than by calling the
+ * "equals" function.
+ * <p>
+ * <b>Note: This class intentionally violates the general contract of {@code
+ * Map}'s on comparing objects by their {@code equals} method.</b>
+ * <p>
* IdentityHashMap uses open addressing (linear probing in particular) for
* collision resolution. This is different from HashMap which uses Chaining.
- *
+ * <p>
* Like HashMap, IdentityHashMap is not thread safe, so access by multiple
* threads must be synchronized by an external mechanism such as
* Collections.synchronizedMap.
@@ -235,14 +237,14 @@
}
/**
- * Create an IdentityHashMap with default maximum size
+ * Creates an IdentityHashMap with default expected maximum size.
*/
public IdentityHashMap() {
this(DEFAULT_MAX_SIZE);
}
/**
- * Create an IdentityHashMap with the given maximum size parameter
+ * Creates an IdentityHashMap with the specified maximum size parameter.
*
* @param maxSize
* The estimated maximum number of entries that will be put in
@@ -280,10 +282,10 @@
}
/**
- * Create an IdentityHashMap using the given Map as initial values.
+ * Creates an IdentityHashMap using the given map as initial values.
*
* @param map
- * A map of (key,value) pairs to copy into the IdentityHashMap
+ * A map of (key,value) pairs to copy into the IdentityHashMap.
*/
public IdentityHashMap(Map<? extends K, ? extends V> map) {
this(map.size() < 6 ? 11 : map.size() * 2);
@@ -296,13 +298,10 @@
}
/**
- * Removes all elements from this Map, leaving it empty.
- *
- * @exception UnsupportedOperationException
- * when removing from this Map is not supported
+ * Removes all elements from this map, leaving it empty.
*
- * @see #isEmpty
- * @see #size
+ * @see #isEmpty()
+ * @see #size()
*/
@Override
public void clear() {
@@ -314,11 +313,12 @@
}
/**
- * Searches this Map for the specified key.
+ * Returns whether this map contains the specified key.
*
* @param key
- * the object to search for
- * @return true if <code>key</code> is a key of this Map, false otherwise
+ * the key to search for.
+ * @return {@code true} if this map contains the specified key,
+ * {@code false} otherwise.
*/
@Override
public boolean containsKey(Object key) {
@@ -331,13 +331,12 @@
}
/**
- * Searches this Map for the specified value.
- *
+ * Returns whether this map contains the specified value.
*
* @param value
- * the object to search for
- * @return true if <code>value</code> is a value of this Map, false
- * otherwise
+ * the value to search for.
+ * @return {@code true} if this map contains the specified value,
+ * {@code false} otherwise.
*/
@Override
public boolean containsValue(Object value) {
@@ -354,11 +353,11 @@
}
/**
- * Answers the value of the mapping with the specified key.
+ * Returns the value of the mapping with the specified key.
*
* @param key
- * the key
- * @return the value of the mapping with the specified key
+ * the key.
+ * @return the value of the mapping with the specified key.
*/
@Override
public V get(Object key) {
@@ -437,11 +436,11 @@
* Maps the specified key to the specified value.
*
* @param key
- * the key
+ * the key.
* @param value
- * the value
- * @return the value of any previous mapping with the specified key or null
- * if there was no mapping
+ * the value.
+ * @return the value of any previous mapping with the specified key or
+ * {@code null} if there was no such mapping.
*/
@Override
public V put(K key, V value) {
@@ -478,14 +477,14 @@
}
/**
- * Copies all the mappings in the given map to this map. These mappings will
- * replace all mappings that this map had for any of the keys currently in
- * the given map.
+ * Copies all the mappings in the specified map to this map. These mappings
+ * will replace all mappings that this map had for any of the keys currently
+ * in the given map.
*
* @param map
- * the Map to copy mappings from
+ * the map to copy mappings from.
* @throws NullPointerException
- * if the given map is null
+ * if {@code map} is {@code null}.
*/
@Override
public void putAll(Map<? extends K, ? extends V> map) {
@@ -516,12 +515,12 @@
}
/**
- * Removes a mapping with the specified key from this IdentityHashMap.
+ * Removes the mapping with the specified key from this map.
*
* @param key
- * the key of the mapping to remove
- * @return the value of the removed mapping, or null if key is not a key in
- * this Map
+ * the key of the mapping to remove.
+ * @return the value of the removed mapping, or {@code null} if no mapping
+ * for the specified key was found.
*/
@Override
public V remove(Object key) {
@@ -576,12 +575,11 @@
}
/**
- * Answers a Set of the mappings contained in this IdentityHashMap. Each
- * element in the set is a Map.Entry. The set is backed by this Map so
- * changes to one are reflected by the other. The set does not support
- * adding.
+ * Returns a set containing all of the mappings in this map. Each mapping is
+ * an instance of {@link Map.Entry}. As the set is backed by this map,
+ * changes in one will be reflected in the other.
*
- * @return a Set of the mappings
+ * @return a set of the mappings.
*/
@Override
public Set<Map.Entry<K, V>> entrySet() {
@@ -589,11 +587,11 @@
}
/**
- * Answers a Set of the keys contained in this IdentityHashMap. The set is
- * backed by this IdentityHashMap so changes to one are reflected by the
- * other. The set does not support adding.
+ * Returns a set of the keys contained in this map. The set is backed by
+ * this map so changes to one are reflected by the other. The set does not
+ * support adding.
*
- * @return a Set of the keys
+ * @return a set of the keys.
*/
@Override
public Set<K> keySet() {
@@ -638,11 +636,23 @@
}
/**
- * Answers a Collection of the values contained in this IdentityHashMap. The
- * collection is backed by this IdentityHashMap so changes to one are
- * reflected by the other. The collection does not support adding.
+ * Returns a collection of the values contained in this map. The collection
+ * is backed by this map so changes to one are reflected by the other. The
+ * collection supports remove, removeAll, retainAll and clear operations,
+ * and it does not support add or addAll operations.
+ * <p>
+ * This method returns a collection which is the subclass of
+ * AbstractCollection. The iterator method of this subclass returns a
+ * "wrapper object" over the iterator of map's entrySet(). The {@code size}
+ * method wraps the map's size method and the {@code contains} method wraps
+ * the map's containsValue method.
+ * <p>
+ * The collection is created when this method is called for the first time
+ * and returned in response to all subsequent calls. This method may return
+ * different collections when multiple concurrent calls occur, since no
+ * synchronization is performed.
*
- * @return a Collection of the values
+ * @return a collection of the values contained in this map.
*/
@Override
public Collection<V> values() {
@@ -692,13 +702,14 @@
/**
* Compares this map with other objects. This map is equal to another map is
* it represents the same set of mappings. With this map, two mappings are
- * the same if both the key and the value are equal by reference.
- *
- * When compared with a map that is not an IdentityHashMap, the equals
- * method is not necessarily symmetric (a.equals(b) implies b.equals(a)) nor
+ * the same if both the key and the value are equal by reference. When
+ * compared with a map that is not an IdentityHashMap, the equals method is
+ * neither necessarily symmetric (a.equals(b) implies b.equals(a)) nor
* transitive (a.equals(b) and b.equals(c) implies a.equals(c)).
*
- * @return whether the argument object is equal to this object
+ * @param object
+ * the object to compare to.
+ * @return whether the argument object is equal to this object.
*/
@Override
public boolean equals(Object object) {
@@ -728,11 +739,10 @@
}
/**
- * Answers a new IdentityHashMap with the same mappings and size as this
+ * Returns a new IdentityHashMap with the same mappings and size as this
* one.
*
- * @return a shallow copy of this IdentityHashMap
- *
+ * @return a shallow copy of this IdentityHashMap.
* @see java.lang.Cloneable
*/
@Override
@@ -745,11 +755,11 @@
}
/**
- * Answers if this IdentityHashMap has no elements, a size of zero.
- *
- * @return true if this IdentityHashMap has no elements, false otherwise
+ * Returns whether this IdentityHashMap has no elements.
*
- * @see #size
+ * @return {@code true} if this IdentityHashMap has no elements,
+ * {@code false} otherwise.
+ * @see #size()
*/
@Override
public boolean isEmpty() {
@@ -757,9 +767,9 @@
}
/**
- * Answers the number of mappings in this IdentityHashMap.
+ * Returns the number of mappings in this IdentityHashMap.
*
- * @return the number of mappings in this IdentityHashMap
+ * @return the number of mappings in this IdentityHashMap.
*/
@Override
public int size() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatCodePointException.java Thu May 7 21:43:41 2009
@@ -19,41 +19,42 @@
import java.io.Serializable;
/**
- * The unchecked exception will be thrown out if an invalid Unicode code point,
- * which is Character.isValidCodePoint(int), is passed as a parameter to
- * Formatter.
+ * An {@code IllegalFormatCodePointException} will be thrown if an invalid
+ * Unicode code point (defined by {@link Character#isValidCodePoint(int)}) is
+ * passed as a parameter to a Formatter.
+ *
+ * @see java.lang.RuntimeException
*/
public class IllegalFormatCodePointException extends IllegalFormatException
implements Serializable {
-
private static final long serialVersionUID = 19080630L;
private int c;
/**
- * Constructs an IllegalFormatCodePointException which is specified by the
- * invalid Unicode code point.
+ * Constructs a new {@code IllegalFormatCodePointException} which is
+ * specified by the invalid Unicode code point.
*
* @param c
- * The invalid Unicode code point.
+ * the invalid Unicode code point.
*/
public IllegalFormatCodePointException(int c) {
this.c = c;
}
/**
- * Return the invalid Unicode code point.
+ * Returns the invalid Unicode code point.
*
- * @return The invalid Unicode code point.
+ * @return the invalid Unicode code point.
*/
public int getCodePoint() {
return c;
}
/**
- * Return the message string of the IllegalFormatCodePointException.
+ * Returns the message string of the IllegalFormatCodePointException.
*
- * @return The message string of the IllegalFormatCodePointException.
+ * @return the message string of the IllegalFormatCodePointException.
*/
@Override
public String getMessage() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatConversionException.java Thu May 7 21:43:41 2009
@@ -19,14 +19,15 @@
import java.io.Serializable;
/**
- * The unchecked exception will be thrown out when the parameter is incompatible
- * with the corresponding format specifier.
+ * An {@code IllegalFormatConversionException} will be thrown when the parameter
+ * is incompatible with the corresponding format specifier.
*
+ * @see java.lang.RuntimeException
+ *
* @since 1.5
*/
public class IllegalFormatConversionException extends IllegalFormatException
implements Serializable {
-
private static final long serialVersionUID = 17000126L;
private char c;
@@ -34,13 +35,13 @@
private Class<?> arg;
/**
- * Constructs an IllegalFormatConversionException with the class of the
- * mismatched conversion and corresponding parameter.
+ * Constructs a new {@code IllegalFormatConversionException} with the class
+ * of the mismatched conversion and corresponding parameter.
*
* @param c
- * The class of the mismatched conversion.
+ * the class of the mismatched conversion.
* @param arg
- * The corresponding parameter.
+ * the corresponding parameter.
*/
public IllegalFormatConversionException(char c, Class<?> arg) {
this.c = c;
@@ -51,27 +52,27 @@
}
/**
- * Return the class of the mismatched parameter.
+ * Returns the class of the mismatched parameter.
*
- * @return The class of the mismatched parameter.
+ * @return the class of the mismatched parameter.
*/
public Class<?> getArgumentClass() {
return arg;
}
/**
- * Return the incompatible conversion.
+ * Returns the incompatible conversion.
*
- * @return The incompatible conversion.
+ * @return the incompatible conversion.
*/
public char getConversion() {
return c;
}
/**
- * Return the message string of the IllegalFormatConversionException.
+ * Returns the message string of the IllegalFormatConversionException.
*
- * @return The message string of the IllegalFormatConversionException.
+ * @return the message string of the IllegalFormatConversionException.
*/
@Override
public String getMessage() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatException.java Thu May 7 21:43:41 2009
@@ -18,10 +18,12 @@
import java.io.Serializable;
/**
- * Unchecked Exception that is to be thrown out when a format string that
+ * An {@code IllegalFormatException} is thrown when a format string that
* contains either an illegal syntax or format specifier is transferred as a
- * parameter. Only a subclass that is inherited explicitly from this exception
- * is allowed to be instantiated.
+ * parameter. Only subclasses inheriting explicitly from this exception are
+ * allowed to be instantiated.
+ *
+ * @see java.lang.RuntimeException
*/
public class IllegalFormatException extends IllegalArgumentException implements
Serializable {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatFlagsException.java Thu May 7 21:43:41 2009
@@ -19,21 +19,23 @@
import java.io.Serializable;
/**
- * The unchecked exception will be thrown out if the combination of the format
- * flags is illegal.
+ * An {@code IllegalFormatFlagsException} will be thrown if the combination of
+ * the format flags is illegal.
+ *
+ * @see java.lang.RuntimeException
*/
public class IllegalFormatFlagsException extends IllegalFormatException
implements Serializable {
-
private static final long serialVersionUID = 790824L;
private String flags;
/**
- * Constructs an IllegalFormatFlagsException with the specified flags.
+ * Constructs a new {@code IllegalFormatFlagsException} with the specified
+ * flags.
*
* @param f
- * The specified flags.
+ * the specified flags.
*/
public IllegalFormatFlagsException(String f) {
if (null == f) {
@@ -43,18 +45,18 @@
}
/**
- * Return the flags that are illegal.
+ * Returns the flags that are illegal.
*
- * @return The flags that are illegal.
+ * @return the flags that are illegal.
*/
public String getFlags() {
return flags;
}
/**
- * Return the message string of the IllegalFormatFlagsException.
+ * Returns the message string of the IllegalFormatFlagsException.
*
- * @return The message string of the IllegalFormatFlagsException.
+ * @return the message string of the IllegalFormatFlagsException.
*/
@Override
public String getMessage() {
@@ -64,4 +66,5 @@
buffer.append("'");
return buffer.toString();
}
+
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatPrecisionException.java Thu May 7 21:43:41 2009
@@ -17,21 +17,23 @@
package java.util;
/**
- * The unchecked exception will be thrown out when the precision is a negative
- * other than -1, or the conversion does not support a precision or other cases
- * when the precision is not supported.
+ * An {@code IllegalFormatPrecisionException} will be thrown if the precision is
+ * a negative other than -1 or in other cases where precision is not supported.
+ *
+ * @see java.lang.RuntimeException
*/
-public class IllegalFormatPrecisionException extends IllegalFormatException {
+public class IllegalFormatPrecisionException extends IllegalFormatException {
private static final long serialVersionUID = 18711008L;
private int p;
/**
- * Constructs a IllegalFormatPrecisionException with specified precision.
+ * Constructs a new {@code IllegalFormatPrecisionException} with specified
+ * precision.
*
* @param p
- * The precision.
+ * the precision.
*/
public IllegalFormatPrecisionException(int p) {
this.p = p;
@@ -49,7 +51,7 @@
/**
* Returns the message of the exception.
*
- * @return The message of the exception.
+ * @return the message of the exception.
*/
@Override
public String getMessage() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/IllegalFormatWidthException.java Thu May 7 21:43:41 2009
@@ -17,9 +17,11 @@
package java.util;
/**
- * The unchecked exception will be thrown out when the width is a negative other
- * than -1, or the conversion does not support a width or other cases when the
- * width is not supported.
+ * An {@code IllegalFormatWidthException} will be thrown if the width is a
+ * negative value other than -1 or in other cases where a width is not
+ * supported.
+ *
+ * @see java.lang.RuntimeException
*/
public class IllegalFormatWidthException extends IllegalFormatException {
@@ -28,10 +30,11 @@
private int w;
/**
- * Constructs a IllegalFormatWidthException with specified width.
+ * Constructs a new {@code IllegalFormatWidthException} with specified
+ * width.
*
* @param w
- * The width.
+ * the width.
*/
public IllegalFormatWidthException(int w) {
this.w = w;
@@ -49,7 +52,7 @@
/**
* Returns the message of the exception.
*
- * @return The message of the exception.
+ * @return the message of the exception.
*/
@Override
public String getMessage() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InputMismatchException.java Thu May 7 21:43:41 2009
@@ -18,10 +18,12 @@
import java.io.Serializable;
/**
- * An InputMismatchException is thrown by a scanner to indicate that the next
- * token does not match the pattern the specified type.
+ * An {@code InputMismatchException} is thrown by a scanner to indicate that the
+ * next token does not match or is out of range for the type specified in the
+ * pattern.
*
* @see Scanner
+ * @see java.lang.RuntimeException
*/
public class InputMismatchException extends NoSuchElementException implements
Serializable {
@@ -29,18 +31,19 @@
private static final long serialVersionUID = 8811230760997066428L;
/**
- * Constructs a InputMismatchException with no error message
- *
+ * Constructs a new {@code InputMismatchException} with the current stack
+ * trace filled in.
*/
public InputMismatchException() {
super();
}
/**
- * Constructs a InputMismatchException with msg as its error message
+ * Constructs a new {@code InputMismatchException} with the stack trace
+ * filled in and {@code msg} as its error message.
*
* @param msg
- * The specified error message
+ * the specified error message.
*/
public InputMismatchException(String msg) {
super(msg);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/InvalidPropertiesFormatException.java Thu May 7 21:43:41 2009
@@ -22,14 +22,37 @@
import java.io.ObjectOutputStream;
import java.io.IOException;
+/**
+ * An {@code InvalidPropertiesFormatException} is thrown if loading the XML
+ * document defining the properties does not follow the {@code Properties}
+ * specification.
+ *
+ * Even though this Exception inherits the {@code Serializable} interface, it is not
+ * serializable. The methods used for serialization throw
+ * {@code NotSerializableException}s.
+ */
public class InvalidPropertiesFormatException extends IOException {
private static final long serialVersionUID = 7763056076009360219L;
-
+
+ /**
+ * Constructs a new {@code InvalidPropertiesFormatException} with the
+ * current stack trace and message filled in.
+ *
+ * @param m
+ * the detail message for the exception.
+ */
public InvalidPropertiesFormatException(String m) {
super(m);
}
+ /**
+ * Constructs a new {@code InvalidPropertiesFormatException} with the cause
+ * for the Exception.
+ *
+ * @param c
+ * the cause for the Exception.
+ */
public InvalidPropertiesFormatException(Throwable c) {
initCause(c);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Iterator.java Thu May 7 21:43:41 2009
@@ -17,42 +17,47 @@
package java.util;
+
/**
- * An Iterator is used to sequence over a collection of objects.
+ * An Iterator is used to sequence over a collection of objects. Conceptual, an
+ * iterator is always positioned between two elements of a collection. A fresh
+ * iterator is always positioned in front of the first element.
+ *
+ * If a collection has been changed since its creation, methods {@code next} and
+ * {@code hasNext()} may throw a {@code ConcurrentModificationException}.
+ * Iterators with this behavior are called fail-fast iterators.
*/
public interface Iterator<E> {
/**
- * Answers if there are more elements to iterate.
- *
- * @return true if there are more elements, false otherwise
+ * Returns whether there are more elements to iterate, i.e. whether the
+ * iterator is positioned in front of an element.
*
+ * @return {@code true} if there are more elements, {@code false} otherwise.
* @see #next
*/
public boolean hasNext();
/**
- * Answers the next object in the iteration.
- *
- * @return the next object
- *
- * @exception NoSuchElementException
- * when there are no more elements
+ * Returns the next object in the iteration, i.e. returns the element in
+ * front of the iterator and advances the iterator by one position.
*
+ * @return the next object.
+ * @throws NoSuchElementException
+ * if there are no more elements.
* @see #hasNext
*/
public E next();
/**
- * Removes the last object returned by <code>next</code> from the
- * collection.
+ * Removes the last object returned by {@code next} from the collection.
+ * This method can only be called once after {@code next} was called.
*
- * @exception UnsupportedOperationException
- * when removing is not supported by the collection being
- * iterated
- * @exception IllegalStateException
- * when <code>next</code> has not been called, or
- * <code>remove</code> has already been called after the
- * last call to <code>next</code>
+ * @throws UnsupportedOperationException
+ * if removing is not supported by the collection being
+ * iterated.
+ * @throws IllegalStateException
+ * if {@code next} has not been called, or {@code remove} has
+ * already been called after the last call to {@code next}.
*/
public void remove();
}