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

Fri Aug 28 13:41:29 UTC 2020

Hi,

as for these @since 12 tags...

While I understand that there are both, arguments pro and con, I'd like to point out one specific thing in the context of this backport:
Classes com.sun.jndi.ldap.spi. LdapDnsProvider and com.sun.jndi.ldap.spi. LdapDnsProviderResult don't even exist in 12 and probably won't ever. In 12 we have javax.naming.ldap.spi.LdapDnsProvider and javax.naming.ldap.spi.LdapDnsProviderResult. So, given that change of package location, I opt to remove the @since 12 tags which I'm proposing in my webrev for 11u as well.

Andrew, does that convice you or you still insist on the tags?

Cheers
Christoph

> -----Original Message-----
> From: jdk8u-dev <jdk8u-dev-retn at openjdk.java.net> On Behalf Of Andrew
> Hughes
> Sent: Donnerstag, 20. August 2020 19:16
> To: Severin Gehwolf <sgehwolf at redhat.com>
> Cc: Zhengyu Gu <zgu at redhat.com>; Michael Osipov <1983-01-
> 06 at gmx.net>; Hohensee, Paul <hohensee at amazon.com>; jdk8u-dev
> <jdk8u-dev at openjdk.java.net>
> Subject: Re: [8u] RFR 8160768: Add capability to custom resolve host/domain
> names within the default JNDI LDAP provider
> 
> 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