JDK-6176978 : current Javadoc's invocation and extension (Doclet) mechanisms are problematic
  • Type: Bug
  • Status: Resolved
  • Resolution: Fixed
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P2
  • Affected Version: 5.0,6u3
  • OS: generic
  • CPU: generic,x86
  • Submit Date: 2004-10-11
  • Updated Date: 2010-04-02
  • Resolved Date: 2004-10-21
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availabitlity Release.

To download the current JDK release, click here.
Other JDK 6 JDK 7
5.0u1 b05Resolved 6u10Resolved 7Fixed
Related Reports
Duplicate :  
Javadoc's invocation and extension (Doclet) mechanisms are rather inelegant. You invoke it programmatically by passing a list of command-line args, exactly like a main().  You use this to pass it -doclet, -classpath and -docletpath.  Javadoc creates a classloader from the paths you pass it, and uses that to load the named doclet class.  It sets this classloader as the context  classloader when invoking methods on the doclet, such as languageVersion().  (Annoyingly, it also fails to restore the context classloader, which has caused another 
bug already).  


The upshot of this seems to be that if tools.jar is not in the system classpath, javadoc and the doclet will load classes (such as LanguageVersion) from it using different

classloaders.  When javadoc goes to do its dynamic invocation on the doclet methods, it complains when its instanceof tests fail.  So, the LanguageVersion that it is complaining about really is a LanguageVersion, but it's just one from a different classloader.

The attached test case is a simple test case which demonstrates the problem using a dummy 
Doclet. It also shows that you *can* get things to work if you can just pass -classpath to the java command that is invoked.  This is exactly what the WLS ant script does, and is why thing work in the 'devenv' environment but not with out-of-the-box ant.
###@###.### 10/11/04 16:31 GMT

EVALUATION The bug as described can be fixed by having the URLClassLoader that's built by DocletInvoker (for loading doclets) inherit from the DocletInvoker instance's own class loader. This guarantees that the doclet and the javadoc tool are seeing tools.jar via the same classloader. However, BEA indicates that the full fix they require must also ensure that the doclet's own classes are loaded into the tool using a class loader created by the app that's invoking the tool. The doclet is not on the application class path. It can be found, however, using the context class loader that's being set by the app. So the most expeditious fix is probably to have DocletInvoker's class loader inherit from the context class loader. This still leaves open the possibility of getting the wrong tools.jar, but it isn't very likely. A far better fix, to be considered for Mustang, is to provide a new entry point to the javadoc tool that takes a Doclet instance (not the doclet's name) as a parameter. ###@###.### 10/14/04 21:32 GMT

SUGGESTED FIX There might be an easy fix to by modifying the constructor in com.sun.tools.javadoc.DocletInvoker so that the classloader it constructs gets the current context classloader (if there is one) as a parent. ###@###.### 10/11/04 16:31 GMT