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 [11/12] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimerTask.java Thu May 7 21:43:41 2009
@@ -18,7 +18,7 @@
package java.util;
/**
- * The TimerTask class is represents a task to run at specified time. The task
+ * The {@code TimerTask} class represents a task to run at a specified time. The task
* may be run once or repeatedly.
*
* @see Timer
@@ -65,7 +65,7 @@
/*
* Is TimerTask scheduled into any timer?
*
- * @return <code>true</code> if the timer task is scheduled, <code>false</code>
+ * @return {@code true} if the timer task is scheduled, {@code false}
* otherwise.
*/
boolean isScheduled() {
@@ -74,17 +74,20 @@
}
}
+ /**
+ * Creates a new {@code TimerTask}.
+ */
protected TimerTask() {
super();
}
/**
- * Cancels the Task and removes it from the Timer's queue. Generally, it
- * returns false if the call did not prevent a TimerTask from running at
+ * Cancels the {@code TimerTask} and removes it from the {@code Timer}'s queue. Generally, it
+ * returns {@code false} if the call did not prevent a {@code TimerTask} from running at
* least once. Subsequent calls have no effect.
*
- * @return <code>true</code> if the call prevented a scheduled execution
- * from taking place, <code>false</code> otherwise.
+ * @return {@code true} if the call prevented a scheduled execution
+ * from taking place, {@code false} otherwise.
*/
public boolean cancel() {
synchronized (lock) {
@@ -96,8 +99,8 @@
/**
* Returns the scheduled execution time. If the task execution is in
- * progress returns the execution time of ongoing task. Tasks which have not
- * yet run return an undefined value.
+ * progress it returns the execution time of the ongoing task. Tasks which
+ * have not yet run return an undefined value.
*
* @return the most recent execution time.
*/
@@ -108,7 +111,7 @@
}
/**
- * The task to run should be specified in the implementation of the run()
+ * The task to run should be specified in the implementation of the {@code run()}
* method.
*/
public abstract void run();
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TooManyListenersException.java Thu May 7 21:43:41 2009
@@ -17,32 +17,33 @@
package java.util;
+
/**
- * This exception is thrown when an attempt is made to add more than one
- * listener to an event source which only supports a single listener. It is also
- * thrown when the same listener is added more than once.
- *
- * @see java.lang.Exception
+ * A {@code TooManyListenersException} is thrown when an attempt is made to add
+ * more than one listener to an event source which only supports a single
+ * listener. It is also thrown when the same listener is added more than once.
*/
public class TooManyListenersException extends Exception {
private static final long serialVersionUID = 5074640544770687831L;
/**
- * Constructs a new instance of this class with its walkback filled in.
+ * Constructs a new {@code TooManyListenersException} with the current stack
+ * trace filled in.
*/
public TooManyListenersException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code TooManyListenersException} with the stack trace
+ * and message filled in.
*
* @param detailMessage
- * String The detail message for the exception.
+ * the detail message for the exception.
*/
public TooManyListenersException(String detailMessage) {
super(detailMessage);
}
+
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeMap.java Thu May 7 21:43:41 2009
@@ -23,9 +23,9 @@
import java.io.Serializable;
/**
- * TreeMap is an implementation of SortedMap. All optional operations are
- * supported, adding and removing. The values can be any objects. The keys can
- * be any objects which are comparable to each other either using their natural
+ * TreeMap is an implementation of SortedMap. All optional operations (adding
+ * and removing) are supported. The values can be any objects. The keys can be
+ * any objects which are comparable to each other either using their natural
* order or a specified Comparator.
*
* @since 1.2
@@ -958,38 +958,43 @@
}
/**
- * Constructs a new empty instance of spec.TreeMap.
+ * Constructs a new empty {@code TreeMap} instance.
*/
public TreeMap() {
}
/**
- * Constructs a new empty instance of spec.TreeMap which uses the specified
- * Comparator.
+ * Constructs a new empty {@code TreeMap} instance with the specified
+ * comparator.
*
- * @param comparator the Comparator
+ * @param comparator
+ * the comparator to compare keys with.
*/
public TreeMap(Comparator<? super K> comparator) {
this.comparator = comparator;
}
/**
- * Constructs a new instance of spec.TreeMap containing the mappings from the
- * specified Map and using the natural ordering.
+ * Constructs a new {@code TreeMap} instance containing the mappings from
+ * the specified map and using natural ordering.
*
- * @param map the mappings to add
- * @throws ClassCastException when a key in the Map does not implement the Comparable
- * interface, or they keys in the Map cannot be compared
+ * @param map
+ * the mappings to add.
+ * @throws ClassCastException
+ * if a key in the specified map does not implement the
+ * Comparable interface, or if the keys in the map cannot be
+ * compared.
*/
public TreeMap(Map<? extends K, ? extends V> map) {
putAll(map);
}
/**
- * Constructs a new instance of spec.TreeMap containing the mappings from the
- * specified SortedMap and using the same Comparator.
+ * Constructs a new {@code TreeMap} instance containing the mappings from
+ * the specified SortedMap and using the same comparator.
*
- * @param map the mappings to add
+ * @param map
+ * the mappings to add.
*/
public TreeMap(SortedMap<K, ? extends V> map) {
this(map.comparator());
@@ -1019,10 +1024,10 @@
}
/**
- * Removes all mappings from this spec.TreeMap, leaving it empty.
+ * Removes all mappings from this TreeMap, leaving it empty.
*
- * @see Map#isEmpty
- * @see #size
+ * @see Map#isEmpty()
+ * @see #size()
*/
@Override
public void clear() {
@@ -1032,10 +1037,10 @@
}
/**
- * Answers a new spec.TreeMap with the same mappings, size and comparator as this
- * spec.TreeMap.
+ * Returns a new {@code TreeMap} with the same mappings, size and comparator
+ * as this instance.
*
- * @return a shallow copy of this spec.TreeMap
+ * @return a shallow copy of this instance.
* @see java.lang.Cloneable
*/
@SuppressWarnings("unchecked")
@@ -1077,23 +1082,27 @@
}
/**
- * Answers the Comparator used to compare elements in this spec.TreeMap.
+ * Returns the comparator used to compare elements in this map.
*
- * @return a Comparator or null if the natural ordering is used
+ * @return the comparator or {@code null} if the natural ordering is used.
*/
public Comparator<? super K> comparator() {
return comparator;
}
/**
- * Searches this spec.TreeMap 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 spec.TreeMap, false
- * otherwise
- * @throws ClassCastException when the key cannot be compared with the keys in this
- * spec.TreeMap
- * @throws NullPointerException when the key is null and the comparator cannot handle null
+ * @param key
+ * the key to search for.
+ * @return {@code true} if this map contains the specified key,
+ * {@code false} otherwise.
+ * @throws ClassCastException
+ * if the specified key cannot be compared with the keys in this
+ * map.
+ * @throws NullPointerException
+ * if the specified key is {@code null} and the comparator
+ * cannot handle {@code null} keys.
*/
@Override
public boolean containsKey(Object key) {
@@ -1138,11 +1147,12 @@
}
/**
- * Searches this spec.TreeMap 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 spec.TreeMap, false
- * otherwise
+ * @param value
+ * the value to search for.
+ * @return {@code true} if this map contains the specified value,
+ * {@code false} otherwise.
*/
@Override
public boolean containsValue(Object value) {
@@ -1177,11 +1187,12 @@
}
/**
- * Answers a Set of the mappings contained in this spec.TreeMap. Each element in
- * the set is a Map.Entry. The set is backed by this spec.TreeMap 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. It does not support adding
+ * operations.
*
- * @return a Set of the mappings
+ * @return a set of the mappings.
*/
@Override
public Set<Map.Entry<K, V>> entrySet() {
@@ -1230,10 +1241,11 @@
}
/**
- * Answers the first sorted key in this spec.TreeMap.
+ * Returns the first key in this map.
*
- * @return the first sorted key
- * @throws NoSuchElementException when this spec.TreeMap is empty
+ * @return the first key in this map.
+ * @throws NoSuchElementException
+ * if this map is empty.
*/
public K firstKey() {
if (root != null) {
@@ -1245,13 +1257,16 @@
/**
- * 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
- * @throws ClassCastException when the key cannot be compared with the keys in this
- * spec.TreeMap
- * @throws NullPointerException when the key is null and the comparator cannot handle null
+ * @param key
+ * the key.
+ * @return the value of the mapping with the specified key.
+ * @throws ClassCastException
+ * if the key cannot be compared with the keys in this map.
+ * @throws NullPointerException
+ * if the key is {@code null} and the comparator cannot handle
+ * {@code null}.
*/
@Override
public V get(Object key) {
@@ -1301,16 +1316,25 @@
}
/**
- * Answers a SortedMap of the specified portion of this spec.TreeMap which
- * contains keys less than the end key. The returned SortedMap is backed by
- * this spec.TreeMap so changes to one are reflected by the other.
- *
- * @param endKey the end key
- * @return a sub-map where the keys are less than <code>endKey</code>
- * @throws ClassCastException when the end key cannot be compared with the keys in this
- * spec.TreeMap
- * @throws NullPointerException when the end key is null and the comparator cannot handle
- * null
+ * 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 high boundary of the range specified.
+ * @return a sorted map where the keys are less than {@code endKey}.
+ * @throws ClassCastException
+ * if the specified key cannot be compared with the keys in this
+ * map.
+ * @throws NullPointerException
+ * if the specified key is {@code null} and the comparator
+ * cannot handle {@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) {
// Check for errors
@@ -1323,11 +1347,11 @@
}
/**
- * Answers a Set of the keys contained in this spec.TreeMap. The set is backed by
- * this spec.TreeMap 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() {
@@ -1367,10 +1391,11 @@
}
/**
- * Answer the last sorted key in this spec.TreeMap.
+ * Returns the last key in this map.
*
- * @return the last sorted key
- * @throws NoSuchElementException when this spec.TreeMap is empty
+ * @return the last key in this map.
+ * @throws NoSuchElementException
+ * if this map is empty.
*/
public K lastKey() {
if (root != null) {
@@ -1403,13 +1428,18 @@
/**
* Maps the specified key to the specified value.
*
- * @param 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
- * @throws ClassCastException when the key cannot be compared with the keys in this
- * spec.TreeMap
- * @throws NullPointerException when the key is null and the comparator cannot handle null
+ * @param key
+ * the key.
+ * @param value
+ * the value.
+ * @return the value of any previous mapping with the specified key or
+ * {@code null} if there was no mapping.
+ * @throws ClassCastException
+ * if the specified key cannot be compared with the keys in this
+ * map.
+ * @throws NullPointerException
+ * if the specified key is {@code null} and the comparator
+ * cannot handle {@code null} keys.
*/
@Override
public V put(K key, V value) {
@@ -1776,13 +1806,18 @@
/**
- * Copies every mapping in the specified Map to this spec.TreeMap.
- *
- * @param map the Map to copy mappings from
- * @throws ClassCastException when a key in the Map cannot be compared with the keys in
- * this spec.TreeMap
- * @throws NullPointerException when a key in the Map is null and the comparator cannot
- * handle null
+ * 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.
+ *
+ * @param map
+ * the map to copy mappings from.
+ * @throws ClassCastException
+ * if a key in the specified map cannot be compared with the
+ * keys in this map.
+ * @throws NullPointerException
+ * if a key in the specified map is {@code null} and the
+ * comparator cannot handle {@code null} keys.
*/
@Override
public void putAll(Map<? extends K, ? extends V> map) {
@@ -1790,14 +1825,18 @@
}
/**
- * Removes a mapping with the specified key from this spec.TreeMap.
+ * 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 spec.TreeMap
- * @throws ClassCastException when the key cannot be compared with the keys in this
- * spec.TreeMap
- * @throws NullPointerException when the key is null and the comparator cannot handle null
+ * @param key
+ * 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.
+ * @throws ClassCastException
+ * if the specified key cannot be compared with the keys in this
+ * map.
+ * @throws NullPointerException
+ * if the specified key is {@code null} and the comparator
+ * cannot handle {@code null} keys.
*/
@Override
public V remove(Object key) {
@@ -2213,9 +2252,9 @@
/**
- * Answers the number of mappings in this spec.TreeMap.
+ * Returns the number of mappings in this map.
*
- * @return the number of mappings in this spec.TreeMap
+ * @return the number of mappings in this map.
*/
@Override
public int size() {
@@ -2223,19 +2262,29 @@
}
/**
- * Answers a SortedMap of the specified portion of this spec.TreeMap which
- * contains keys greater or equal to the start key but less than the end
- * key. The returned SortedMap is backed by this spec.TreeMap so changes to one
- * are reflected by the other.
- *
- * @param startKey the start key
- * @param endKey the end key
- * @return a sub-map where the keys are greater or equal to
- * <code>startKey</code> and less than <code>endKey</code>
- * @throws ClassCastException when the start or end key cannot be compared with the keys
- * in this spec.TreeMap
- * @throws NullPointerException when the start or end key is null and the comparator
- * cannot handle null
+ * 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 low boundary of the range (inclusive).
+ * @param endKey
+ * the high boundary of the range (exclusive),
+ * @return a sorted map with the key from the specified range.
+ * @throws ClassCastException
+ * if the start or end key cannot be compared with the keys in
+ * this map.
+ * @throws NullPointerException
+ * if the start or end key is {@code null} and the comparator
+ * cannot handle {@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) {
if (comparator == null) {
@@ -2251,17 +2300,26 @@
}
/**
- * Answers a SortedMap of the specified portion of this spec.TreeMap which
- * contains keys greater or equal to the start key. The returned SortedMap
- * is backed by this spec.TreeMap so changes to one are reflected by the other.
- *
- * @param startKey the start key
- * @return a sub-map where the keys are greater or equal to
- * <code>startKey</code>
- * @throws ClassCastException when the start key cannot be compared with the keys in
- * this spec.TreeMap
- * @throws NullPointerException when the start key is null and the comparator cannot
- * handle null
+ * 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 low boundary of the range specified.
+ * @return a sorted map where the keys are greater or equal to
+ * {@code startKey}.
+ * @throws ClassCastException
+ * if the specified key cannot be compared with the keys in this
+ * map.
+ * @throws NullPointerException
+ * if the specified key is {@code null} and the comparator
+ * cannot handle {@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) {
// Check for errors
@@ -2274,11 +2332,23 @@
}
/**
- * Answers a Collection of the values contained in this spec.TreeMap. The
- * collection is backed by this spec.TreeMap 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/TreeSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TreeSet.java Thu May 7 21:43:41 2009
@@ -23,8 +23,8 @@
import java.io.Serializable;
/**
- * TreeSet is an implementation of SortedSet. All optional operations are
- * supported, adding and removing. The elements can be any objects which are
+ * TreeSet is an implementation of SortedSet. All optional operations (adding
+ * and removing) are supported. The elements can be any objects which are
* comparable to each other either using their natural order or a specified
* Comparator.
*
@@ -42,24 +42,23 @@
}
/**
- * Constructs a new empty instance of TreeSet which uses natural ordering.
- *
+ * Constructs a new empty instance of {@code TreeSet} which uses natural
+ * ordering.
*/
public TreeSet() {
backingMap = new TreeMap<E, E>();
}
/**
- * Constructs a new instance of TreeSet which uses natural ordering and
- * containing the unique elements in the specified collection.
+ * Constructs a new instance of {@code TreeSet} which uses natural ordering
+ * and containing the unique elements in the specified collection.
*
* @param collection
- * the collection of elements to add
- *
- * @exception ClassCastException
- * when an element in the Collection does not implement the
- * Comparable interface, or the elements in the Collection
- * cannot be compared
+ * the collection of elements to add.
+ * @throws ClassCastException
+ * when an element in the collection does not implement the
+ * Comparable interface, or the elements in the collection
+ * cannot be compared.
*/
public TreeSet(Collection<? extends E> collection) {
this();
@@ -67,22 +66,22 @@
}
/**
- * Constructs a new empty instance of TreeSet which uses the specified
- * Comparator.
+ * Constructs a new empty instance of {@code TreeSet} which uses the
+ * specified comparator.
*
* @param comparator
- * the Comparator
+ * the comparator to use.
*/
public TreeSet(Comparator<? super E> comparator) {
backingMap = new TreeMap<E, E>(comparator);
}
/**
- * Constructs a new instance of TreeSet containing the elements in the
- * specified SortedSet and using the same Comparator.
+ * Constructs a new instance of {@code TreeSet} containing the elements of
+ * the specified SortedSet and using the same Comparator.
*
* @param set
- * the SortedSet of elements to add
+ * the SortedSet of elements to add.
*/
public TreeSet(SortedSet<E> set) {
this(set.comparator());
@@ -93,19 +92,18 @@
}
/**
- * Adds the specified object to this TreeSet.
+ * Adds the specified object to this {@code TreeSet}.
*
* @param object
- * the object to add
- * @return true when this TreeSet did not already contain the object, false
- * otherwise
- *
- * @exception ClassCastException
- * when the object cannot be compared with the elements in
- * this TreeSet
- * @exception NullPointerException
- * when the object is null and the comparator cannot handle
- * null
+ * the object to add.
+ * @return {@code true} when this {@code TreeSet} did not already contain
+ * the object, {@code false} otherwise.
+ * @throws ClassCastException
+ * when the object cannot be compared with the elements in this
+ * {@code TreeSet}.
+ * @throws NullPointerException
+ * when the object is null and the comparator cannot handle
+ * null.
*/
@Override
public boolean add(E object) {
@@ -113,18 +111,18 @@
}
/**
- * Adds the objects in the specified Collection to this TreeSet.
+ * Adds the objects in the specified collection to this {@code TreeSet}.
*
* @param collection
- * the Collection of objects
- * @return true if this TreeSet is modified, false otherwise
- *
- * @exception ClassCastException
- * when an object in the Collection cannot be compared with
- * the elements in this TreeSet
- * @exception NullPointerException
- * when an object in the Collection is null and the
- * comparator cannot handle null
+ * the collection of objects to add.
+ * @return {@code true} if this {@code TreeSet} was modified, {@code false}
+ * otherwise.
+ * @throws ClassCastException
+ * when an object in the collection cannot be compared with the
+ * elements in this {@code TreeSet}.
+ * @throws NullPointerException
+ * when an object in the collection is null and the comparator
+ * cannot handle null.
*/
@Override
public boolean addAll(Collection<? extends E> collection) {
@@ -132,7 +130,7 @@
}
/**
- * Removes all elements from this TreeSet, leaving it empty.
+ * Removes all elements from this {@code TreeSet}, leaving it empty.
*
* @see #isEmpty
* @see #size
@@ -143,11 +141,10 @@
}
/**
- * Answers a new TreeSet with the same elements, size and comparator as this
- * TreeSet.
- *
- * @return a shallow copy of this TreeSet
+ * Returns a new {@code TreeSet} with the same elements, size and comparator
+ * as this {@code TreeSet}.
*
+ * @return a shallow copy of this {@code TreeSet}.
* @see java.lang.Cloneable
*/
@SuppressWarnings("unchecked")
@@ -168,7 +165,7 @@
}
/**
- * Answers the Comparator used to compare elements in this TreeSet.
+ * Returns the comparator used to compare elements in this {@code TreeSet}.
*
* @return a Comparator or null if the natural ordering is used
*/
@@ -177,19 +174,18 @@
}
/**
- * Searches this TreeSet for the specified object.
+ * Searches this {@code TreeSet} for the specified object.
*
* @param object
- * the object to search for
- * @return true if <code>object</code> is an element of this TreeSet,
- * false otherwise
- *
- * @exception ClassCastException
- * when the object cannot be compared with the elements in
- * this TreeSet
- * @exception NullPointerException
- * when the object is null and the comparator cannot handle
- * null
+ * the object to search for.
+ * @return {@code true} if {@code object} is an element of this
+ * {@code TreeSet}, {@code false} otherwise.
+ * @throws ClassCastException
+ * when the object cannot be compared with the elements in this
+ * {@code TreeSet}.
+ * @throws NullPointerException
+ * when the object is null and the comparator cannot handle
+ * null.
*/
@Override
public boolean contains(Object object) {
@@ -197,32 +193,31 @@
}
/**
- * Answers the first element in this TreeSet.
- *
- * @return the first element
+ * Returns the first element in this {@code TreeSet}.
*
- * @exception NoSuchElementException
- * when this TreeSet is empty
+ * @return the first element.
+ * @throws NoSuchElementException
+ * when this {@code TreeSet} is empty.
*/
public E first() {
return backingMap.firstKey();
}
/**
- * Answers a SortedSet of the specified portion of this TreeSet which
- * contains elements less than the end element. The returned SortedSet is
- * backed by this TreeSet so changes to one are reflected by the other.
+ * Returns a SortedSet of the specified portion of this {@code TreeSet}
+ * which contains elements which are all less than the end element. The
+ * returned SortedSet is backed by this {@code TreeSet} so changes to one
+ * 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 end object cannot be compared with the elements
- * in this TreeSet
- * @exception NullPointerException
- * when the end object is null and the comparator cannot
- * handle null
+ * the end element.
+ * @return a subset where the elements are less than {@code end}
+ * @throws ClassCastException
+ * when the end object cannot be compared with the elements in
+ * this {@code TreeSet}.
+ * @throws NullPointerException
+ * when the end object is null and the comparator cannot handle
+ * null.
*/
@SuppressWarnings("unchecked")
public SortedSet<E> headSet(E end) {
@@ -237,10 +232,9 @@
}
/**
- * Answers if this TreeSet has no elements, a size of zero.
- *
- * @return true if this TreeSet has no elements, false otherwise
+ * Returns true if this {@code TreeSet} has no element, otherwise false.
*
+ * @return true if this {@code TreeSet} has no element.
* @see #size
*/
@Override
@@ -249,10 +243,9 @@
}
/**
- * Answers an Iterator on the elements of this TreeSet.
- *
- * @return an Iterator on the elements of this TreeSet
+ * Returns an Iterator on the elements of this {@code TreeSet}.
*
+ * @return an Iterator on the elements of this {@code TreeSet}.
* @see Iterator
*/
@Override
@@ -261,30 +254,30 @@
}
/**
- * Answers the last element in this TreeSet.
+ * Returns the last element in this {@code TreeSet}. The last element is
+ * the highest element.
*
- * @return the last element
- *
- * @exception NoSuchElementException
- * when this TreeSet is empty
+ * @return the last element.
+ * @throws NoSuchElementException
+ * when this {@code TreeSet} is empty.
*/
public E last() {
return backingMap.lastKey();
}
/**
- * Removes an occurrence of the specified object from this TreeSet.
+ * Removes an occurrence of the specified object from this {@code TreeSet}.
*
* @param object
- * the object to remove
- * @return true if this TreeSet is modified, false otherwise
- *
- * @exception ClassCastException
- * when the object cannot be compared with the elements in
- * this TreeSet
- * @exception NullPointerException
- * when the object is null and the comparator cannot handle
- * null
+ * the object to remove.
+ * @return {@code true} if this {@code TreeSet} was modified, {@code false}
+ * otherwise.
+ * @throws ClassCastException
+ * when the object cannot be compared with the elements in this
+ * {@code TreeSet}.
+ * @throws NullPointerException
+ * when the object is null and the comparator cannot handle
+ * null.
*/
@Override
public boolean remove(Object object) {
@@ -292,9 +285,9 @@
}
/**
- * Answers the number of elements in this TreeSet.
+ * Returns the number of elements in this {@code TreeSet}.
*
- * @return the number of elements in this TreeSet
+ * @return the number of elements in this {@code TreeSet}.
*/
@Override
public int size() {
@@ -302,24 +295,23 @@
}
/**
- * Answers a SortedSet of the specified portion of this TreeSet which
- * contains elements greater or equal to the start element but less than the
- * end element. The returned SortedSet is backed by this TreeSet so changes
- * to one are reflected by the other.
+ * Returns a SortedSet of the specified portion of this {@code TreeSet}
+ * which contains elements greater or equal to the start element but less
+ * than the end element. The returned SortedSet is backed by this
+ * {@code TreeSet} so changes to one 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 start or end object cannot be compared with the
- * elements in this TreeSet
- * @exception NullPointerException
- * when the start or end object is null and the comparator
- * cannot handle null
+ * the end element (exclusive).
+ * @return a subset where the elements are greater or equal to {@code start}
+ * and less than {@code end}
+ * @throws ClassCastException
+ * when the start or end object cannot be compared with the
+ * elements in this {@code TreeSet}.
+ * @throws NullPointerException
+ * when the start or end object is null and the comparator
+ * cannot handle null.
*/
@SuppressWarnings("unchecked")
public SortedSet<E> subSet(E start, E end) {
@@ -337,22 +329,20 @@
}
/**
- * Answers a SortedSet of the specified portion of this TreeSet which
- * contains elements greater or equal to the start element. The returned
- * SortedSet is backed by this TreeSet so changes to one are reflected by
- * the other.
+ * Returns a SortedSet of the specified portion of this {@code TreeSet}
+ * which contains elements greater or equal to the start element. The
+ * returned SortedSet is backed by this {@code TreeSet} so changes to one
+ * 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 start object cannot be compared with the elements
- * in this TreeSet
- * @exception NullPointerException
- * when the start object is null and the comparator cannot
- * handle null
+ * the start element.
+ * @return a subset where the elements are greater or equal to {@code start}
+ * @throws ClassCastException
+ * when the start object cannot be compared with the elements in
+ * this {@code TreeSet}.
+ * @throws NullPointerException
+ * when the start object is null and the comparator cannot
+ * handle null.
*/
@SuppressWarnings("unchecked")
public SortedSet<E> tailSet(E start) {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UUID.java Thu May 7 21:43:41 2009
@@ -27,20 +27,16 @@
import org.apache.harmony.luni.util.Msg;
/**
- * <p>
* UUID is an immutable representation of a 128-bit universally unique
* identifier (UUID).
- * </p>
* <p>
* There are multiple, variant layouts of UUIDs, but this class is based upon
* variant 2 of <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>, the
* Leach-Salz variant. This class can be used to model alternate variants, but
* most of the methods will be unsupported in those cases; see each method for
* details.
- * </p>
- *
+ *
* @since 1.5
- * @author Nathan Beyer (Harmony)
*/
public final class UUID implements Serializable, Comparable<UUID> {
@@ -61,8 +57,7 @@
/**
* <p>
* Constructs an instance with the specified bits.
- * </p>
- *
+ *
* @param mostSigBits
* The 64 most significant bits of the UUID.
* @param leastSigBits
@@ -78,8 +73,7 @@
/**
* <p>
* Sets up the transient fields of this instance based on the current values
- * of the <code>mostSigBits</code> and <code>leastSigBits</code> fields.
- * </p>
+ * of the {@code mostSigBits} and {@code leastSigBits} fields.
*/
private void init() {
// setup hash field
@@ -123,9 +117,8 @@
* <p>
* Generates a variant 2, version 4 (randomly generated number) UUID as per
* <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
- * @return A UUID instance.
+ *
+ * @return an UUID instance.
*/
public static UUID randomUUID() {
byte[] data;
@@ -162,9 +155,10 @@
* <p>
* Generates a variant 2, version 3 (name-based, MD5-hashed) UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
- * @return A UUID instance.
+ *
+ * @param name
+ * the name used as byte array to create an UUID.
+ * @return an UUID instance.
*/
public static UUID nameUUIDFromBytes(byte[] name) {
if (name == null) {
@@ -204,15 +198,14 @@
/**
* <p>
* Parses a UUID string with the format defined by {@link #toString()}.
- * </p>
- *
+ *
* @param uuid
- * The UUID string to parse.
- * @return A UUID instance.
+ * the UUID string to parse.
+ * @return an UUID instance.
* @throws NullPointerException
- * if <code>uuid</code> is <code>null</code>.
+ * if {@code uuid} is {@code null}.
* @throws IllegalArgumentException
- * if <code>uuid</code> is not formatted correctly.
+ * if {@code uuid} is not formatted correctly.
*/
public static UUID fromString(String uuid) {
if (uuid == null) {
@@ -254,9 +247,8 @@
/**
* <p>
* The 64 least significant bits of the UUID.
- * </p>
- *
- * @return A long value.
+ *
+ * @return the 64 least significant bits.
*/
public long getLeastSignificantBits() {
return leastSigBits;
@@ -265,9 +257,8 @@
/**
* <p>
* The 64 most significant bits of the UUID.
- * </p>
- *
- * @return A long value.
+ *
+ * @return the 64 most significant bits.
*/
public long getMostSignificantBits() {
return mostSigBits;
@@ -278,7 +269,6 @@
* The version of the variant 2 UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>. If the variant
* is not 2, then the version will be 0.
- * </p>
* <ul>
* <li>1 - Time-based UUID</li>
* <li>2 - DCE Security UUID</li>
@@ -287,7 +277,7 @@
* <li>5 - Name-based with SHA-1 hashing UUID</li>
* </ul>
*
- * @return An int value.
+ * @return an {@code int} value.
*/
public int version() {
return version;
@@ -297,7 +287,6 @@
* <p>
* The variant of the UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
* <ul>
* <li>0 - Reserved for NCS compatibility</li>
* <li>2 - RFC 4122/Leach-Salz</li>
@@ -305,7 +294,7 @@
* <li>7 - Reserved for future use</li>
* </ul>
*
- * @return An int value.
+ * @return an {@code int} value.
*/
public int variant() {
return variant;
@@ -315,9 +304,8 @@
* <p>
* The timestamp value of the version 1, variant 2 UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
- * @return A long value.
+ *
+ * @return a {@code long} value.
* @throws UnsupportedOperationException
* if {@link #version()} is not 1.
*/
@@ -332,9 +320,8 @@
* <p>
* The clock sequence value of the version 1, variant 2 UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
- * @return A long value.
+ *
+ * @return a {@code long} value.
* @throws UnsupportedOperationException
* if {@link #version()} is not 1.
*/
@@ -349,9 +336,8 @@
* <p>
* The node value of the version 1, variant 2 UUID as per <a
* href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
- * @return A long value.
+ *
+ * @return a {@code long} value.
* @throws UnsupportedOperationException
* if {@link #version()} is not 1.
*/
@@ -367,12 +353,11 @@
* Compares this UUID to the specified UUID. The natural ordering of UUIDs
* is based upon the value of the bits from most significant to least
* significant.
- * </p>
- *
+ *
* @param uuid
- * The UUID to compare to.
- * @return A value of -1, 0 or 1 if this UUID is less than, equal to or
- * greater than <code>uuid</code>.
+ * the UUID to compare to.
+ * @return a value of -1, 0 or 1 if this UUID is less than, equal to or
+ * greater than {@code uuid}.
*/
public int compareTo(UUID uuid) {
if (uuid == this) {
@@ -396,15 +381,14 @@
/**
* <p>
- * Compares this UUID to another object for equality. If <code>object</code>
- * is not <code>null</code>, a UUID instance and all bits are equals,
- * then <code>true</code> is returned.
- * </p>
- *
+ * Compares this UUID to another object for equality. If {@code object}
+ * is not {@code null}, is a UUID instance, and all bits are equal, then
+ * {@code true} is returned.
+ *
* @param object
- * The Object to compare to.
- * @return A <code>true</code> if this UUID is equal to
- * <code>object</code> or <code>false</code> if not.
+ * the {@code Object} to compare to.
+ * @return {@code true} if this UUID is equal to {@code object}
+ * or {@code false} if not.
*/
@Override
public boolean equals(Object object) {
@@ -430,9 +414,8 @@
* <p>
* Returns a hash value for this UUID that is consistent with the
* {@link #equals(Object)} method.
- * </p>
- *
- * @return An int value.
+ *
+ * @return an {@code int} value.
*/
@Override
public int hashCode() {
@@ -443,8 +426,7 @@
* <p>
* Returns a string representation of this UUID in the following format, as
* per <a href="http://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>.
- * </p>
- *
+ *
* <pre>
* UUID = time-low "-" time-mid "-"
* time-high-and-version "-"
@@ -463,7 +445,7 @@
* "A" / "B" / "C" / "D" / "E" / "F"
* </pre>
*
- * @return A String instance.
+ * @return a String instance.
*/
@Override
public String toString() {
@@ -494,14 +476,13 @@
/**
* <p>
* Resets the transient fields to match the behavior of the constructor.
- * </p>
*
* @param in
- * The InputStream to read from.
+ * the {@code InputStream} to read from.
* @throws IOException
- * if <code>in</code> throws it.
+ * if {@code in} throws it.
* @throws ClassNotFoundException
- * if <code>in</code> throws it.
+ * if {@code in} throws it.
*/
private void readObject(ObjectInputStream in) throws IOException,
ClassNotFoundException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatConversionException.java Thu May 7 21:43:41 2009
@@ -18,21 +18,22 @@
import org.apache.harmony.luni.util.Msg;
/**
- * The unchecked exception will be thrown out if the format conversion is
- * unknown.
+ * An {@code UnknownFormatConversionException} will be thrown if the format
+ * conversion is unknown.
+ *
+ * @see java.lang.RuntimeException
*/
public class UnknownFormatConversionException extends IllegalFormatException {
-
private static final long serialVersionUID = 19060418L;
private String s;
/**
- * Constructs an UnknownFormatConversionException with the unknown format
- * conversion.
+ * Constructs an {@code UnknownFormatConversionException} with the unknown
+ * format conversion.
*
- * @param s
- * The unknown format conversion
+ * @param s
+ * the unknown format conversion.
*/
public UnknownFormatConversionException(String s) {
this.s = s;
@@ -41,7 +42,7 @@
/**
* Returns the conversion associated with the exception.
*
- * @return The conversion associated with the exception.
+ * @return the conversion associated with the exception.
*/
public String getConversion() {
return s;
@@ -50,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/UnknownFormatFlagsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/UnknownFormatFlagsException.java Thu May 7 21:43:41 2009
@@ -19,7 +19,10 @@
import org.apache.harmony.luni.util.Msg;
/**
- * The unchecked exception will be thrown out if there is an unknown flag.
+ * An {@code UnknownFormatFlagsException} will be thrown if there is
+ * an unknown flag.
+ *
+ * @see java.lang.RuntimeException
*/
public class UnknownFormatFlagsException extends IllegalFormatException {
@@ -28,10 +31,11 @@
private String flags;
/**
- * Constructs an UnknownFormatFlagsException with the specified flags.
+ * Constructs a new {@code UnknownFormatFlagsException} with the specified
+ * flags.
*
* @param f
- * The specified flags.
+ * the specified flags.
*/
public UnknownFormatFlagsException(String f) {
if (null == f) {
@@ -43,7 +47,7 @@
/**
* Returns the flags associated with the exception.
*
- * @return The flags associated with the exception.
+ * @return the flags associated with the exception.
*/
public String getFlags() {
return flags;
@@ -52,7 +56,7 @@
/**
* Returns the message associated with the exception.
*
- * @return The message associated with the exception.
+ * @return the message associated with the exception.
*/
@Override
public String getMessage() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Vector.java Thu May 7 21:43:41 2009
@@ -23,18 +23,18 @@
import java.lang.reflect.Array;
/**
- * Vector is a variable size contiguous indexable array of Objects. The size of
- * the Vector is the number of Objects it contains. The capacity of the Vector
- * is the number of Objects it can hold.
+ * Vector is a variable size contiguous indexable array of objects. The size of
+ * the vector is the number of objects it contains. The capacity of the vector
+ * is the number of objects it can hold.
* <p>
- * Objects may be inserted at any position up to the size of the Vector,
- * increasing the size of the Vector. Objects at any position in the Vector may
- * be removed, shrinking the size of the Vector. Objects at any position in the
- * Vector may be replaced, which does not affect the Vector size.
+ * Objects may be inserted at any position up to the size of the vector, thus
+ * increasing the size of the vector. Objects at any position in the vector may
+ * be removed, thus shrinking the size of the Vector. Objects at any position in
+ * the Vector may be replaced, which does not affect the vector's size.
* <p>
- * The capacity of a Vector may be specified when the Vector is created. If the
- * capacity of the Vector is exceeded, the capacity is increased, doubling by
- * default.
+ * The capacity of a vector may be specified when the vector is created. If the
+ * capacity of the vector is exceeded, the capacity is increased (doubled by
+ * default).
*
* @see java.lang.StringBuffer
*/
@@ -55,37 +55,42 @@
/**
* How many elements should be added to the vector when it is detected that
- * it needs to grow to accommodate extra entries.
+ * it needs to grow to accommodate extra entries. If this value is zero or
+ * negative the size will be doubled if an increase is needed.
*/
protected int capacityIncrement;
private static final int DEFAULT_SIZE = 10;
/**
- * Constructs a new Vector using the default capacity.
+ * Constructs a new vector using the default capacity.
*/
public Vector() {
this(DEFAULT_SIZE, 0);
}
/**
- * Constructs a new Vector using the specified capacity.
+ * Constructs a new vector using the specified capacity.
*
* @param capacity
- * the initial capacity of the new vector
+ * the initial capacity of the new vector.
+ * @throws IllegalArgumentException
+ * if {@code capacity} is negative.
*/
public Vector(int capacity) {
this(capacity, 0);
}
/**
- * Constructs a new Vector using the specified capacity and capacity
+ * Constructs a new vector using the specified capacity and capacity
* increment.
*
* @param capacity
- * the initial capacity of the new Vector
+ * the initial capacity of the new vector.
* @param capacityIncrement
- * the amount to increase the capacity when this Vector is full
+ * the amount to increase the capacity when this vector is full.
+ * @throws IllegalArgumentException
+ * if {@code capacity} is negative.
*/
public Vector(int capacity, int capacityIncrement) {
if (capacity < 0) {
@@ -97,13 +102,12 @@
}
/**
- * Constructs a new instance of <code>Vector</code> containing the
- * elements in <code>collection</code>. The order of the elements in the
- * new <code>Vector</code> is dependent on the iteration order of the seed
- * collection.
+ * Constructs a new instance of {@code Vector} containing the elements in
+ * {@code collection}. The order of the elements in the new {@code Vector}
+ * is dependent on the iteration order of the seed collection.
*
* @param collection
- * the collection of elements to add
+ * the collection of elements to add.
*/
public Vector(Collection<? extends E> collection) {
this(collection.size(), 0);
@@ -119,19 +123,17 @@
}
/**
- * Adds the specified object into this Vector at the specified location. The
- * object is inserted before any previous element at the specified location.
- * If the location is equal to the size of this Vector, the object is added
- * at the end.
+ * Adds the specified object into this vector at the specified location. The
+ * object is inserted before any element with the same or a higher index
+ * increasing their index by 1. If the location is equal to the size of this
+ * vector, the object is added at the end.
*
* @param location
- * the index at which to insert the element
+ * the index at which to insert the element.
* @param object
- * the object to insert in this Vector
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || > size()</code>
- *
+ * the object to insert in this vector.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location > size()}.
* @see #addElement
* @see #size
*/
@@ -141,11 +143,11 @@
}
/**
- * Adds the specified object at the end of this Vector.
+ * Adds the specified object at the end of this vector.
*
* @param object
- * the object to add to the Vector
- * @return true
+ * the object to add to the vector.
+ * @return {@code true}
*/
@Override
public synchronized boolean add(E object) {
@@ -158,19 +160,19 @@
}
/**
- * Inserts the objects in the specified Collection at the specified location
- * in this Vector. The objects are inserted in the order in which they are
- * returned from the Collection iterator.
+ * Inserts the objects in the specified collection at the specified location
+ * in this vector. The objects are inserted in the order in which they are
+ * returned from the Collection iterator. The elements with an index equal
+ * or higher than {@code location} have their index increased by the size of
+ * the added collection.
*
* @param location
- * the location to insert the objects
+ * the location to insert the objects.
* @param collection
- * the Collection of objects
- * @return true if this Vector is modified, false otherwise
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0</code> or
- * <code>location > size()</code>
+ * the collection of objects.
+ * @return {@code true} if this vector is modified, {@code false} otherwise.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0} or {@code location > size()}.
*/
@Override
public synchronized boolean addAll(int location,
@@ -201,11 +203,11 @@
}
/**
- * Adds the objects in the specified Collection to the end of this Vector.
+ * Adds the objects in the specified collection to the end of this vector.
*
* @param collection
- * the Collection of objects
- * @return true if this Vector is modified, false otherwise
+ * the collection of objects.
+ * @return {@code true} if this vector is modified, {@code false} otherwise.
*/
@Override
public synchronized boolean addAll(Collection<? extends E> collection) {
@@ -213,10 +215,10 @@
}
/**
- * Adds the specified object at the end of this Vector.
+ * Adds the specified object at the end of this vector.
*
* @param object
- * the object to add to the Vector
+ * the object to add to the vector.
*/
public synchronized void addElement(E object) {
if (elementCount == elementData.length) {
@@ -227,10 +229,9 @@
}
/**
- * Answers the number of elements this Vector can hold without growing.
- *
- * @return the capacity of this Vector
+ * Returns the number of elements this vector can hold without growing.
*
+ * @return the capacity of this vector.
* @see #ensureCapacity
* @see #size
*/
@@ -239,7 +240,7 @@
}
/**
- * Removes all elements from this Vector, leaving it empty.
+ * Removes all elements from this vector, leaving it empty.
*
* @see #isEmpty
* @see #size
@@ -250,11 +251,10 @@
}
/**
- * Answers a new Vector with the same elements, size, capacity and capacity
- * increment as this Vector.
- *
- * @return a shallow copy of this Vector
+ * Returns a new vector with the same elements, size, capacity and capacity
+ * increment as this vector.
*
+ * @return a shallow copy of this vector.
* @see java.lang.Cloneable
*/
@Override
@@ -270,12 +270,12 @@
}
/**
- * Searches this Vector for the specified object.
+ * Searches this vector for the specified object.
*
* @param object
- * the object to look for in this Vector
- * @return true if object is an element of this Vector, false otherwise
- *
+ * the object to look for in this vector.
+ * @return {@code true} if object is an element of this vector,
+ * {@code false} otherwise.
* @see #indexOf(Object)
* @see #indexOf(Object, int)
* @see java.lang.Object#equals
@@ -286,12 +286,12 @@
}
/**
- * Searches this Vector for all objects in the specified Collection.
+ * Searches this vector for all objects in the specified collection.
*
* @param collection
- * the Collection of objects
- * @return true if all objects in the specified Collection are elements of
- * this Vector, false otherwise
+ * the collection of objects.
+ * @return {@code true} if all objects in the specified collection are
+ * elements of this vector, {@code false} otherwise.
*/
@Override
public synchronized boolean containsAll(Collection<?> collection) {
@@ -299,13 +299,14 @@
}
/**
- * Attempts to copy elements contained by this <code>Vector</code> into
- * the corresponding elements of the supplied <code>Object</code> array.
+ * Attempts to copy elements contained by this {@code Vector} into the
+ * corresponding elements of the supplied {@code Object} array.
*
* @param elements
- * the <code>Object</code> array into which the elements of
- * this Vector are copied
- *
+ * the {@code Object} array into which the elements of this
+ * vector are copied.
+ * @throws IndexOutOfBoundsException
+ * if {@code elements} is not big enough.
* @see #clone
*/
public synchronized void copyInto(Object[] elements) {
@@ -313,15 +314,13 @@
}
/**
- * Answers the element at the specified location in this Vector.
+ * Returns the element at the specified location in this vector.
*
* @param location
- * the index of the element to return in this Vector
- * @return the element at the specified location
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the index of the element to return in this vector.
+ * @return the element at the specified location.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
* @see #size
*/
@SuppressWarnings("unchecked")
@@ -333,11 +332,10 @@
}
/**
- * Answers an Enumeration on the elements of this Vector. The results of the
- * Enumeration may be affected if the contents of this Vector are modified.
- *
- * @return an Enumeration of the elements of this Vector
+ * Returns an enumeration on the elements of this vector. The results of the
+ * enumeration may be affected if the contents of this vector is modified.
*
+ * @return an enumeration of the elements of this vector.
* @see #elementAt
* @see Enumeration
*/
@@ -362,13 +360,12 @@
}
/**
- * Ensures that this Vector can hold the specified number of elements
+ * Ensures that this vector can hold the specified number of elements
* without growing.
*
* @param minimumCapacity
* the minimum number of elements that this vector will hold
- * before growing
- *
+ * before growing.
* @see #capacity
*/
public synchronized void ensureCapacity(int minimumCapacity) {
@@ -381,15 +378,14 @@
}
/**
- * Compares the specified object to this Vector and answer if they are
+ * Compares the specified object to this vector and returns if they are
* equal. The object must be a List which contains the same objects in the
* same order.
*
* @param object
* the object to compare with this object
- * @return true if the specified object is equal to this Vector, false
- * otherwise
- *
+ * @return {@code true} if the specified object is equal to this vector,
+ * {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -417,13 +413,11 @@
}
/**
- * Answers the first element in this Vector.
- *
- * @return the element at the first position
- *
- * @exception NoSuchElementException
- * when this vector is empty
+ * Returns the first element in this vector.
*
+ * @return the element at the first position.
+ * @throws NoSuchElementException
+ * if this vector is empty.
* @see #elementAt
* @see #lastElement
* @see #size
@@ -437,15 +431,13 @@
}
/**
- * Answers the element at the specified location in this Vector.
+ * Returns the element at the specified location in this vector.
*
* @param location
- * the index of the element to return in this Vector
- * @return the element at the specified location
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the index of the element to return in this vector.
+ * @return the element at the specified location.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
* @see #size
*/
@Override
@@ -500,11 +492,10 @@
}
/**
- * 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
@@ -518,15 +509,14 @@
}
/**
- * Searches in this Vector for the index of the specified object. The search
+ * Searches in this vector for the index of the specified object. The search
* for the object starts at the beginning and moves towards the end of this
- * Vector.
+ * vector.
*
* @param object
- * the object to find in this Vector
- * @return the index in this Vector of the specified element, -1 if the
- * element isn't found
- *
+ * the object to find in this vector.
+ * @return the index in this vector of the specified element, -1 if the
+ * element isn't found.
* @see #contains
* @see #lastIndexOf(Object)
* @see #lastIndexOf(Object, int)
@@ -537,20 +527,18 @@
}
/**
- * Searches in this Vector for the index of the specified object. The search
+ * Searches in this vector for the index of the specified object. The search
* for the object starts at the specified location and moves towards the end
- * of this Vector.
+ * of this vector.
*
* @param object
- * the object to find in this Vector
+ * the object to find in this vector.
* @param location
- * the index at which to start searching
- * @return the index in this Vector of the specified element, -1 if the
- * element isn't found
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0</code>
- *
+ * the index at which to start searching.
+ * @return the index in this vector of the specified element, -1 if the
+ * element isn't found.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0}.
* @see #contains
* @see #lastIndexOf(Object)
* @see #lastIndexOf(Object, int)
@@ -573,19 +561,18 @@
}
/**
- * Inserts the specified object into this Vector at the specified location.
+ * Inserts the specified object into this vector at the specified location.
* This object is inserted before any previous element at the specified
- * location. If the location is equal to the size of this Vector, the object
- * is added at the end.
+ * location. All elements with an index equal or greater than
+ * {@code location} have their index increased by 1. If the location is
+ * equal to the size of this vector, the object is added at the end.
*
* @param object
- * the object to insert in this Vector
+ * the object to insert in this vector.
* @param location
- * the index at which to insert the element
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || > size()</code>
- *
+ * the index at which to insert the element.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location > size()}.
* @see #addElement
* @see #size
*/
@@ -608,10 +595,10 @@
}
/**
- * Answers if this Vector has no elements, a size of zero.
- *
- * @return true if this Vector has no elements, false otherwise
+ * Returns if this vector has no elements, a size of zero.
*
+ * @return {@code true} if this vector has no elements, {@code false}
+ * otherwise.
* @see #size
*/
@Override
@@ -620,13 +607,11 @@
}
/**
- * Answers the last element in this Vector.
- *
- * @return the element at the last position
- *
- * @exception NoSuchElementException
- * when this vector is empty
+ * Returns the last element in this vector.
*
+ * @return the element at the last position.
+ * @throws NoSuchElementException
+ * if this vector is empty.
* @see #elementAt
* @see #firstElement
* @see #size
@@ -641,15 +626,14 @@
}
/**
- * Searches in this Vector for the index of the specified object. The search
+ * Searches in this vector for the index of the specified object. The search
* for the object starts at the end and moves towards the start of this
- * Vector.
+ * vector.
*
* @param object
- * the object to find in this Vector
- * @return the index in this Vector of the specified element, -1 if the
- * element isn't found
- *
+ * the object to find in this vector.
+ * @return the index in this vector of the specified element, -1 if the
+ * element isn't found.
* @see #contains
* @see #indexOf(Object)
* @see #indexOf(Object, int)
@@ -660,20 +644,18 @@
}
/**
- * Searches in this Vector for the index of the specified object. The search
+ * Searches in this vector for the index of the specified object. The search
* for the object starts at the specified location and moves towards the
- * start of this Vector.
+ * start of this vector.
*
* @param object
- * the object to find in this Vector
+ * the object to find in this vector.
* @param location
- * the index at which to start searching
- * @return the index in this Vector of the specified element, -1 if the
- * element isn't found
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location >= size()</code>
- *
+ * the index at which to start searching.
+ * @return the index in this vector of the specified element, -1 if the
+ * element isn't found.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location >= size()}.
* @see #contains
* @see #indexOf(Object)
* @see #indexOf(Object, int)
@@ -698,10 +680,16 @@
throw new ArrayIndexOutOfBoundsException(location);
}
- /*
- * (non-Javadoc)
+ /**
+ * Removes the object at the specified location from this vector. All
+ * elements with an index bigger than {@code location} have their index
+ * decreased by 1.
*
- * @see java.util.List#remove(int)
+ * @param location
+ * the index of the object to remove.
+ * @return the removed object.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
*/
@SuppressWarnings("unchecked")
@Override
@@ -723,12 +711,14 @@
/**
* Removes the first occurrence, starting at the beginning and moving
- * towards the end, of the specified object from this Vector.
+ * towards the end, of the specified object from this vector. All elements
+ * with an index bigger than the element that gets removed have their index
+ * decreased by 1.
*
* @param object
- * the object to remove from this Vector
- * @return true if the specified object was found, false otherwise
- *
+ * the object to remove from this vector.
+ * @return {@code true} if the specified object was found, {@code false}
+ * otherwise.
* @see #removeAllElements
* @see #removeElementAt
* @see #size
@@ -739,12 +729,14 @@
}
/**
- * Removes all occurrences in this Vector of each object in the specified
+ * Removes all occurrences in this vector of each object in the specified
* Collection.
*
* @param collection
- * the Collection of objects to remove
- * @return true if this Vector is modified, false otherwise
+ * the collection of objects to remove.
+ * @return {@code true} if this vector is modified, {@code false} otherwise.
+ * @see #remove(Object)
+ * @see #contains(Object)
*/
@Override
public synchronized boolean removeAll(Collection<?> collection) {
@@ -752,7 +744,7 @@
}
/**
- * Removes all elements from this Vector, leaving the size zero and the
+ * Removes all elements from this vector, leaving the size zero and the
* capacity unchanged.
*
* @see #isEmpty
@@ -768,12 +760,14 @@
/**
* Removes the first occurrence, starting at the beginning and moving
- * towards the end, of the specified object from this Vector.
+ * towards the end, of the specified object from this vector. All elements
+ * with an index bigger than the element that gets removed have their index
+ * decreased by 1.
*
* @param object
- * the object to remove from this Vector
- * @return true if the specified object was found, false otherwise
- *
+ * the object to remove from this vector.
+ * @return {@code true} if the specified object was found, {@code false}
+ * otherwise.
* @see #removeAllElements
* @see #removeElementAt
* @see #size
@@ -788,15 +782,14 @@
}
/**
- * Removes the element found at index position <code>location</code> from
- * this <code>Vector</code> and decrements the size accordingly.
+ * Removes the element found at index position {@code location} from
+ * this {@code Vector}. All elements with an index bigger than
+ * {@code location} have their index decreased by 1.
*
* @param location
- * the index of the element to remove
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the index of the element to remove.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
* @see #removeElement
* @see #removeAllElements
* @see #size
@@ -818,16 +811,16 @@
/**
* Removes the objects in the specified range from the start to the, but not
- * including, end index.
+ * including, end index. All elements with an index bigger than or equal to
+ * {@code end} have their index decreased by {@code end - start}.
*
* @param start
- * the index at which to start removing
+ * the index at which to start removing.
* @param end
- * the index one past the end of the range to remove
- *
- * @exception IndexOutOfBoundsException
- * when <code>start < 0, start > end</code> or
- * <code>end > size()</code>
+ * the index one past the end of the range to remove.
+ * @throws IndexOutOfBoundsException
+ * if {@code start < 0, start > end} or
+ * {@code end > size()}.
*/
@Override
protected void removeRange(int start, int end) {
@@ -852,12 +845,13 @@
}
/**
- * Removes all objects from this Vector that are not contained in the
- * specified Collection.
+ * Removes all objects from this vector that are not contained in the
+ * specified collection.
*
* @param collection
- * the Collection of objects to retain
- * @return true if this Vector is modified, false otherwise
+ * the collection of objects to retain.
+ * @return {@code true} if this vector is modified, {@code false} otherwise.
+ * @see #remove(Object)
*/
@Override
public synchronized boolean retainAll(Collection<?> collection) {
@@ -865,18 +859,16 @@
}
/**
- * Replaces the element at the specified location in this Vector with the
+ * Replaces the element at the specified location in this vector with the
* specified object.
*
* @param location
- * the index at which to put the specified object
+ * the index at which to put the specified object.
* @param object
- * the object to add to this Vector
- * @return the previous element at the location
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the object to add to this vector.
+ * @return the previous element at the location.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
* @see #size
*/
@SuppressWarnings("unchecked")
@@ -891,17 +883,15 @@
}
/**
- * Replaces the element at the specified location in this Vector with the
+ * Replaces the element at the specified location in this vector with the
* specified object.
*
* @param object
- * the object to add to this Vector
+ * the object to add to this vector.
* @param location
- * the index at which to put the specified object
- *
- * @exception ArrayIndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the index at which to put the specified object.
+ * @throws ArrayIndexOutOfBoundsException
+ * if {@code location < 0 || location >= size()}.
* @see #size
*/
public synchronized void setElementAt(E object, int location) {
@@ -913,14 +903,13 @@
}
/**
- * Sets the size of this Vector to the specified size. If there are more
- * than length elements in this Vector, the elements at end are lost. If
- * there are less than length elements in the Vector, the additional
+ * Sets the size of this vector to the specified size. If there are more
+ * than length elements in this vector, the elements at end are lost. If
+ * there are less than length elements in the vector, the additional
* elements contain null.
*
* @param length
- * the new size of this Vector
- *
+ * the new size of this vector.
* @see #size
*/
public synchronized void setSize(int length) {
@@ -936,10 +925,9 @@
}
/**
- * Answers the number of elements in this Vector.
- *
- * @return the number of elements in this Vector
+ * Returns the number of elements in this vector.
*
+ * @return the number of elements in this vector.
* @see #elementCount
* @see #lastElement
*/
@@ -949,19 +937,19 @@
}
/**
- * Answers a List of the specified portion of this Vector from the start
+ * Returns a List of the specified portion of this vector from the start
* index to one less than the end index. The returned List is backed by this
- * Vector so changes to one are reflected by the other.
+ * vector so changes to one are reflected by the other.
*
* @param start
- * the index at which to start the sublist
+ * the index at which to start the sublist.
* @param end
- * the index one past the end of the sublist
- * @return a List of a portion of this Vector
- *
- * @exception IndexOutOfBoundsException
- * when <code>start < 0 or <code>end > size()</code>
- * @exception IllegalArgumentException when <code>start > end</code>
+ * the index one past the end of the sublist.
+ * @return a List of a portion of this vector.
+ * @throws IndexOutOfBoundsException
+ * if {@code start < 0} or {@code end > size()}.
+ * @throws IllegalArgumentException
+ * if {@code start > end}.
*/
@Override
public synchronized List<E> subList(int start, int end) {
@@ -970,9 +958,9 @@
}
/**
- * Answers a new array containing all elements contained in this Vector.
+ * Returns a new array containing all elements contained in this vector.
*
- * @return an array of the elements from this Vector
+ * @return an array of the elements from this vector.
*/
@Override
public synchronized Object[] toArray() {
@@ -982,19 +970,18 @@
}
/**
- * Answers an array containing all elements contained in this Vector. If the
+ * Returns an array containing all elements contained in this vector. If the
* specified array is large enough to hold the elements, the specified array
* is used, otherwise an array of the same type is created. If the specified
- * array is used and is larger than this Vector, the array element following
+ * array is used and is larger than this vector, the array element following
* the collection elements is set to null.
*
* @param contents
- * the array
- * @return an array of the elements from this Vector
- *
- * @exception ArrayStoreException
- * when the type of an element in this Vector cannot be
- * stored in the type of the specified array
+ * the array to fill.
+ * @return an array of the elements from this vector.
+ * @throws ArrayStoreException
+ * if the type of an element in this vector cannot be
+ * stored in the type of the specified array.
*/
@Override
@SuppressWarnings("unchecked")
@@ -1011,10 +998,9 @@
}
/**
- * Answers the string representation of this Vector.
- *
- * @return the string representation of this Vector
+ * Returns the string representation of this vector.
*
+ * @return the string representation of this vector.
* @see #elements
*/
@Override
@@ -1043,7 +1029,7 @@
}
/**
- * Sets the capacity of this Vector to be the same as the size.
+ * Sets the capacity of this vector to be the same as the size.
*
* @see #capacity
* @see #ensureCapacity