Re: RFR: 7147994 Hashtable rehash‎(‎) javadoc describes implementation details

[Stuart Marks]

The bug report states that this method specification describes implementation 
details, with the implication that implementation details should be avoided and 
that abstract specifications (contracts or invariants) should be provided 
instead. The alternative wording from the bug report removes the implementation 
details and replaces them with some informative text.

However, looking more closely about this change, I think it's wrong.

This is a protected method, so it can be overridden or called by a subclass. As 
such, the method specification should provide information necessary for 
subclasses to be implemented correctly, in particular, about "self-use" of the 
overridable methods from other parts of the superclass implementation. (See 
Bloch, Effective Java 3/e, Item 19. See also AbstractCollection.removeAll() for 
an example of this in practice.)

I think the bug report is wrong because it suggests removing implementation 
details, when in fact this is a place where implementation details ought to be 
provided.

(One might argue that more implementation details should be provided here, but 
it's not clear that Hashtable was actually designed for subclassing. That said, 
it can be subclassed, and there are surely many subclasses out there relying on 
all kinds of behavior of Hashtable. It's probably not worth trying to document 
all of it though.)

So, I'm inclined to close this issue as Won't Fix.

s'marks


On 4/29/20 3:02 AM, Jayashree Sk1 wrote:
> Hi All,
>          Please find the below changes for the issues https://bugs.openjdk.java.net/browse/JDK-7147994
> It is a description change, which was already approved by the reviewer.
> 
> Thanks!
> 
> diff -r 59b5bd9a7168 src/java.base/share/classes/java/util/Hashtable.java
> --- a/src/java.base/share/classes/java/util/Hashtable.java      Mon Mar 16 02:16:49 2020 -0400
> +++ b/src/java.base/share/classes/java/util/Hashtable.java      Mon Mar 30 15:45:43 2020 +0530
> @@ -399,9 +399,9 @@
>       /**
>        * Increases the capacity of and internally reorganizes this
>        * hashtable, in order to accommodate and access its entries more
> -     * efficiently.  This method is called automatically when the
> -     * number of keys in the hashtable exceeds this hashtable's capacity
> -     * and load factor.
> +     * efficiently.  This method is called to increase the capacity of and
> +     * internally reorganize this hashtable in order to more efficiently
> +     * accommodate and access its entries.
>        */
>       @SuppressWarnings("unchecked")
>       protected void rehash() {
>