Public API for programmatic registration of Taglet?

[Jonathan Gibbons]

On 4/18/18 9:08 AM, Martin Desruisseaux wrote:
>
> Hello
>
> I'm trying to write an extension of the standard doclet together with 
> custom taglets in the same JAR file. The custom taglets and doclet 
> need to share information. But I faced the following difficulties:
>
> When the Taglet.init​(DocletEnvironment,Doclet) method is invoked, the 
> doclet argument given by the caller is the internal HtmlDoclet wrapped 
> by StandardDoclet, not my custom StandardDoclet subtype. So I can not 
> get my doclet and taglet in touch that way.
>
> The lazy workaround - shared static fields - does not work because the 
> taglet is loaded in a different class loader than the doclet. So even 
> if I change a static field value from the taglet, the doclet never see 
> that change. This is not a multi-threading issue; I tested with 
> volatile static field. I also verified that the class loaders for the 
> same class were different depending on whether the class of my JAR 
> file is accessed from the doclet or from the taglet.
>
> I tried to wrap DocletEnvironment in order to return a customised 
> ForwardingJavaFileManager, in an attempt to control which ClassLoader 
> is used for loading the taglet. But the standard doclet does not seem 
> to accept customized DocletEnvironment, as suggested by the error that 
> I got:
>
>     java.lang.ClassCastException: org.opengis.tools.doclet.ForwardingDocletEnvironment cannot be cast to jdk.javadoc/jdk.javadoc.internal.tool.DocEnvImpl
>              at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.WorkArounds.<init>(WorkArounds.java:101)
>              at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:108)
>              at jdk.javadoc/jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:72)
>              (...snip...)
>
> The jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager class 
> has public void addCustomTag(Taglet) method which seems perfect for my 
> need, but I found no public API for accessing this functionality.
>
> Is there a public way for a doclet to know its registered taglets, or 
> any other workaround that I may have missed? If not, would the 
> following evolution of Javadoc tools be possible?
>
>   * When extending the StandardDoclet, the doclet given in
>     Taglet.init(...) method should be the user StandardDoclet instance
>     instead than the JDK internal HtmlDoclet.
>   * Alternatively, a public API for addCustomTag(…) functionality
>     would also work.
>
> Regards,
>
>     Martin
>
>
Martin,

You are (regrettably) on the bleeding edge here with this use of the 
recent new Doclet API.

I would somewhat rephrase your first bullet, to reflect the intent of 
the API

* Whatever the doclet, the doclet given in Taglet.init(...) method 
should be the user doclet, whether specified explicitly or by default

Given that redefinition, the behavior you describe can reasonably be 
described as a bug.  This would require a minor spec change of the 
doclet parameter: "doclet - the doclet that instantiated this taglet"

It is true that there is no public API (except for option support) on 
StandardDoclet to access some of the features of the standard doclet.  
And, I don't think we should go all the way with methods to access all 
the individual features. But, there is precedent in other similar APIs 
for adding methods to provide instances of objects that might otherwise 
be created in problematic classloaders. The most notable case is the 
ability to provide instances of annotation processors to javac [1]
The problem in this case would be the specification of such a method. 
While it would be easy to write "Adds a custom tag." the order of the 
calls has a visible impact on the generated documentation that would be 
harder to specify and/or provide full control.

-- Jon

[1] 
https://docs.oracle.com/javase/9/docs/api/javax/tools/JavaCompiler.CompilationTask.html#setProcessors-java.lang.Iterable-



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180418/8f2d0118/attachment.html>