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()
    {
        ...
    }
    




Stateless Class: This class neither contains any program-state, nor can it be instantiated.
The @StaticFunctional Annotation may also be called 'The Spaghetti Report'
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 5 Method(s), 5 declared static
  • 4 Field(s), 4 declared static, 4 declared final


    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static int run​(CommonParamRecord pr)
      • 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​(CommonParamRecord pr)
        This method will load external HTML into a JavaDoc HTML Page
        Parameters:
        pr - This contains all of the needed parameters for this method, encapsulated into a single record-class. The list is somewhat lengthy, so this makes the code "look cleaner"
        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 (pr.sw != null) pr.sw.print("EmbedTag.run(...)\n\tReplacing: ");
        
         RECORD rec = new RECORD();
         rec.fileName            = pr.srcCodeFileName;   // File Name of the '.java' file.
         rec.packageName         = pr.jscf.packageName;  // Package for this '.java' file.
         rec.sw                  = pr.sw;                // The Log that was passed here.
         rec.stats               = pr.stats;             // The upgrade-build 'Statistics' class
         rec.ids                 = pr.embedTagIDTable;   // The Embed-Tag-to-FileName Map passed.
         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(pr.fileVec);
        
         // All "Global Embed Tag Parameter Definitions" look like:
         // <EMBED CLASS=globalDefs DATA-PARAMNAME=PARAMVALUE>
         Vector<TagNode> globalDefTNs =
             InnerTagPoll.all(
                 pr.fileVec, topDescription.start, topDescription.end,
                 "embed", "class", TextComparitor.C, "globalDefs"
             );
        
         /*
         if (fileName.equals("javadoc/Torello/Java/Function/IntByteConsumer.html"))
         {
             pr.sw.println
                 ("Top Description: " + Util.rangeToString(pr.fileVec, topDescription));
             pr.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(pr.fileVec, topDescription);
         embedTagsReplaced = replaceEmbedTags(v, rec, "Top Description");
        
         if (embedTagsReplaced > 0)
             Util.replaceRange(pr.fileVec, topDescription, v);
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Methods, Constructors, Fields and Enumerated-Constants
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         int             replaced;
         HNLIInclusive   iter;
        
         /*
             ***NOTE: This hasn't even come up, until now.  The parameter lists have evaluations
                     inside them below.  This is how that works.  (Code was copied from oracle.com)
        
             // 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(pr.fileVec) != null)
         {
             iter = Details.methodDetailsIterator(pr.fileVec);
             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(pr.fileVec) != null)
         {
             iter = Details.fieldDetailsIterator(pr.fileVec);
             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(pr.fileVec) != null)
         {
             iter = Details.constructorDetailsIterator(pr.fileVec);
             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(pr.fileVec) != null)
         {
             iter = Details.enumConstDetailsIterator(pr.fileVec);
             while (iter.hasNext())
             {
                 replaced = replaceEmbedTags
                     (v=iter.next(), rec, Util.textNodesString(v, DetailsPartEnumConst.name(v)));
        
                 if (replaced > 0)
                     { iter.set(v);  embedTagsReplaced += replaced; }
             }
         }
        
         if (pr.sw != null) pr.sw.println(
             "\n\tReplaced " + C.BBLUE + StringParse.zeroPad(embedTagsReplaced, 5) + C.RESET +
             " total <EMBED ...> tag(s)."
         );
        
         return embedTagsReplaced;