Bug ID: JDK-4654308 Modify Taglet API for standalone tags to handle inline tags taglets.jar, etc.

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 1.4.0

Priority: P4
Status: Resolved
Resolution: Fixed
OS: generic
CPU: generic

Submitted: 2002-03-18
Updated: 2017-05-16
Resolved: 2003-09-26

Other
5.0 tigerFixed

The Taglet class is fine for simple tags, but has limitations.

- Extend the Taglet API to enable standalone tags to handline inline tags
  (both standard and custom) in their arguments.  This requires access
  to HtmlStandardWriter and Doc.  This is currently done
  by extending AbstractExecutableMemberTaglet

- Extend the Taglet API to enable access to HtmlStandardWriter.
  This is currently done by extending AbstractInlineTag

- Extend the Taglet API to enables multiple taglets to be 
  put in a single jar file (taglets.jar) and loaded with a single option.
  A suggestion for this can be found under Suggested Fix.

Name: dk30142			Date: 06/29/2002


A major goal is that a third party developer should be able to reimplement a standard 
tag with *all* of its standard functionality, including supporting inline tags.
All of this should depend only on the new internal API (SPI) resulting from the refactoring
work.  That is, taglets should not break in the future if we later reimplement the
standard doclet.
======================================================================

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger FIXED IN: tiger INTEGRATED IN: tiger tiger-b22
14-06-2004
SUGGESTED FIX I think I've got a nice solution for you. At least it worked for me. I packed all the taglets into a single jar and added a main registration class like this: public class TagRegr implements Taglet { // ... public static void register(Map tagletMap) { Taglet[] taglet = new Taglet[N_TAGLETS]; taglet[0] = new FirstTaglet(); //.. taglet[N_TAGLETS-1] = new LastTaglet(); int i; for(i=0; i<taglet.length; ++i){ Taglet t = (Taglet) tagletMap.get(taglet<i>.getName()); if (t != null) { tagletMap.remove(taglet<i>.getName()); } tagletMap.put(taglet<i>.getName(), taglet<i>); } } \\... } So I can write a command line like: javacod -taglet TagReg -tagletpath AllTaglets.jar ... Perhaps the big array is not so nice, but it works. Marco. (from Javadoc Forum, subject: Packaging taglets)
11-06-2004
PUBLIC COMMENTS This has been fixed but is in an internal package. It is not a supported API. ###@###.### 2003-09-16
16-09-2003
EVALUATION Requires submitting a JSR ###@###.### 2002-03-18 I think that designing the Taglet interface was a good idea but I think we should have a special interface that is just for standard doclet taglets. Taglets that extend this interface should have access to the HtmlStandardWriter and the Doc object that holds the tag. We should put this API in its own package. ###@###.### (by ###@###.###) 2002-03-18 Name: dk30142 Date: 06/29/2002 Also see 4654636 "Taglet does not allow use of inline tags" ###@###.### 2002-06-29 We have been cleared by the Tiger planning committee to pursue this feature. ###@###.### 2002-08-09 Concerning the taglet jar feature, ###@###.### wrote: > The method mentioned in the "suggested fix" works for the user because he > knows the names of his tags and hard codes them in the register method. > It does not work for us because all we have is a JAR file. We would have > to iterate through the classes in the JAR file and then register them one > by one. That would be a useful feature for users who have a lot of > taglets and don't want to register them one by one. To identify this > JAR file that only contains taglets, maybe we can give it a special name > like taglets.jar. We can't just load classes from any JAR file because > there is nothing stopping users from putting tools.jar in > the taglet path. We wouldn't want to iterate through that. ###@###.### replied: I wouldn't want to restrict this to only one jar file. Then people couldn't build libraries of taglets or share them as easily. Why would someone put tools.jar in taglet path? It's documented that -tagletpath is for taglets. It seems reasonable to me to expect that a jar file in -tagletpath should contain only taglets. Or might someone create taglets that depend on other non-taglet classes, and want to jar them all up in a single jar file? When you iterate through the classes, you can tell which are taglets and which are not, can't you? If you can, this would also seem reasonable to allow non-taglet classes. jamie's reply: >Why would someone put tools.jar in taglet path? I don't think anyone would do this but I am just worried that the doclet will run slowly because it will have to iterate through a large JAR. > It seems reasonable to me to expect that a jar file > in -tagletpath should contain only taglets. If we can assume this, I guess there is nothing to worry about. > Or might someone create taglets that depend on > other non-taglet classes, and want to jar them all > up in a single jar file? When you iterate through > the classes, you can tell which are taglets and which > are not, can't you? I can tell which classes are taglets in the JAR. I guess that will be our proposal then. Iterate through all the classes and register that ones that implement a Taglet interface (old or new). ###@###.### 2003-07-19 First a comment about registering multiple taglets in one register call. I've actually done something like this myself, but I noticed that it seems to bypass a bit of sanity checking that the standard doclet does for you. After each call to "register" the doclet looks at the single taglet most recently registered, and does some processing on its name. If several taglets are registered at once, only the final one gets processed. It would be possible for the tagletMap implementation to be smarter and handle this correctly. While I'm on the subject, the tagletMap implementation could also be smart enough not to require you to unregister an existing taglet before registering a replacement. But forget all this talk about improving the register method. I really like the idea of doing away with taglet registration altogether. It seems entirely reasonable that Some Big Project with its own taglets will come all packaged up in SomeBigProject.jar, which would then serve for both the classpath and the tagletpath. So there certainly would need to be a way to locate the taglets within the classpath. Enumerating all classes and looking for taglets may be fine. If that's not desired -- either due to efficiency or because you lose some flexibility in choosing your taglets -- there's a solution to exactly this problem used in lots of places in the JDK and elsewhere: take a look at sun.misc.Service. You create a file in the jar's META-INF/services directory that lists all the taglets in that jar. (Note that although the implementation is in a sun.* package, there's nothing Sun-private about the mechanism itself.) ###@###.### 2003-07-19 Fixed but not a supported API. ###@###.### 2003-09-16
19-07-2003