Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8309566

Migrate away from TagletWriter and TagletWriterImpl

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Fixed
    • P4
    • 22
    • 21
    • tools

    Description

      TagletWriter and TagletWriterImpl do not provide a useful layer of abstraction, and moreover, seem to provide an unnecessary "choke point" when working on taglets.

      This is to suggest a possible way forward:

      TagletWriter (mostly) contains taglet-specific methods, to generate the output for a tag. These methods could be converted to an abstract method on the corresponding taglet class, and the corresponding implementation from TagletWriterImpl moved to a new HTML subtype of the taglet class.

      TagletManager (in the standard doclet) would be updated to know about the subtypes.

      To ease the transition, if taglet-specific methods in TagletWriterImpl use shared methods, we could provide delegating methods in Taglet (which might need to be converted from an interface to an abstract class; but note the presence and use of BaseTaglet). This ought to allow code to be literally cut-and-pasted from TagletWriterImpl to corresponding `Html*Taglet` classes.

      Once we have moved the tag-specific methods into corresponding taglet classes, we can look at addressing any remaining shared methods, either inlining the delegating methods in Taglet or looking for other alternatives.

      Also to be considered: what happens to the existing use of `TagletWriter` as a parameter to Taglet `getInlineTagOutput` and `getAllBlockTagOutput`. It might need to be replaced by an equivalent to `TagletWriterImpl.Context`, promoted up to be a toolkit class.
      Maybe `TagletWriterImpl.Context moves to `Taglet.Context`, which would be in keeping with the general trend of this work ... moving `TagletWriter` "stuff" to `Taglet` and its subtypes.

      Also to be considered: TagletWriterImpl caches a lot of useful values, that might need to be made available to various taglets.

          private final HtmlDocletWriter htmlWriter;
          private final HtmlConfiguration configuration;
          private final HtmlOptions options;
          private final Utils utils;
          private final Resources resources;
          private final Messages messages;
          private final Contents contents;
          private final Context context;

      Many/most of these can be derived from `HtmlDocletWriter` and/or `Configuration`. `Configuration` could be passed in to `BaseTaglet`, but `HtmlDocletWriter` is per-page and is HTML only (so cannot appear in Taglet method signatures.). One likely possibility is to put it in an HTML subtype of the Context object.

      Attachments

        Issue Links

          Activity

            People

              jjg Jonathan Gibbons
              jjg Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: