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

[Andrew Hughes]

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
-- 
Andrew :)

Senior Free Java Software Engineer
OpenJDK Package Owner
Red Hat, Inc. (http://www.redhat.com)

PGP Key: ed25519/0xCFDA0F9B35964222 (hkp://keys.gnupg.net)
Fingerprint = 5132 579D D154 0ED2 3E04  C5A0 CFDA 0F9B 3596 4222