Javadoc task : -link not linking external javadocs

Help/Discuss
1

I am trying to use -link to link to external javadocs for my javadoc tasks. Mainly this is links to Java EE references such as JPA, CDI and BV. I have the following in my build:

links += [
    'http://docs.oracle.com/javase/8/docs/api/',
    'http://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/',
    'http://docs.jboss.org/cdi/api/2.0/',
    'http://docs.oracle.com/javaee/7/api/'
]

Which causes Gradle to insert the following into the javadoc.options file it generates:

-link 'http://docs.oracle.com/javase/8/docs/api/'
-link 'http://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/'
-link 'http://docs.jboss.org/cdi/api/2.0/'
-link 'http://docs.oracle.com/javaee/7/api/'

but for some reason (maybe some other option it sets?) javadoc complains about references that each of these links provides. E.g.:

/projects/hibernate-orm/hibernate-core/src/main/java/org/hibernate/resource/beans/spi/ExtendedBeanManager.java:9: error: package javax.enterprise.inject.spi does not exist
import javax.enterprise.inject.spi.BeanManager;

  symbol:   class BeanManager
  location: interface LifecycleListener

or

/projects/hibernate-orm/hibernate-core/src/main/java/org/hibernate/cfg/beanvalidation/TypeSafeActivator.java:104: error: cannot find symbol
        public static void applyCallbackListeners(ValidatorFactory validatorFactory, ActivationContext activationContext) {
                                                  ^
  symbol:   class ValidatorFactory
  location: class TypeSafeActivator

etc.

But again each of these references exist in the provided external resources (-links):

http://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/javax/validation/ValidatorFactory.html
http://docs.jboss.org/cdi/api/2.0/javax/enterprise/inject/spi/BeanManager.html

Help?

2

Linked Hibernate Jira

3

I don’t think you’re having any issue with the links themselves. Extracting just the relevant javadoc configuration and creating a few dummy classes that reference the same classes from those links in a sample project works as expected.

I didn’t dive deep into the root cause, but it seems classpath is not ending up with what would be expected for the javadoc task. Specifically, I don’t think some of your provided dependencies are being taken into account for the task and causing the actual problem. Explicitly resetting the classpath for the task (even to the default) seems to work, but I would only consider that a work-around, not a real solution (as are some other obscure tweaks that seem to influence things just enough, but aren’t even good work-arounds). Without a little more “general tidying” it’s going to be hard to find the exact cause.

Also, your first and last links to http://docs.oracle.com/ may also cause trouble because they redirect to HTTPS. I’ve seen issues linking the platform javadocs when not providing the link as https://docs.oracle.com/.

4

Thanks for the thoughts James…

Ah, I had not even considered the classpath. I will play with that some more…

I actually changed them from https to http thinking that the https might be causing problems. I will switch those back.

5

Although I am a little confused as to why subProject.sourceSets.main.compileClasspath would not contain deps from provided configuration