United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-6176978 current Javadoc's invocation and extension (Doclet) mechanisms are problematic
JDK-6176978 : current Javadoc's invocation and extension (Doclet) mechanisms are problematic

Details
Type:
Bug
Submit Date:
2004-10-11
Status:
Resolved
Updated Date:
2010-04-02
Project Name:
JDK
Resolved Date:
2004-10-21
Component:
tools
OS:
generic
Sub-Component:
javadoc(tool)
CPU:
x86,generic
Priority:
P2
Resolution:
Fixed
Affected Versions:
5.0,6u3
Fixed Versions:
5.0u1 (b05)

Related Reports
Backport:
Backport:
Backport:
Duplicate:

Sub Tasks

Description
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

                                    

Comments
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
                                     
2004-10-11
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
                                     
2004-10-14



Hardware and Software, Engineered to Work Together