Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 76955 invoked from network); 7 May 2009 21:44:40 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 7 May 2009 21:44:40 -0000 Received: (qmail 66634 invoked by uid 500); 7 May 2009 21:44:40 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 66585 invoked by uid 500); 7 May 2009 21:44:40 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 66576 invoked by uid 99); 7 May 2009 21:44:40 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 May 2009 21:44:40 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 May 2009 21:44:37 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id AFE5D2388BB8; Thu, 7 May 2009 21:43:51 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r772785 [12/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/ Date: Thu, 07 May 2009 21:43:44 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090507214351.AFE5D2388BB8@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/WeakHashMap.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/WeakHashMap.java?rev=772785&r1=772784&r2=772785&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/WeakHashMap.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/WeakHashMap.java Thu May 7 21:43:41 2009 @@ -21,10 +21,11 @@ import java.lang.ref.WeakReference; /** - * WeakHashMap is an implementation of Map with keys which are WeakReferences. - * The key/value mapping is removed when the key is no longer referenced. All - * optional operations are supported, adding and removing. Keys and values can - * be any objects. + * WeakHashMap is an implementation of Map with keys which are WeakReferences. A + * key/value mapping is removed when the key is no longer referenced. All + * optional operations (adding and removing) are supported. Keys and values can + * be any objects. Note that the garbage collector acts similar to a second + * thread on this collection, possibly removing keys. * * @since 1.2 * @see HashMap @@ -181,20 +182,20 @@ } /** - * Constructs a new empty instance of WeakHashMap. + * Constructs a new empty {@code WeakHashMap} instance. */ public WeakHashMap() { this(DEFAULT_SIZE); } /** - * Constructs a new instance of WeakHashMap with the specified capacity. + * Constructs a new {@code WeakHashMap} instance with the specified + * capacity. * * @param capacity - * the initial capacity of this WeakHashMap - * - * @exception IllegalArgumentException - * when the capacity is less than zero + * the initial capacity of this map. + * @throws IllegalArgumentException + * if the capacity is less than zero. */ public WeakHashMap(int capacity) { if (capacity >= 0) { @@ -209,17 +210,16 @@ } /** - * Constructs a new instance of WeakHashMap with the specified capacity and - * load factor. + * Constructs a new {@code WeakHashMap} instance with the specified capacity + * and load factor. * * @param capacity - * the initial capacity + * the initial capacity of this map. * @param loadFactor - * the initial load factor - * - * @exception IllegalArgumentException - * when the capacity is less than zero or the load factor is - * less or equal to zero + * the initial load factor. + * @throws IllegalArgumentException + * if the capacity is less than zero or the load factor is less + * or equal to zero. */ public WeakHashMap(int capacity, float loadFactor) { if (capacity >= 0 && loadFactor > 0) { @@ -234,11 +234,11 @@ } /** - * Constructs a new instance of HashMap containing the mappings from the - * specified Map. + * Constructs a new {@code WeakHashMap} instance containing the mappings + * from the specified map. * * @param map - * the mappings to add + * the mappings to add. */ public WeakHashMap(Map map) { this(map.size() < 6 ? 11 : map.size() * 2); @@ -246,10 +246,10 @@ } /** - * Removes all mappings from this WeakHashMap, leaving it empty. + * Removes all mappings from this map, leaving it empty. * - * @see #isEmpty - * @see #size + * @see #isEmpty() + * @see #size() */ @Override public void clear() { @@ -268,12 +268,12 @@ } /** - * Searches this WeakHashMap for the specified key. + * Returns whether this map contains the specified key. * * @param key - * the object to search for - * @return true if key is a key of this WeakHashMap, false - * otherwise + * the key to search for. + * @return {@code true} if this map contains the specified key, + * {@code false} otherwise. */ @Override public boolean containsKey(Object key) { @@ -281,12 +281,12 @@ } /** - * Answers a Set of the mappings contained in this WeakHashMap. Each element - * in the set is a Map.Entry. The set is backed by this WeakHashMap so - * changes to one are reflected by the other. The set does not support - * adding. - * - * @return a Set of the mappings + * 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. */ @Override public Set> entrySet() { @@ -340,11 +340,11 @@ } /** - * Answers a Set of the keys contained in this WeakHashMap. The set is - * backed by this WeakHashMap 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 keySet() { @@ -409,11 +409,23 @@ } /** - * Answers a Collection of the values contained in this WeakHashMap. The - * collection is backed by this WeakHashMap 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. + *

+ * 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. + *

+ * The collection is created when this method is called at first time and + * returned in response to all subsequent calls. This method may return + * different Collection when multiple calls to this method, since it has no + * synchronization performed. * - * @return a Collection of the values + * @return a collection of the values contained in this map. */ @Override public Collection values() { @@ -449,11 +461,12 @@ } /** - * Answers the value of the mapping with the specified key. + * Returns the value of the mapping with the specified key. * * @param key - * the key - * @return the value of the mapping with the specified key + * the key. + * @return the value of the mapping with the specified key, or {@code null} + * if no mapping for the specified key is found. */ @Override public V get(Object key) { @@ -503,13 +516,12 @@ } /** - * Searches this WeakHashMap for the specified value, and returns true, if - * at least one entry has this object as its value. + * Returns whether this map contains the specified value. * * @param value - * the object to search for - * @return true if value is a value in this WeakHashMap, - * false otherwise + * the value to search for. + * @return {@code true} if this map contains the specified value, + * {@code false} otherwise. */ @Override public boolean containsValue(Object value) { @@ -542,11 +554,9 @@ } /** - * Answers if this WeakHashMap has no elements, a size of zero. - * - * @return true if this HashMap has no elements, false otherwise + * Returns the number of elements in this map. * - * @see #size + * @return the number of elements in this map. */ @Override public boolean isEmpty() { @@ -587,11 +597,11 @@ * Maps the specified key to the specified value. * * @param key - * the key + * the key. * @param value - * the value - * @return the value of any previous mapping with the specified key or null - * if there was no mapping + * the value. + * @return the value of any previous mapping with the specified key or + * {@code null} if there was no mapping. */ @Override public V put(K key, V value) { @@ -654,9 +664,9 @@ * the given map. * * @param map - * the Map to copy mappings from + * the map to copy mappings from. * @throws NullPointerException - * if the given map is null + * if {@code map} is {@code null}. */ @Override public void putAll(Map map) { @@ -664,12 +674,12 @@ } /** - * Removes a mapping with the specified key from this WeakHashMap. + * 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 WeakHashMap + * 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) { @@ -704,9 +714,9 @@ } /** - * Answers the number of mappings in this WeakHashMap. + * Returns the number of elements in this map. * - * @return the number of mappings in this WeakHashMap + * @return the number of elements in this map. */ @Override public int size() {