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 [7/12] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashMap.java Thu May 7 21:43:41 2009
@@ -18,18 +18,34 @@
package java.util;
/**
- * LinkedHashMap is a variant on HashMap. Its entries are kept in a
+ * LinkedHashMap is a variant of HashMap. Its entries are kept in a
* doubly-linked list. The iteration order is, by default, the order in which
- * keys were inserted.
+ * keys were inserted. Reinserting an already existing key doesn't change the
+ * order. A key is existing if a call to {@code containsKey} would return true.
* <p>
- * If the three argument constructor is used, and <code>order</code> is
- * specified as <code>true</code>, the iteration would be in the order that
- * entries were accessed. The access order gets affected by put(), get(),
- * putAll() operations, but not by operations on the collection views.
+ * If the three argument constructor is used, and {@code order} is specified as
+ * {@code true}, the iteration will be in the order that entries were accessed.
+ * The access order gets affected by put(), get(), putAll() operations, but not
+ * by operations on the collection views.
* <p>
- * Null elements are allowed, and all the optional Map operations are supported.
+ * Null elements are allowed, and all the optional map operations are supported.
* <p>
- *
+ * <b>Note:</b> The implementation of {@code LinkedHashMap} is not synchronized.
+ * If one thread of several threads accessing an instance modifies the map
+ * structurally, access to the map needs to be synchronized. For
+ * insertion-ordered instances a structural modification is an operation that
+ * removes or adds an entry. Access-ordered instances also are structurally
+ * modified by put(), get() and putAll() since these methods change the order of
+ * the entries. Changes in the value of an entry are not structural changes.
+ * <p>
+ * The Iterator that can be created by calling the {@code iterator} method
+ * throws a {@code ConcurrentModificationException} if the map is structurally
+ * changed while an iterator is used to iterate over the elements. Only the
+ * {@code remove} method that is provided by the iterator allows for removal of
+ * elements during iteration. It is not possible to guarantee that this
+ * mechanism works in all cases of unsynchronized concurrent modification. It
+ * should only be used for debugging purposes.
+ *
* @since 1.4
*/
public class LinkedHashMap<K, V> extends HashMap<K, V> {
@@ -41,7 +57,7 @@
transient private LinkedHashMapEntry<K, V> head, tail;
/**
- * Constructs a new empty instance of LinkedHashMap.
+ * Constructs a new empty {@code LinkedHashMap} instance.
*/
public LinkedHashMap() {
super();
@@ -50,10 +66,13 @@
}
/**
- * Constructor with specified size.
+ * Constructs a new {@code LinkedHashMap} instance with the specified
+ * capacity.
*
* @param s
- * Size of LinkedHashMap required
+ * the initial capacity of this map.
+ * @throws IllegalArgumentException
+ * if the capacity is less than zero.
*/
public LinkedHashMap(int s) {
super(s);
@@ -62,12 +81,16 @@
}
/**
- * Constructor with specified size and load factor.
+ * Constructs a new {@code LinkedHashMap} instance with the specified
+ * capacity and load factor.
*
* @param s
- * Size of LinkedHashMap required
+ * the initial capacity of this map.
* @param lf
- * Load factor
+ * the initial load factor.
+ * @throws IllegalArgumentException
+ * when the capacity is less than zero or the load factor is
+ * less or equal to zero.
*/
public LinkedHashMap(int s, float lf) {
super(s, lf);
@@ -77,15 +100,21 @@
}
/**
- * Constructor with specified size, load factor and access order
+ * Constructs a new {@code LinkedHashMap} instance with the specified
+ * capacity, load factor and a flag specifying the ordering behavior.
*
* @param s
- * Size of LinkedHashmap required
+ * the initial capacity of this hash map.
* @param lf
- * Load factor
+ * the initial load factor.
* @param order
- * If true indicates that traversal order should begin with most
- * recently accessed
+ * {@code true} if the ordering should be done based on the last
+ * access (from least-recently accessed to most-recently
+ * accessed), and {@code false} if the ordering should be the
+ * order in which the entries were inserted.
+ * @throws IllegalArgumentException
+ * when the capacity is less than zero or the load factor is
+ * less or equal to zero.
*/
public LinkedHashMap(int s, float lf, boolean order) {
super(s, lf);
@@ -95,10 +124,11 @@
}
/**
- * Constructor with input map
+ * Constructs a new {@code LinkedHashMap} instance containing the mappings
+ * from the specified map. The order of the elements is preserved.
*
* @param m
- * Input map
+ * the mappings to add.
*/
public LinkedHashMap(Map<? extends K, ? extends V> m) {
accessOrder = false;
@@ -246,14 +276,6 @@
}
}
- /**
- * Searches this map for the specified value.
- *
- * @param value
- * the object to search for
- * @return true if <code>value</code> is a value of this HashMap, false
- * otherwise
- */
@Override
public boolean containsValue(Object value) {
LinkedHashMapEntry<K, V> entry = head;
@@ -288,11 +310,12 @@
}
/**
- * Retrieve the map value corresponding to the given key.
+ * Returns the value of the mapping with the specified key.
*
* @param key
- * Key value
- * @return mapped value or null if the key is not in the map
+ * 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) {
@@ -345,14 +368,14 @@
}
/**
- * Set the mapped value for the given key to the given value.
+ * Maps the specified key to the specified value.
*
* @param key
- * Key value
+ * the key.
* @param value
- * New mapped value
- * @return The old value if the key was already in the map or null
- * otherwise.
+ * 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) {
@@ -462,11 +485,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() {
@@ -474,11 +497,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() {
@@ -518,11 +541,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.
- *
- * @return a Collection of the values
+ * 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 size method
+ * wraps the map's size method and the 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 contained in this map.
*/
@Override
public Collection<V> values() {
@@ -553,12 +588,12 @@
}
/**
- * Remove the entry corresponding to the given key.
+ * Removes the mapping with the specified key from this map.
*
* @param key
- * the key
- * @return the value associated with the key or null if the key was no in
- * the 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) {
@@ -585,17 +620,18 @@
* This method is queried from the put and putAll methods to check if the
* eldest member of the map should be deleted before adding the new member.
* If this map was created with accessOrder = true, then the result of
- * removeEldesrEntry is assumed to be false.
+ * removeEldestEntry is assumed to be false.
*
* @param eldest
- * @return true if the eldest member should be removed
+ * the entry to check if it should be removed.
+ * @return {@code true} if the eldest member should be removed.
*/
protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
return false;
}
/**
- * Removes all mappings from this HashMap, leaving it empty.
+ * Removes all elements from this map, leaving it empty.
*
* @see #isEmpty()
* @see #size()
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedHashSet.java Thu May 7 21:43:41 2009
@@ -20,7 +20,7 @@
import java.io.Serializable;
/**
- * LinkedHashSet is a variant on HashSet. Its entries are kept in a
+ * LinkedHashSet is a variant of HashSet. Its entries are kept in a
* doubly-linked list. The iteration order is the order in which entries were
* inserted.
* <p>
@@ -28,8 +28,8 @@
* <p>
* Like HashSet, LinkedHashSet is not thread safe, so access by multiple threads
* must be synchronized by an external mechanism such as
- * Collections.synchronizedSet.
- *
+ * {@link Collections#synchronizedSet(Set)}.
+ *
* @since 1.4
*/
public class LinkedHashSet<E> extends HashSet<E> implements Set<E>, Cloneable,
@@ -38,41 +38,42 @@
private static final long serialVersionUID = -2851667679971038690L;
/**
- * Constructs a new empty instance of LinkedHashSet.
+ * Constructs a new empty instance of {@code LinkedHashSet}.
*/
public LinkedHashSet() {
super(new LinkedHashMap<E, HashSet<E>>());
}
/**
- * Constructs a new instance of LinkedHashSet with the specified capacity.
+ * Constructs a new instance of {@code LinkedHashSet} with the specified
+ * capacity.
*
* @param capacity
- * the initial capacity of this HashSet
+ * the initial capacity of this {@code LinkedHashSet}.
*/
public LinkedHashSet(int capacity) {
super(new LinkedHashMap<E, HashSet<E>>(capacity));
}
/**
- * Constructs a new instance of LinkedHashSet with the specified capacity
- * and load factor.
+ * Constructs a new instance of {@code LinkedHashSet} 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 LinkedHashSet(int capacity, float loadFactor) {
super(new LinkedHashMap<E, HashSet<E>>(capacity, loadFactor));
}
/**
- * Constructs a new instance of LinkedHashSet containing the unique elements
- * in the specified collection.
+ * Constructs a new instance of {@code LinkedHashSet} containing the unique
+ * elements in the specified collection.
*
* @param collection
- * the collection of elements to add
+ * the collection of elements to add.
*/
public LinkedHashSet(Collection<? extends E> collection) {
super(new LinkedHashMap<E, HashSet<E>>(collection.size() < 6 ? 11
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/LinkedList.java Thu May 7 21:43:41 2009
@@ -25,7 +25,7 @@
/**
* LinkedList is an implementation of List, backed by a linked list. All
- * optional operations are supported, adding, removing and replacing. The
+ * optional operations (adding, removing and replacing) are supported. The
* elements can be any objects.
*
* @since 1.2
@@ -176,8 +176,7 @@
}
/**
- * Constructs a new empty instance of LinkedList.
- *
+ * Constructs a new empty instance of {@code LinkedList}.
*/
public LinkedList() {
voidLink = new Link<E>(null, null, null);
@@ -186,13 +185,13 @@
}
/**
- * Constructs a new instance of <code>LinkedList</code> that holds all of
- * the elements contained in the supplied <code>collection</code>
- * argument. The order of the elements in this new <code>LinkedList</code>
- * will be determined by the iteration order of <code>collection</code>.
+ * Constructs a new instance of {@code LinkedList} that holds all of the
+ * elements contained in the specified {@code collection}. The order of the
+ * elements in this new {@code LinkedList} will be determined by the
+ * iteration order of {@code collection}.
*
* @param collection
- * the collection of elements to add
+ * the collection of elements to add.
*/
public LinkedList(Collection<? extends E> collection) {
this();
@@ -200,18 +199,17 @@
}
/**
- * Inserts the specified object into this LinkedList 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
- * LinkedList, the object is added at the end.
+ * Inserts the specified object into this {@code LinkedList} 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
+ * {@code LinkedList}, the object is added at the end.
*
* @param location
- * the index at which to insert
+ * the index at which to insert.
* @param object
- * the object to add
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the object to add.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
@Override
public void add(int location, E object) {
@@ -238,11 +236,11 @@
}
/**
- * Adds the specified object at the end of this LinkedList.
+ * Adds the specified object at the end of this {@code LinkedList}.
*
* @param object
- * the object to add
- * @return true
+ * the object to add.
+ * @return always true
*/
@Override
public boolean add(E object) {
@@ -257,18 +255,22 @@
}
/**
- * Inserts the objects in the specified Collection at the specified location
- * in this LinkedList. The objects are added in the order they are returned
- * from the <code>Collection</code> iterator.
+ * Inserts the objects in the specified collection at the specified location
+ * in this {@code LinkedList}. The objects are added in the order they are
+ * returned from the collection's iterator.
*
* @param location
- * the index at which to insert
+ * the index at which to insert.
* @param collection
- * the Collection of objects
- * @return true if this LinkedList is modified, false otherwise
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || > size()</code>
+ * the collection of objects
+ * @return {@code true} if this {@code LinkedList} is modified,
+ * {@code false} otherwise.
+ * @throws ClassCastException
+ * if the class of an object is inappropriate for this list.
+ * @throws IllegalArgumentException
+ * if an object cannot be added to this list.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || > size()}
*/
@Override
public boolean addAll(int location, Collection<? extends E> collection) {
@@ -306,11 +308,12 @@
}
/**
- * Adds the objects in the specified Collection to this LinkedList.
+ * Adds the objects in the specified Collection to this {@code LinkedList}.
*
* @param collection
- * the Collection of objects
- * @return true if this LinkedList is modified, false otherwise
+ * the collection of objects.
+ * @return {@code true} if this {@code LinkedList} is modified,
+ * {@code false} otherwise.
*/
@Override
public boolean addAll(Collection<? extends E> collection) {
@@ -335,10 +338,10 @@
}
/**
- * Adds the specified object at the beginning of this LinkedList.
+ * Adds the specified object at the beginning of this {@code LinkedList}.
*
* @param object
- * the object to add
+ * the object to add.
*/
public void addFirst(E object) {
Link<E> oldFirst = voidLink.next;
@@ -350,10 +353,10 @@
}
/**
- * Adds the specified object at the end of this LinkedList.
+ * Adds the specified object at the end of this {@code LinkedList}.
*
* @param object
- * the object to add
+ * the object to add.
*/
public void addLast(E object) {
Link<E> oldLast = voidLink.previous;
@@ -365,7 +368,7 @@
}
/**
- * Removes all elements from this LinkedList, leaving it empty.
+ * Removes all elements from this {@code LinkedList}, leaving it empty.
*
* @see List#isEmpty
* @see #size
@@ -381,11 +384,10 @@
}
/**
- * Answers a new LinkedList with the same elements and size as this
- * LinkedList.
- *
- * @return a shallow copy of this LinkedList
+ * Returns a new {@code LinkedList} with the same elements and size as this
+ * {@code LinkedList}.
*
+ * @return a shallow copy of this {@code LinkedList}.
* @see java.lang.Cloneable
*/
@SuppressWarnings("unchecked")
@@ -405,12 +407,12 @@
}
/**
- * Searches this LinkedList for the specified object.
+ * Searches this {@code LinkedList} for the specified object.
*
* @param object
- * the object to search for
- * @return true if <code>object</code> is an element of this LinkedList,
- * false otherwise
+ * the object to search for.
+ * @return {@code true} if {@code object} is an element of this
+ * {@code LinkedList}, {@code false} otherwise
*/
@Override
public boolean contains(Object object) {
@@ -452,12 +454,11 @@
}
/**
- * Answers the first element in this LinkedList.
- *
- * @return the first element
+ * Returns the first element in this {@code LinkedList}.
*
- * @exception NoSuchElementException
- * when this LinkedList is empty
+ * @return the first element.
+ * @throws NoSuchElementException
+ * if this {@code LinkedList} is empty.
*/
public E getFirst() {
Link<E> first = voidLink.next;
@@ -468,12 +469,11 @@
}
/**
- * Answers the last element in this LinkedList.
+ * Returns the last element in this {@code LinkedList}.
*
* @return the last element
- *
- * @exception NoSuchElementException
- * when this LinkedList is empty
+ * @throws NoSuchElementException
+ * if this {@code LinkedList} is empty
*/
public E getLast() {
Link<E> last = voidLink.previous;
@@ -483,14 +483,6 @@
throw new NoSuchElementException();
}
- /**
- * Searches this LinkedList for the specified object and returns the index
- * of the first occurrence.
- *
- * @param object
- * the object to search for
- * @return the index of the first occurrence of the object
- */
@Override
public int indexOf(Object object) {
int pos = 0;
@@ -516,12 +508,13 @@
}
/**
- * Searches this LinkedList for the specified object and returns the index
- * of the last occurrence.
+ * Searches this {@code LinkedList} for the specified object and returns the
+ * index of the last occurrence.
*
* @param object
* the object to search for
- * @return the index of the last occurrence of the object
+ * @return the index of the last occurrence of the object, or -1 if it was
+ * not found.
*/
@Override
public int lastIndexOf(Object object) {
@@ -548,17 +541,15 @@
}
/**
- * Answers a ListIterator on the elements of this LinkedList. The elements
- * are iterated in the same order that they occur in the LinkedList. The
- * iteration starts at the specified location.
+ * Returns a ListIterator on the elements of this {@code LinkedList}. The
+ * elements are iterated in the same order that they occur in the
+ * {@code LinkedList}. The iteration starts at the specified location.
*
* @param location
* the index at which to start the iteration
- * @return a ListIterator on the elements of this LinkedList
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * @return a ListIterator on the elements of this {@code LinkedList}
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
* @see ListIterator
*/
@Override
@@ -567,14 +558,13 @@
}
/**
- * Removes the object at the specified location from this LinkedList.
+ * Removes the object at the specified location from this {@code LinkedList}.
*
* @param location
* the index of the object to remove
* @return the removed object
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
@Override
public E remove(int location) {
@@ -625,12 +615,11 @@
}
/**
- * Removes the first object from this LinkedList.
- *
- * @return the removed object
+ * Removes the first object from this {@code LinkedList}.
*
- * @exception NoSuchElementException
- * when this LinkedList is empty
+ * @return the removed object.
+ * @throws NoSuchElementException
+ * if this {@code LinkedList} is empty.
*/
public E removeFirst() {
Link<E> first = voidLink.next;
@@ -646,12 +635,11 @@
}
/**
- * Removes the last object from this LinkedList.
- *
- * @return the removed object
+ * Removes the last object from this {@code LinkedList}.
*
- * @exception NoSuchElementException
- * when this LinkedList is empty
+ * @return the removed object.
+ * @throws NoSuchElementException
+ * if this {@code LinkedList} is empty.
*/
public E removeLast() {
Link<E> last = voidLink.previous;
@@ -667,17 +655,20 @@
}
/**
- * Replaces the element at the specified location in this LinkedList with
- * the specified object.
+ * Replaces the element at the specified location in this {@code LinkedList}
+ * 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
- * @return the previous element at the index
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the object to add.
+ * @return the previous element at the index.
+ * @throws ClassCastException
+ * if the class of an object is inappropriate for this list.
+ * @throws IllegalArgumentException
+ * if an object cannot be added to this list.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
@Override
public E set(int location, E object) {
@@ -700,9 +691,9 @@
}
/**
- * Answers the number of elements in this LinkedList.
+ * Returns the number of elements in this {@code LinkedList}.
*
- * @return the number of elements in this LinkedList
+ * @return the number of elements in this {@code LinkedList}.
*/
@Override
public int size() {
@@ -732,9 +723,10 @@
}
/**
- * Answers a new array containing all elements contained in this LinkedList.
+ * Returns a new array containing all elements contained in this
+ * {@code LinkedList}.
*
- * @return an array of the elements from this LinkedList
+ * @return an array of the elements from this {@code LinkedList}.
*/
@Override
public Object[] toArray() {
@@ -749,19 +741,19 @@
}
/**
- * Answers an array containing all elements contained in this LinkedList. 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 LinkedList, the array
- * element following the collection elements is set to null.
+ * Returns an array containing all elements contained in this
+ * {@code LinkedList}. 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
+ * {@code LinkedList}, the array element following the collection elements
+ * is set to null.
*
* @param contents
- * the array
- * @return an array of the elements from this LinkedList
- *
- * @exception ArrayStoreException
- * when the type of an element in this LinkedList cannot be
- * stored in the type of the specified array
+ * the array.
+ * @return an array of the elements from this {@code LinkedList}.
+ * @throws ArrayStoreException
+ * if the type of an element in this {@code LinkedList} cannot
+ * be stored in the type of the specified array.
*/
@Override
@SuppressWarnings("unchecked")
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/List.java Thu May 7 21:43:41 2009
@@ -17,339 +17,337 @@
package java.util;
+
/**
- * List is a collection which maintains an ordering for its elements. Every
- * element in the list has an index.
+ * A {@code List} is a collection which maintains an ordering for its elements. Every
+ * element in the {@code List} has an index. Each element can thus be accessed by its
+ * index, with the first index being zero. Normally, {@code List}s allow duplicate
+ * elements, as compared to Sets, where elements have to be unique.
*/
public interface List<E> extends Collection<E> {
-
/**
- * Inserts 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 List, the object
- * is added at the end.
+ * Inserts the specified object into this {@code List} at the specified location.
+ * The object is inserted before the current element at the specified
+ * location. If the location is equal to the size of this {@code List}, the object
+ * is added at the end. If the location is smaller than the size of this
+ * {@code List}, then all elements beyond the specified location are moved by one
+ * position towards the end of the {@code List}.
*
* @param location
- * the index at which to insert
+ * the index at which to insert.
* @param object
- * the object to add
- *
- * @exception UnsupportedOperationException
- * when adding to this List is not supported
- * @exception ClassCastException
- * when the class of the object is inappropriate for this
- * List
- * @exception IllegalArgumentException
- * when the object cannot be added to this List
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the object to add.
+ * @throws UnsupportedOperationException
+ * if adding to this {@code List} is not supported.
+ * @throws ClassCastException
+ * if the class of the object is inappropriate for this
+ * {@code List}.
+ * @throws IllegalArgumentException
+ * if the object cannot be added to this {@code List}.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || location > size()}
*/
public void add(int location, E object);
/**
- * Adds the specified object at the end of this List.
+ * Adds the specified object at the end of this {@code List}.
*
* @param object
- * the object to add
- * @return true
- *
- * @exception UnsupportedOperationException
- * when adding to this List is not supported
- * @exception ClassCastException
- * when the class of the object is inappropriate for this
- * List
- * @exception IllegalArgumentException
- * when the object cannot be added to this List
+ * the object to add.
+ * @return always true.
+ * @throws UnsupportedOperationException
+ * if adding to this {@code List} is not supported.
+ * @throws ClassCastException
+ * if the class of the object is inappropriate for this
+ * {@code List}.
+ * @throws IllegalArgumentException
+ * if the object cannot be added to this {@code List}.
*/
public boolean add(E object);
/**
- * Inserts the objects in the specified Collection at the specified location
- * in this List. The objects are added in the order they are returned from
- * the Collection iterator.
+ * Inserts the objects in the specified collection at the specified location
+ * in this {@code List}. The objects are added in the order they are returned from
+ * the collection's iterator.
*
* @param location
- * the index at which to insert
+ * the index at which to insert.
* @param collection
- * the Collection of objects
- * @return true if this List is modified, false otherwise
- *
- * @exception UnsupportedOperationException
- * when adding to this List is not supported
- * @exception ClassCastException
- * when the class of an object is inappropriate for this List
- * @exception IllegalArgumentException
- * when an object cannot be added to this List
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the collection of objects to be inserted.
+ * @return true if this {@code List} has been modified through the insertion, false
+ * otherwise (i.e. if the passed collection was empty).
+ * @throws UnsupportedOperationException
+ * if adding to this {@code List} is not supported.
+ * @throws ClassCastException
+ * if the class of an object is inappropriate for this
+ * {@code List}.
+ * @throws IllegalArgumentException
+ * if an object cannot be added to this {@code List}.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || > size()}
*/
public boolean addAll(int location, Collection<? extends E> collection);
/**
- * Adds the objects in the specified Collection to the end of this List. The
- * objects are added in the order they are returned from the Collection
- * iterator.
+ * Adds the objects in the specified collection to the end of this {@code List}. The
+ * objects are added in the order in which they are returned from the
+ * collection's iterator.
*
* @param collection
- * the Collection of objects
- * @return true if this List is modified, false otherwise
- *
- * @exception UnsupportedOperationException
- * when adding to this List is not supported
- * @exception ClassCastException
- * when the class of an object is inappropriate for this List
- * @exception IllegalArgumentException
- * when an object cannot be added to this List
+ * the collection of objects.
+ * @return {@code true} if this {@code List} is modified, {@code false} otherwise
+ * (i.e. if the passed collection was empty).
+ * @throws UnsupportedOperationException
+ * if adding to this {@code List} is not supported.
+ * @throws ClassCastException
+ * if the class of an object is inappropriate for this
+ * {@code List}.
+ * @throws IllegalArgumentException
+ * if an object cannot be added to this {@code List}.
*/
public boolean addAll(Collection<? extends E> collection);
/**
- * Removes all elements from this List, leaving it empty.
- *
- * @exception UnsupportedOperationException
- * when removing from this List is not supported
+ * Removes all elements from this {@code List}, leaving it empty.
*
+ * @throws UnsupportedOperationException
+ * if removing from this {@code List} is not supported.
* @see #isEmpty
* @see #size
*/
public void clear();
/**
- * Searches this List for the specified object.
+ * Tests whether this {@code List} contains the specified object.
*
* @param object
- * the object to search for
- * @return true if object is an element of this List, false otherwise
+ * the object to search for.
+ * @return {@code true} if object is an element of this {@code List}, {@code false}
+ * otherwise
*/
public boolean contains(Object object);
/**
- * Searches this List for all objects in the specified Collection.
+ * Tests whether this {@code List} contains all objects contained in the
+ * specified collection.
*
* @param collection
- * the Collection of objects
- * @return true if all objects in the specified Collection are elements of
- * this List, false otherwise
+ * the collection of objects
+ * @return {@code true} if all objects in the specified collection are
+ * elements of this {@code List}, {@code false} otherwise.
*/
public boolean containsAll(Collection<?> collection);
/**
- * Compares the argument to the receiver, and answers true if they represent
- * the <em>same</em> object using a class specific comparison.
+ * Compares the given object with the {@code List}, and returns true if they
+ * represent the <em>same</em> object using a class specific comparison. For
+ * {@code List}s, this means that they contain the same elements in exactly the same
+ * order.
*
* @param object
- * Object the object to compare with this object.
- * @return boolean <code>true</code> if the object is the same as this
- * object <code>false</code> if it is different from this object.
+ * the object to compare with this object.
+ * @return boolean {@code true} if the object is the same as this object,
+ * and {@code false} if it is different from this object.
* @see #hashCode
*/
public boolean equals(Object object);
/**
- * Answers the element at the specified location in this List.
+ * Returns the element at the specified location in this {@code List}.
*
* @param location
- * the index of the element to return
- * @return the element at the specified location
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the index of the element to return.
+ * @return the element at the specified location.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
public E get(int location);
/**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
+ * Returns the hash code for this {@code List}. It is calculated by taking each
+ * element' hashcode and its position in the {@code List} into account.
*
- * @return the receiver's hash
- *
- * @see #equals
+ * @return the hash code of the {@code List}.
*/
public int hashCode();
/**
- * Searches this List for the specified object and returns the index of the
+ * Searches this {@code List} for the specified object and returns the index of the
* first occurrence.
*
* @param object
- * the object to search for
- * @return the index of the first occurrence of the object
+ * the object to search for.
+ * @return the index of the first occurrence of the object or -1 if the
+ * object was not found.
*/
public int indexOf(Object object);
/**
- * Answers if this List has no elements, a size of zero.
- *
- * @return true if this List has no elements, false otherwise
+ * Returns whether this {@code List} contains no elements.
*
+ * @return {@code true} if this {@code List} has no elements, {@code false}
+ * otherwise.
* @see #size
*/
public boolean isEmpty();
/**
- * Answers an Iterator on the elements of this List. The elements are
- * iterated in the same order that they occur in the List.
- *
- * @return an Iterator on the elements of this List
+ * Returns an iterator on the elements of this {@code List}. The elements are
+ * iterated in the same order as they occur in the {@code List}.
*
+ * @return an iterator on the elements of this {@code List}.
* @see Iterator
*/
public Iterator<E> iterator();
/**
- * Searches this List for the specified object and returns the index of the
+ * Searches this {@code List} for the specified object and returns the index of the
* last occurrence.
*
* @param object
- * the object to search for
- * @return the index of the last occurrence of the object
+ * the object to search for.
+ * @return the index of the last occurrence of the object, or -1 if the
+ * object was not found.
*/
public int lastIndexOf(Object object);
/**
- * Answers a ListIterator on the elements of this List. The elements are
- * iterated in the same order that they occur in the List.
+ * Returns a {@code List} iterator on the elements of this {@code List}. The elements are
+ * iterated in the same order that they occur in the {@code List}.
*
- * @return a ListIterator on the elements of this List
+ * @return a {@code List} iterator on the elements of this {@code List}
*
* @see ListIterator
*/
public ListIterator<E> listIterator();
/**
- * Answers a ListIterator on the elements of this List. The elements are
- * iterated in the same order that they occur in the List. The iteration
+ * Returns a list iterator on the elements of this {@code List}. The elements are
+ * iterated in the same order as they occur in the {@code List}. The iteration
* starts at the specified location.
*
* @param location
- * the index at which to start the iteration
- * @return a ListIterator on the elements of this List
- *
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
- *
+ * the index at which to start the iteration.
+ * @return a list iterator on the elements of this {@code List}.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || location > size()}
* @see ListIterator
*/
public ListIterator<E> listIterator(int location);
/**
- * Removes the object at the specified location from this List.
+ * Removes the object at the specified location from this {@code List}.
*
* @param location
- * the index of the object to remove
- * @return the removed object
- *
- * @exception UnsupportedOperationException
- * when removing from this List is not supported
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the index of the object to remove.
+ * @return the removed object.
+ * @throws UnsupportedOperationException
+ * if removing from this {@code List} is not supported.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
public E remove(int location);
/**
- * Removes the first occurrence of the specified object from this List.
+ * Removes the first occurrence of the specified object from this {@code List}.
*
* @param object
- * the object to remove
- * @return true if this List is modified, false otherwise
- *
- * @exception UnsupportedOperationException
- * when removing from this List is not supported
+ * the object to remove.
+ * @return true if this {@code List} was modified by this operation, false
+ * otherwise.
+ * @throws UnsupportedOperationException
+ * if removing from this {@code List} is not supported.
*/
public boolean remove(Object object);
/**
- * Removes all occurrences in this List of each object in the specified
- * Collection.
+ * Removes all occurrences in this {@code List} of each object in the specified
+ * collection.
*
* @param collection
- * the Collection of objects to remove
- * @return true if this List is modified, false otherwise
- *
- * @exception UnsupportedOperationException
- * when removing from this List is not supported
+ * the collection of objects to remove.
+ * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
+ * @throws UnsupportedOperationException
+ * if removing from this {@code List} is not supported.
*/
public boolean removeAll(Collection<?> collection);
/**
- * Removes all objects from this List that are not contained in the
- * specified Collection.
+ * Removes all objects from this {@code List} that are not contained in the
+ * specified collection.
*
* @param collection
- * the Collection of objects to retain
- * @return true if this List is modified, false otherwise
- *
- * @exception UnsupportedOperationException
- * when removing from this List is not supported
+ * the collection of objects to retain.
+ * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
+ * @throws UnsupportedOperationException
+ * if removing from this {@code List} is not supported.
*/
public boolean retainAll(Collection<?> collection);
/**
- * Replaces the element at the specified location in this List with the
- * specified object.
+ * Replaces the element at the specified location in this {@code List} with the
+ * specified object. This operation does not change the size of the {@code List}.
*
* @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
- * @return the previous element at the index
- *
- * @exception UnsupportedOperationException
- * when replacing elements in this List is not supported
- * @exception ClassCastException
- * when the class of an object is inappropriate for this List
- * @exception IllegalArgumentException
- * when an object cannot be added to this List
- * @exception IndexOutOfBoundsException
- * when <code>location < 0 || >= size()</code>
+ * the object to insert.
+ * @return the previous element at the index.
+ * @throws UnsupportedOperationException
+ * if replacing elements in this {@code List} is not supported.
+ * @throws ClassCastException
+ * if the class of an object is inappropriate for this
+ * {@code List}.
+ * @throws IllegalArgumentException
+ * if an object cannot be added to this {@code List}.
+ * @throws IndexOutOfBoundsException
+ * if {@code location < 0 || >= size()}
*/
public E set(int location, E object);
/**
- * Answers the number of elements in this List.
+ * Returns the number of elements in this {@code List}.
*
- * @return the number of elements in this List
+ * @return the number of elements in this {@code List}.
*/
public int size();
/**
- * Answers a List of the specified portion of this List from the start index
- * to one less than the end index. The returned List is backed by this list
- * so changes to one are reflected by the other.
+ * Returns a {@code List} of the specified portion of this {@code List} from the given start
+ * index to the end index minus one. The returned {@code List} is backed by this
+ * {@code List} so changes to it 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 List
- *
- * @exception IndexOutOfBoundsException
- * when <code>start < 0, start > end</code> or
- * <code>end > size()</code>
+ * the index one past the end of the sublist.
+ * @return a list of a portion of this {@code List}.
+ * @throws IndexOutOfBoundsException
+ * if {@code start < 0, start > end} or {@code end >
+ * size()}
*/
public List<E> subList(int start, int end);
/**
- * Answers an array containing all elements contained in this List.
+ * Returns an array containing all elements contained in this {@code List}.
*
- * @return an array of the elements from this List
+ * @return an array of the elements from this {@code List}.
*/
public Object[] toArray();
/**
- * Answers an array containing all elements contained in this List. If the
+ * Returns an array containing all elements contained in this {@code List}. 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 List, the array element following
+ * array is used and is larger than this {@code List}, the array element following
* the collection elements is set to null.
*
* @param array
- * the array
- * @return an array of the elements from this List
- *
- * @exception ArrayStoreException
- * when the type of an element in this List cannot be stored
- * in the type of the specified array
+ * the array.
+ * @return an array of the elements from this {@code List}.
+ * @throws ArrayStoreException
+ * if the type of an element in this {@code List} cannot be stored
+ * in the type of the specified array.
*/
public <T> T[] toArray(T[] array);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListIterator.java Thu May 7 21:43:41 2009
@@ -17,127 +17,116 @@
package java.util;
+
/**
* An ListIterator is used to sequence over a List of objects. ListIterator can
- * move backwards or forwards through the List.
+ * move backwards or forwards through the list.
*/
public interface ListIterator<E> extends Iterator<E> {
-
+
/**
- * Inserts the specified object into the list between <code>next</code>
- * and <code>previous</code>. The object inserted will be the previous
- * object.
+ * Inserts the specified object into the list between {@code next} and
+ * {@code previous}. The object inserted will be the previous object.
*
* @param object
- * the object to insert
- *
- * @exception UnsupportedOperationException
- * when adding is not supported by the list being iterated
- * @exception ClassCastException
- * when the class of the object is inappropriate for the list
- * @exception IllegalArgumentException
- * when the object cannot be added to the list
+ * the object to insert.
+ * @throws UnsupportedOperationException
+ * if adding is not supported by the list being iterated.
+ * @throws ClassCastException
+ * if the class of the object is inappropriate for the list.
+ * @throws IllegalArgumentException
+ * if the object cannot be added to the list.
*/
void add(E object);
/**
- * 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.
*
+ * @return {@code true} if there are more elements, {@code false} otherwise.
* @see #next
*/
public boolean hasNext();
/**
- * Answers if there are previous elements to iterate.
- *
- * @return true if there are previous elements, false otherwise
+ * Returns whether there are previous elements to iterate.
*
+ * @return {@code true} if there are previous elements, {@code false}
+ * otherwise.
* @see #previous
*/
public boolean hasPrevious();
/**
- * 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.
*
+ * @return the next object.
+ * @throws NoSuchElementException
+ * if there are no more elements.
* @see #hasNext
*/
public E next();
/**
- * Answers the index of the next object in the iteration.
- *
- * @return the index of the next object
- *
- * @exception NoSuchElementException
- * when there are no more elements
+ * Returns the index of the next object in the iteration.
*
+ * @return the index of the next object, or the size of the list if the
+ * iterator is at the end.
+ * @throws NoSuchElementException
+ * if there are no more elements.
* @see #next
*/
public int nextIndex();
/**
- * Answers the previous object in the iteration.
- *
- * @return the previous object
- *
- * @exception NoSuchElementException
- * when there are no previous elements
+ * Returns the previous object in the iteration.
*
+ * @return the previous object.
+ * @throws NoSuchElementException
+ * if there are no previous elements.
* @see #hasPrevious
*/
public E previous();
/**
- * Answers the index of the previous object in the iteration.
- *
- * @return the index of the previous object
- *
- * @exception NoSuchElementException
- * when there are no previous elements
+ * Returns the index of the previous object in the iteration.
*
+ * @return the index of the previous object, or -1 if the iterator is at the
+ * beginning.
+ * @throws NoSuchElementException
+ * if there are no previous elements.
* @see #previous
*/
public int previousIndex();
/**
- * Removes the last object returned by <code>next</code> or
- * <code>previous</code> from the list.
+ * Removes the last object returned by {@code next} or {@code previous} from
+ * the list.
*
- * @exception UnsupportedOperationException
- * when removing is not supported by the list being iterated
- * @exception IllegalStateException
- * when <code>next</code> or <code>previous</code> have
- * not been called, or <code>remove</code> or
- * <code>add</code> have already been called after the last
- * call to <code>next</code> or <code>previous</code>
+ * @throws UnsupportedOperationException
+ * if removing is not supported by the list being iterated.
+ * @throws IllegalStateException
+ * if {@code next} or {@code previous} have not been called, or
+ * {@code remove} or {@code add} have already been called after
+ * the last call to {@code next} or {@code previous}.
*/
public void remove();
/**
- * Replaces the last object returned by <code>next</code> or
- * <code>previous</code> with the specified object.
+ * Replaces the last object returned by {@code next} or {@code previous}
+ * with the specified object.
*
* @param object
- * the object to add
- *
- * @exception UnsupportedOperationException
- * when adding is not supported by the list being iterated
- * @exception ClassCastException
- * when the class of the object is inappropriate for the list
- * @exception IllegalArgumentException
- * when the object cannot be added to the list
- * @exception IllegalStateException
- * when <code>next</code> or <code>previous</code> have
- * not been called, or <code>remove</code> or
- * <code>add</code> have already been called after the last
- * call to <code>next</code> or <code>previous</code>
+ * the object to set.
+ * @throws UnsupportedOperationException
+ * if setting is not supported by the list being iterated
+ * @throws ClassCastException
+ * if the class of the object is inappropriate for the list.
+ * @throws IllegalArgumentException
+ * if the object cannot be added to the list.
+ * @throws IllegalStateException
+ * if {@code next} or {@code previous} have not been called, or
+ * {@code remove} or {@code add} have already been called after
+ * the last call to {@code next} or {@code previous}.
*/
void set(E object);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ListResourceBundle.java Thu May 7 21:43:41 2009
@@ -18,8 +18,8 @@
package java.util;
/**
- * ListResourceBundle is the abstract superclass of classes which provide
- * resources by implementing the <code>getContents()</code> method to return
+ * {@code ListResourceBundle} is the abstract superclass of classes which provide
+ * resources by implementing the {@code getContents()} method to return
* the list of resources.
*
* @see ResourceBundle
@@ -36,18 +36,19 @@
}
/**
- * Answers an Object array which contains the resources of this
- * ListResourceBundle. Each element in the array is an array of two
- * elements, the first is the resource key and the second is the resource.
+ * Returns an {@code Object} array which contains the resources of this
+ * {@code ListResourceBundle}. Each element in the array is an array of two
+ * elements, the first is the resource key string and the second is the
+ * resource.
*
- * @return a Object array containing the resources
+ * @return a {@code Object} array containing the resources.
*/
protected abstract Object[][] getContents();
/**
- * Answers the names of the resources contained in this ListResourceBundle.
+ * Returns the names of the resources contained in this {@code ListResourceBundle}.
*
- * @return an Enumeration of the resource names
+ * @return an {@code Enumeration} of the resource names.
*/
@Override
public Enumeration<String> getKeys() {
@@ -109,14 +110,6 @@
}
}
- /**
- * Answers the named resource from this ResourceBundle, or null if the
- * resource is not found.
- *
- * @param key
- * the name of the resource
- * @return the resource object
- */
@Override
public final Object handleGetObject(String key) {
initializeTable();
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Locale.java Thu May 7 21:43:41 2009
@@ -32,7 +32,7 @@
import com.ibm.icu.util.ULocale;
/**
- * Locale represents a language/country/variant combination. It is an identifier
+ * {@code Locale} represents a language/country/variant combination. It is an identifier
* which dictates particular conventions for the presentation of information.
* The language codes are two letter lowercase codes as defined by ISO-639. The
* country codes are three letter uppercase codes as defined by ISO-3166. The
@@ -185,36 +185,40 @@
}
/**
- * Constructs a new Locale using the specified language.
+ * Constructs a new {@code Locale} using the specified language.
*
* @param language
- *
+ * the language this {@code Locale} represents.
*/
public Locale(String language) {
this(language, "", ""); //$NON-NLS-1$//$NON-NLS-2$
}
/**
- * Constructs a new Locale using the specified language and country codes.
+ * Constructs a new {@code Locale} using the specified language and country codes.
*
* @param language
+ * the language this {@code Locale} represents.
* @param country
- *
+ * the country this {@code Locale} represents.
*/
public Locale(String language, String country) {
this(language, country, ""); //$NON-NLS-1$
}
/**
- * Constructs a new Locale using the specified language, country, and
+ * Constructs a new {@code Locale} using the specified language, country, and
* variant codes.
*
* @param language
+ * the language this {@code Locale} represents.
* @param country
+ * the country this {@code Locale} represents.
* @param variant
+ * the variant this {@code Locale} represents.
* @throws NullPointerException
- * if <code>language</code>, <code>country</code> or
- * <code>variant</code> is <code>null</code>.
+ * if {@code language}, {@code country}, or
+ * {@code variant} is {@code null}.
*/
public Locale(String language, String country, String variant) {
if (language == null || country == null || variant == null) {
@@ -246,11 +250,10 @@
}
/**
- * Answers a new Locale with the same language, country and variant codes as
- * this Locale.
- *
- * @return a shallow copy of this Locale
+ * Returns a new {@code Locale} with the same language, country and variant codes as
+ * this {@code Locale}.
*
+ * @return a shallow copy of this {@code Locale}.
* @see java.lang.Cloneable
*/
@Override
@@ -263,15 +266,14 @@
}
/**
- * Compares the specified object to this Locale and answer if they are
- * equal. The object must be an instance of Locale and have the same
+ * Compares the specified object to this {@code Locale} and returns whether they are
+ * equal. The object must be an instance of {@code Locale} and have the same
* language, country and variant.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this Locale, false
- * otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this {@code Locale},
+ * {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -374,9 +376,10 @@
}
/**
- * Gets the list of installed Locales.
- *
- * @return an array of Locale
+ * Gets the list of installed {@code Locale}. At least a {@code Locale} that is equal to
+ * {@code Locale.US} must be contained in this array.
+ *
+ * @return an array of {@code Locale}s.
*/
public static Locale[] getAvailableLocales() {
ULocale[] ulocales = ULocale.getAvailableLocales();
@@ -388,76 +391,77 @@
}
/**
- * Gets the country code for this Locale.
+ * Gets the country code for this {@code Locale} or an empty string of no country
+ * was set.
*
- * @return a country code
+ * @return a country code.
*/
public String getCountry() {
return countryCode;
}
/**
- * Gets the default Locale.
+ * Gets the default {@code Locale}.
*
- * @return the default Locale
+ * @return the default {@code Locale}.
*/
public static Locale getDefault() {
return defaultLocale;
}
/**
- * Gets the full country name in the default Locale for the country code of
- * this Locale. If there is no matching country name, the country code is
+ * Gets the full country name in the default {@code Locale} for the country code of
+ * this {@code Locale}. If there is no matching country name, the country code is
* returned.
*
- * @return a country name
+ * @return a country name.
*/
public final String getDisplayCountry() {
return getDisplayCountry(getDefault());
}
- /**
- * Gets the full country name in the specified Locale for the country code
- * of this Locale. If there is no matching country name, the country code is
- * returned.
- *
- * @param locale
- * the Locale
- * @return a country name
- */
+ /**
+ * Gets the full country name in the specified {@code Locale} for the country code
+ * of this {@code Locale}. If there is no matching country name, the country code is
+ * returned.
+ *
+ * @param locale
+ * the {@code Locale} for which the display name is retrieved.
+ * @return a country name.
+ */
public String getDisplayCountry(Locale locale) {
return ULocale.forLocale(this).getDisplayCountry(ULocale.forLocale(locale));
}
/**
- * Gets the full language name in the default Locale for the language code
- * of this Locale. If there is no matching language name, the language code
+ * Gets the full language name in the default {@code Locale} for the language code
+ * of this {@code Locale}. If there is no matching language name, the language code
* is returned.
*
- * @return a language name
+ * @return a language name.
*/
public final String getDisplayLanguage() {
return getDisplayLanguage(getDefault());
}
- /**
- * Gets the full language name in the specified Locale for the language code
- * of this Locale. If there is no matching language name, the language code
- * is returned.
- *
- * @param locale
- * the Locale
- * @return a language name
- */
+ /**
+ * Gets the full language name in the specified {@code Locale} for the language code
+ * of this {@code Locale}. If there is no matching language name, the language code
+ * is returned.
+ *
+ * @param locale
+ * the {@code Locale} for which the display name is retrieved.
+ * @return a language name.
+ */
public String getDisplayLanguage(Locale locale) {
return ULocale.forLocale(this).getDisplayLanguage(ULocale.forLocale(locale));
}
/**
- * Gets the full language, country, and variant names in the default Locale
- * for the codes of this Locale.
+ * Gets the full language, country, and variant names in the default {@code Locale}
+ * for the codes of this {@code Locale}.
*
- * @return a Locale name
+ * @return a {@code Locale} name.
*/
public final String getDisplayName() {
return getDisplayName(getDefault());
@@ -465,11 +469,11 @@
/**
* Gets the full language, country, and variant names in the specified
- * Locale for the codes of this Locale.
+ * Locale for the codes of this {@code Locale}.
*
* @param locale
- * the Locale
- * @return a Locale name
+ * the {@code Locale} for which the display name is retrieved.
+ * @return a {@code Locale} name.
*/
public String getDisplayName(Locale locale) {
int count = 0;
@@ -501,99 +505,98 @@
}
/**
- * Gets the full variant name in the default Locale for the variant code of
- * this Locale. If there is no matching variant name, the variant code is
+ * Gets the full variant name in the default {@code Locale} for the variant code of
+ * this {@code Locale}. If there is no matching variant name, the variant code is
* returned.
*
- * @return a variant name
+ * @return a variant name.
*/
public final String getDisplayVariant() {
return getDisplayVariant(getDefault());
}
- /**
- * Gets the full variant name in the specified Locale for the variant code
- * of this Locale. If there is no matching variant name, the variant code is
- * returned.
- *
- * @param locale
- * the Locale
- * @return a variant name
- */
+ /**
+ * Gets the full variant name in the specified {@code Locale} for the variant code
+ * of this {@code Locale}. If there is no matching variant name, the variant code is
+ * returned.
+ *
+ * @param locale
+ * the {@code Locale} for which the display name is retrieved.
+ * @return a variant name.
+ */
public String getDisplayVariant(Locale locale) {
return ULocale.forLocale(this).getDisplayVariant(ULocale.forLocale(locale));
}
- /**
- * Gets the three letter ISO country code which corresponds to the country
- * code for this Locale.
- *
- * @return a three letter ISO language code
- *
- * @exception MissingResourceException
- * when there is no matching three letter ISO country code
- */
+ /**
+ * Gets the three letter ISO country code which corresponds to the country
+ * code for this {@code Locale}.
+ *
+ * @return a three letter ISO language code.
+ * @throws MissingResourceException
+ * if there is no matching three letter ISO country code.
+ */
public String getISO3Country() throws MissingResourceException {
return ULocale.forLocale(this).getISO3Country();
}
- /**
- * Gets the three letter ISO language code which corresponds to the language
- * code for this Locale.
- *
- * @return a three letter ISO language code
- *
- * @exception MissingResourceException
- * when there is no matching three letter ISO language code
- */
+ /**
+ * Gets the three letter ISO language code which corresponds to the language
+ * code for this {@code Locale}.
+ *
+ * @return a three letter ISO language code.
+ * @throws MissingResourceException
+ * if there is no matching three letter ISO language code.
+ */
public String getISO3Language() throws MissingResourceException {
return ULocale.forLocale(this).getISO3Language();
}
/**
* Gets the list of two letter ISO country codes which can be used as the
- * country code for a Locale.
+ * country code for a {@code Locale}.
*
- * @return an array of String
+ * @return an array of strings.
*/
public static String[] getISOCountries() {
return ULocale.getISOCountries();
}
- /**
- * Gets the list of two letter ISO language codes which can be used as the
- * language code for a Locale.
- *
- * @return an array of String
- */
+ /**
+ * Gets the list of two letter ISO language codes which can be used as the
+ * language code for a {@code Locale}.
+ *
+ * @return an array of strings.
+ */
public static String[] getISOLanguages() {
return ULocale.getISOLanguages();
}
/**
- * Gets the language code for this Locale.
+ * Gets the language code for this {@code Locale} or the empty string of no language
+ * was set.
*
- * @return a language code
+ * @return a language code.
*/
public String getLanguage() {
return languageCode;
}
/**
- * Gets the variant code for this Locale.
+ * Gets the variant code for this {@code Locale} or an empty {@code String} of no variant
+ * was set.
*
- * @return a variant code
+ * @return a variant code.
*/
public String getVariant() {
return variantCode;
}
/**
- * 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
@@ -603,14 +606,13 @@
}
/**
- * Sets the default Locale to the specified Locale.
+ * Sets the default {@code Locale} to the specified {@code Locale}.
*
* @param locale
- * the new default Locale
- *
- * @exception SecurityException
- * when there is a security manager which does not allow this
- * operation
+ * the new default {@code Locale}.
+ * @throws SecurityException
+ * if there is a {@code SecurityManager} in place which does not allow this
+ * operation.
*/
public synchronized static void setDefault(Locale locale) {
if (locale != null) {
@@ -625,9 +627,17 @@
}
/**
- * Answers the string representation of this Locale.
- *
- * @return the string representation of this Locale
+ * Returns the string representation of this {@code Locale}. It consists of the
+ * language followed by the country and at the end the variant. They are
+ * separated by underscores. If the language is missing the string begins
+ * with an underscore. If the country is missing there are 2 underscores
+ * between the language and the variant. the variant alone canot be defined
+ * without a language and/or a country (in this case this method would
+ * return the empty string).
+ *
+ * Examples: "en", "en_US", "_US", "en__POSIX", "en_US_POSIX"
+ *
+ * @return the string representation of this {@code Locale}.
*/
@Override
public final String toString() {