[8u] RFR 8160768: Add capability to custom resolve host/domain names within the default JNDI LDAP provider

[Zhengyu Gu]

Okay, I restored @since 12.

Updated: http://cr.openjdk.java.net/~zgu/JDK-8160768-8u/jdk/webrev.04/

I still don't have a strong opinion on this, but it is not a specific 
problem for this backport.

grep -r "@since" under jdk8u-dev/jdk, you see many versions > 8.

If it needs to be addressed, we should address them at once and setup a 
guideline for future backports.

Could I get formal review now? I bet Michael is anxious to get this in.

Thanks,

-Zhengyu


On 8/20/20 1:16 PM, Andrew Hughes wrote:
> On 08:51 Wed 19 Aug     , Severin Gehwolf wrote:
>> On Mon, 2020-08-17 at 06:26 +0100, Andrew Hughes wrote:
>>> On 11:51 Thu 13 Aug     , Severin Gehwolf wrote:
>>>> On Tue, 2020-08-11 at 14:48 -0400, Zhengyu Gu wrote:
>>>>> Hi Michael,
>>>>>
>>>>>> My tests/comments:
>>>>>> * @since still says 12. Is that correct?
>>>>
>>>> I agree. Zhengyu, please remove the @since 12 tags in this backport. It
>>>> doesn't make sense to have them in either 11 or 8.
>>>>
>>>
>>> I disagree. Such tags are a useful indicator that this is a backported
>>> API that wasn't in 8 GA.
>>
>> If we are starting to rely on @since tags as an indicator for backports
>> then we're in trouble. Instead, the bug system and source control
>> should be used for this. Given that, by removing the @since tag we
>> don't loose info that it's a backport.
>>
> 
> I didn't claim it was the only indicator.
> 
> It is useful to have it there in the source code if you're looking at
> the file concerned. It's also easily accessible. Being able to find
> the same information in the bug system or source control system
> requires you to be aware of their existence and to know to look for
> such information there.
> 
> To find the same information as the simple @since tag provides, I
> would need a checkout of the code from the source code repository, to
> know how to look up when that file was added, and then use the bug ID
> to lookup in the bug database in which JDK it was added. All a lot
> more complicated than one line of text that only requires the sources
> concerned.
> 
>>> What would be the issue with leaving them in?
>>
>> A couple of reasons:
>>
>>   * It's confusing. Mentioning something related to JDK 12 in a JDK 8
>>     tree is, well, confusing. It only wouldn't be so if you are
>>     intimately familiar with the process and know about this mailing
>>     list discussion.
> 
> I guess we have to beg to differ on this. I don't find it confusing.
> The @since tag has long-term well-defined semantics familiar to any
> Java user. I don't think it's that complicated to infer that if
> "@since 12" is used in 8u sources, it must have been backported.
> 
> I have used it in this manner for years (e.g. [0] [1]) and never been
> aware of anyone finding it confusing before.
> 
> On the contrary, to know to strip this information in a backport does
> require the person backporting to have knowledge of the need to do
> that and this discussion.
> 
>>   * @Since tags are usually used for *publicly* exposed classes as an
>>     aid for JDK API consumers. "This API is available for JDK 12 and
>>     onwards". I'm aware there are instances where it was used for
>>     internal classes too, but they become less prominent these days. It
>>     makes sense to have them for the original JDK 12 change. For the JDK
>>     8u backport, classes have been moved to a private package. It's not
>>     a 1-to-1 backport. The value of it being preserved regardless makes
>>     little sense. It's not the original class where it was added to
>>     begin with.
> 
> It is rare that public API would be backported. The one case where
> this has happened (ALPN+RSA-PSS) used "@since 8". I'd have preferred
> "@since 8M3" or "@since 8u41".
> 
> It not being publicly exposed actually seems more reason to just leave
> it in, as Javadoc won't be generated, so only someone looking at the
> source would see it.
> 
>>   * The SinceTree.java interface mentions this in its javadoc: "Returns
>>     the text explaining the availability of the item being documented."
>>     That's wrong for code in JDK 8. We'd be putting a @since 12 on code
>>     introduced in an update version of 8u.
> 
> 12 was its first availability.
> 
> You could use @since 8u272 if you like. The main concern is to make it
> clear that it wasn't part of 8 GA.
> 
>>
>> Overall, the drawbacks outweigh the benefits.
>>
> 
> I disagree. It seems mandating this could result in unnecessary
> differences between 8u & later sources, and additional work for
> backporters, all for no clear benefit.
> 
>> Thanks,
>> Severin
>>
> 
> [0] https://hg.openjdk.java.net/jdk7u/jdk7u/jdk/rev/9ab3c966585d
> [1] https://openjdk.java.net/jeps/129
> [2] https://jdk.java.net/java-se-ri/8-MR3
>