Straightforward use of ant javadoc on JDK25+

[jtulach]

Problem Description

Generating Javadoc on JDK25+ fails as described on mailing list:

netbeans$ JAVA_HOME=/jdk-25/ ant -q -f ide/projectapi javadoc
Trying to override old definition of task javac
Trying to override old definition of task java
Trying to override old definition of task javadoc
Trying to override old definition of task junit
     [echo] Build number : 20261001-e3c161964007
Trying to override old definition of task custom-javac

BUILD FAILED
/home/devel/NetBeansProjects/netbeans/nbbuild/templates/projectized.xml:409:
The following error occurred while executing this line:
/home/devel/NetBeansProjects/netbeans/nbbuild/javadoctools/links.xml:229:
JAXP00010004: The accumulated size of entities is "100 001" that
exceeded the "100 000" limit set by "jdk.xml.totalEntitySizeLimit".

Workaround

The way this is currently handled is covered in the README at https://github.com/apache/netbeans#generating-javadoc

export ANT_OPTS=-Djdk.xml.totalEntitySizeLimit=200000

as pointed out by @neilcsmith-net

Review the Fix

@matthiasblaesing and @mbien joined the discussion and showed an interest in proper review. Let this PR be a forum for such a review.

[mbien]

makes sense overall.

The title is a bit misleading though, given that we already build the javadoc using JDK 25 for NetBeans releases with some of the newer features enabled. Something like "configure parser limits for javadoc target" would be more precise IMO, since the current title would imply that it can't be built on JDK 25 and above right now.

This would also have to remove

netbeans/README.md

Line 84 in d5a2acd

* On JDK 24 or later, building javadoc may require to raise the jaxp entity limit by setting `export ANT_OPTS=-Djdk.xml.totalEntitySizeLimit=200000`

and

netbeans/.github/workflows/main.yml

Line 471 in d5a2acd

export ANT_OPTS=-Djdk.xml.totalEntitySizeLimit=200000

with the same commit.

We should do that for jenkins too (probably at https://github.com/apache/netbeans-jenkins-lib/blob/master/vars/asfMainNetBeansBuild.groovy) Eric/Neil know that area better.

[jtulach]

makes sense overall.

• thanks
• title updated to "Straightforward use of ant javadoc on JDK25+"
• references to the property removed in c27f11b

We should do that for jenkins too (probably at https://github.com/apache/netbeans-jenkins-lib/blob/master/vars/asfMainNetBeansBuild.groovy) Eric/Neil know that area better.

• I am awaiting instructions, but that would (obviously) be another PR/commit

[neilcsmith-net]

Makes sense overall. Added @ebarboni as reviewer as he's probably done the most work on Javadoc here. Please wait for his input before merging.

Is the naming sysproperty deliberate? Seems confusing with the same named element for other tasks we already have in a bunch of places. I assume it can't conflict?

There seem to be a lot of warnings about the property already being set in the CI, even after removing the environment variable? Is this setting in the right place? I assume the JDK also caches the first value it sees when needed.

We should do that for jenkins too (probably at https://github.com/apache/netbeans-jenkins-lib/blob/master/vars/asfMainNetBeansBuild.groovy) Eric/Neil know that area better.

Could possibly change for master build section. The other sections still have to cover occasional rebuilds on old release branches IIRC.

[ebarboni]

LGTM,

it works well with jdk25, it simplify build

PS:
there is a change in jdk26+ that remove jdk.jsobject => java.source.base javadoc are KO but not because of this PR

[matthiasblaesing]

Makes sense to me. Alternative (more specialized tasks) could be done, but this is small, well readable and solves the problem, so lets keep it. Thank you.

[matthiasblaesing]

Nitpick: I think it would be good to follow the formatting convention of the surrounding code.

[jtulach]

There is

    <taskdef name="hgid"
         classname="org.netbeans.nbbuild.HgId"
         classpath="${nbantext.jar}"/>

just few lines above. E.g. there doesn't seem to be a single formatting of these statements.