Class EmbedTag


  • public class EmbedTag
    extends java.lang.Object
    JavaDoc EmbedTag - Documentation.

    This class is capable of finding and replacing specified HTML "EMBED" Elements (<EMBED>) and replacing them with externally-located HTML pages. It does this by requiring that the tag have a class='external-html' attribute and also an inner-tag that specifies an ID for that piece of HTML. This is in the form of DATA-FILE-ID='SOME-ID-TOKEN'. When the Upgrader finds an HTML Embed element in the page whose class is external-html, it will search for this 'Data-File-ID' attribute in the element, and then use a user-provided lookup-table, or lambda function, to insert that HTML into the class.

    VALUE ADDED: This can allow programmers to type longer descriptions - particularly for elements such as the top-level class descriptions - in separate files from their source-code, if they so chose. A separate directory for longer HTML explanations for a class functionality or description can contain '.html' files that may automatically imported into their javadoc's using the HTML Embed Element and this tool.

    Hopefully, this simple example of how to insert an HTML 'EMBED' Element into a Java-Doc Documentation Comment Page will make it easier to add External HTML Files directly into code documentation. Please notice the 'Attribute' in the example named 'DATA-FILE-ID'. This is a token that must be defined in the Embed Tags Definitions This definitions list is simply a list of Tokens and HTML FileNames - separated by white-space, one-per-line that has been passed or registered with the Upgrader. See the Upgrader's method setEmbedTagsMap(...) for more details.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    /**
     * The purpose of this method is to save every person on earth.  Please see the descriptive table included below:
     * 
     * <EMBED class='external-html' DATA-FILE-ID='IDTOKEN'>
     *
     * @returns An explanation of steps that have already been taken to save the world
     * @throws SleepingInException If the alarm clock does not go off, this exception will throw.
     */
    public static String saveTheWorld()
    {
        ...
    }
    



    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static int run​(Vector<HTMLNode> javaDocHTMLCIETPage, String fileName, Hashtable<String,​String> ids, StorageWriter sw)
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • run

        public static int run​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage,
                     java.lang.String fileName,
                     java.util.Hashtable<java.lang.String,​java.lang.String> ids,
                     StorageWriter sw)
        
        This method will load external HTML into a JavaDoc HTML Page
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        fileName - This parameter is the name of the file being upgraded.

        NOTE: This parameter is required solely for error reporting purposes. It may be null, but if it were, and a JavaDocError were thrown, then it would read 'FileName: null' in the error message.
        ids - This is a map from tags in the Embed-Tag's 'DATA-FILE-ID' attribute to HTML files on the file-system. This must be provided in order to find the HTML file that needs to be inserted in each Embed Tag in the JavaDoc File.
        sw - This is the log. This parameter may be null, and if it is it will be ignored.
        Returns:
        This will return a count on exactly how many HTML Embed Elements were identified and replaced.
        Code:
        Exact Method Body:
          1
          2
          3
          4
          5
          6
          7
          8
          9
         10
         11
         12
         13
         14
         15
         16
         17
         18
         19
         20
         21
         22
         23
         24
         25
         26
         27
         28
         29
         30
         31
         32
         33
         34
         35
         36
         37
         38
         39
         40
         41
         42
         43
         44
         45
         46
         47
         48
         49
         50
         51
         52
         53
         54
         55
         56
         57
         58
         59
         60
         61
         62
         63
         64
         65
         66
         67
         68
         69
         70
         71
         72
         73
         74
         75
         76
         77
         78
         79
         80
         81
         82
         83
         84
         85
         86
         87
         88
         89
         90
         91
         92
         93
         94
         95
         96
         97
         98
         99
        100
        101
        102
        103
        104
        105
        106
        107
        108
        109
        110
        111
        112
        113
        114
        115
        116
        117
        118
        119
        120
        121
        122
        123
        124
        125
        126
        127
        128
        129
        130
        131
        132
        133
        134
        135
        136
        137
        138
        139
        140
        141
        142
        143
        144
        145
        146
        147
        148
        149
        150
        151
        152
        153
        154
        155
        156
        157
         if (sw != null) sw.println("EmbedTag.run(...)");
        
         if (! initialized) init();
        
         RECORD rec = new RECORD();
         rec.fileName            = fileName; // File Name of the '.java' file for this CIET Page.
         rec.sw                  = sw;       // The Log that was passed to this method.
         rec.ids                 = ids;      // The Embed-Tag-to-FileName Map passed to this method.
         rec.alreadyLoadedIDs    = new TreeMap<>();
             // Whenever an HTML File is loaded for a page, the HTML is saved in this TreeMap, so it
             // is not retrieved *MORE THAN ONCE PER FILE*.
             // NOTE: This 'alreadyLoadedIDs' cannot be saved and passed around because it isn't
             //       really feasible to save *ALL* the HTML Files that are loaded (it would be too
             //       much!).  Instead, they 'external-HTML' snippets are loaded only once per class.
        
         // This will keep a count of the number of Embed Tag's that have been replaced for
         // a given class file.  This number is returned - and printed by the main loop.
         int embedTagsReplaced = 0;
        
         // Temporary Variable
         Vector<HTMLNode> v;
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Top Description - Get any potential Global Definitions - *AND* replace any Embed-Tags.
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // This is, as it says, the "Upper Description Area" of any Java Doc Generated HTML Page.
         // In an upgraded page, it is the area in yellow with a class, interface or enumerated-type
         // description.  It is here where a user may (if needed) define global-parameters for the
         // Embed Tags Processor (a.k.a. this class)
         DotPair topDescription =
             TopDescription.descriptionAtTop(javaDocHTMLCIETPage);
        
         // All "Global Embed Tag Parameter Definitions" look like:
         // <EMBED CLASS=globalDefs DATA-PARAMNAME=PARAMVALUE>
         Vector<TagNode> globalDefTNs =
             InnerTagPoll.all(
                 javaDocHTMLCIETPage, topDescription.start, topDescription.end,
                 "embed", "class", TextComparitor.C, "globalDefs"
             );
        
         /*
         if (fileName.equals("javadoc/Torello/Java/Function/IntByteConsumer.html"))
         {
             sw.println
                 ("Top Description: " + Util.rangeToString(javaDocHTMLCIETPage, topDescription));
             sw.println(
                 "globalDefTNs.size(): " + globalDefTNs.size() + "\n" +
                 "globalDefTNs: " + StrCSV.toCSV(globalDefTNs, tn-> (tn.str+"\n"), true, null)
             );
         }
         */
        
         // Parse all of the EMBED tag's into variables table
         rec.sectionDetailsName  = "Top Description";
         rec.globals             = (globalDefTNs.size() > 0) ? parseDefs(globalDefTNs, rec) : null;
        
         v = Util.cloneRange(javaDocHTMLCIETPage, topDescription);
         embedTagsReplaced = replaceEmbedTags(v, rec, "Top Description");
        
         if (embedTagsReplaced > 0)
             Util.replaceRange(javaDocHTMLCIETPage, topDescription, v);
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Methods, Constructors, Fields and Enumerated-Constants
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         int             replaced;
         HNLIInclusive   iter;
        
         /*
             ***NOTE: This hasn't even come up.  The parameter lists have evaluations inside them
                      below.  This is how that works.
        
             // 15.7.4. Argument Lists are Evaluated Left-to-Right
             public static void main(String[] args)
             { String s = "going, ";   print3(s, s, s = "gone"); }
        
             static void print3(String a, String b, String c)
             { System.out.println(a + b + c); }
        
             // PRINTS: going, going, gone
         */
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Method Details
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         rec.sectionDetailsName = "Method Details";
         if (Details.hasMethodDetails(javaDocHTMLCIETPage) != null)
         {
             iter = Details.methodDetailsIterator(javaDocHTMLCIETPage);
             while (iter.hasNext())
             {
                 replaced = replaceEmbedTags
                     (v=iter.next(), rec, Util.textNodesString(v, DetailsPartMethod.name(v)));
                 if (replaced > 0)
                     { iter.set(v);  embedTagsReplaced += replaced; }
             }
         }
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Field Details
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         rec.sectionDetailsName = "Field Details";
         if (Details.hasFieldDetails(javaDocHTMLCIETPage) != null)
         {
             iter = Details.fieldDetailsIterator(javaDocHTMLCIETPage);
             while (iter.hasNext())
             {
                 replaced = replaceEmbedTags
                     (v=iter.next(), rec, Util.textNodesString(v, DetailsPartField.name(v)));
        
                 if (replaced > 0)
                     { iter.set(v);  embedTagsReplaced += replaced; }
             }
         }
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Constructor Details
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         rec.sectionDetailsName = "Constructor Details";
         if (Details.hasConstructorDetails(javaDocHTMLCIETPage) != null)
         {
             iter = Details.constructorDetailsIterator(javaDocHTMLCIETPage);
             while (iter.hasNext())
             {
                 replaced = replaceEmbedTags
                     (v=iter.next(), rec, Util.textNodesString(v, DetailsPartConstructor.name(v)));
        
                 if (replaced > 0)
                     { iter.set(v);  embedTagsReplaced += replaced; }
             }
         }
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Enumerated Constant Details
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         rec.sectionDetailsName = "Enumerated Constant Details";
         if (Details.hasEnumConstDetails(javaDocHTMLCIETPage) != null)
         {
             iter = Details.enumConstDetailsIterator(javaDocHTMLCIETPage);
             while (iter.hasNext())
             {
                 replaced = replaceEmbedTags
                     (v=iter.next(), rec, Util.textNodesString(v, DetailsPartEnumConst.name(v)));
        
                 if (replaced > 0)
                     { iter.set(v);  embedTagsReplaced += replaced; }
             }
         }
        
         if (sw != null) sw.println(
             "\tReplaced " + C.BBLUE + StringParse.zeroPad(embedTagsReplaced, 5) + C.RESET +
             " total <EMBED ...> tag(s)."
         );
        
         return embedTagsReplaced;