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

[Stuart Marks]

OK, great, I've closed out the bug.

s'marks

On 4/29/20 10:29 PM, Jayashree Sk1 wrote:
> 
> Stuart, Thanks for all the details.
> All you have said makes sense to me, I have no contention for closing this issue as Won't Fix (am not related to originator, picked this issue up as starters to understand the contribution process)
> 
> 
> Regards!
> Jay
> 
> 
> 
> -----Stuart Marks <stuart.marks at oracle.com> wrote: -----
> To: Jayashree Sk1 <jayashreesk at in.ibm.com>
> From: Stuart Marks <stuart.marks at oracle.com>
> Date: 04/30/2020 09:53AM
> Cc: core-libs-dev at openjdk.java.net
> Subject: [EXTERNAL] Re: RFR: 7147994 Hashtable rehash‎(‎) javadoc describes implementation details
> 
> 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://urldefense.proofpoint.com/v2/url?u=https-3A__bugs.openjdk.java.net_browse_JDK-2D7147994&d=DwICaQ&c=jf_iaSHvJObTbx-siA1ZOg&r=rA_13vli8clPM_toR46hq8FVwH3XGr8z7cUfcQoqL-k&m=bNY044TQSELJWMafSRxC-62CyHMVnMxboXMG0qqU6CU&s=V9rN7MCO4rArlV8tRjEn44_Kl_tCH2h-xjqakCvpBxY&e=
>> 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() {
>>
> 
>