Class HiLiteMethods

  • public class HiLiteMethods
extends java.lang.Object
    HiLiteMethods - Documentation.

    The primary use of this class is that it allows a user to request that the Java-Doc assistance package hilite each and every method within an (already existing) Java-Doc HTML Class, Enumerated-Type, or Interface Page.

    NOTE: This class will only provide Method Bodies as Hilited Code, Constructors and Fields will not be hilited.

    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Static Fields: The methods in this class do not create any internal state that is maintained - however there are a few private & static fields defined. These fields are instantiated only once during the Class Loader phase (and only if this class shall be used), and serve as data 'lookup' fields (static constants). View this class' source-code in the link provided below to see internally used data.

    The two internally-defined private, static fields defined in this class include an HTMLNode[] array array which is used as the header for hilited method definitions, and a String constant identifying the chosen HiLiter Style.



    • Method Detail

      • run

        public static int run​(java.util.Vector<HTMLNode> fileVec,
                      JavaSourceCodeFile jscf,
                      JavaDocHTMLFile jdhf,
                      java.lang.String jdFileName,
                      java.lang.String srcCodeFileName,
                      HiLiter hiLiter,
                      StorageWriter sw)
        This method will hilite all Method's that are scraped from a Java Doc Generated HTML Documentation Page for a Class, Enumerated Type, or Interface. Hilited source-code for method-bodies (as String's) are inserted into the Java-Doc HTML Web-Page in the 'Method Details' section for any / all Method's found on the page.
        Parameters:
        fileVec - This is the local file-name that contains the HTML-Page JavaDoc File, stored as a vectorized-html web-page.
        jscf - This is the parsed "Source-Code-File" created by the Java-Parser Bridge. This allows the logic to retrieve the actual text-String data-definitions for the Method-bodies in a Java-Class. After identifying the correct Method, these text-String's can be transmitted to the HiLite Server and added into the Java-Doc Page.
        jdhf - This is the parsed "Java-Doc HTML Web Documentation File" which was also parsed by the Java-Parser bridge. Theoretically, it should contain identical (or nearly identical) internals (Field's, Constructor's, and Method's) to the instance of "JavaSourceCodeFile" (input parameter 'jscf') - because they are both created from the same Java class.
        jdFileName - This parameter is not needed for the purposes of loading the file here. In this method this parameter is required to make sure that if an exception is thrown, the name of the java-doc file being updated is included in exception / error messages that are potentially thrown.
        srcCodeFileName - This is the local file-name that contains the "Java Source Code File" as a '.java' text file.
        hiLiter - The Functional Interface module that performs Code Hiliting.
        sw - This parameter is a log, and if it is not null, it will print log information. If it is null, it will be ignored.
        Returns:
        This will return a count on exactly how many Method's have had their code-hilited Method-bodies inserted into the JavaDoc Documentation File for this class.
        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
         if (sw != null) sw.println("HiLiteMethods.run(...) ");

 int countNumMethodsHiLited  = 0;
 int numMethodsSkipped       = 0;

 // ********** Check whether the fileVec has any Methods in the first place  *****************
 if (Details.hasMethodDetails(fileVec) == null)
 {
     if (sw != null) sw.println( "\tJavaDoc File: " + C.BYELLOW + jdFileName + C.RESET +
                                 " does not have a Method-Details-Section, Skipping...");
     return 0; // no methods to hilite, skip this file
 }
 // ********** Check whether the fileVec has any Methods in the first place  *****************


 // ********** Iterate through every method found in the '.html' file  *****************
 HNLIInclusive   methodsIter     = Details.methodDetailsIterator(fileVec);
 boolean         firstIteration  = true;
 int             cur             = 0;

 while (methodsIter.hasNext())
 {
     // Retrieves the next method-details section defined in the HTML file using the
     // "Method Details Iterator"
     DotPair methodDP = methodsIter.nextDotPair();

     // The instance of JavaDocHTMLFile (jdhf) was built using the same '.html' file, and
     // the same iterator.  Using the 'getMethod(counter)' should retrieve the parsed
     // version of this HTML-defined java method from the javadoc documentation HTML page.
     Method fromHTMLFileMethod = jdhf.getMethod(cur++);

     // Now we need to search through all of the methods in the JavaSourceCodeFile for a
     // method with the EXACT SAME NAME AND PARAMETER LIST.
     Method  fromSrcFileMethod = (fromHTMLFileMethod   != null)
         ? jscf.findMethod(fromHTMLFileMethod)
         : null;

     // Since the instance of "Method" that is retrieved from the Source-Code '.java' file
     // is guaranteed to have the "body text" filled out (as long as their was a body
     // defined for that method, i.e. - it wasn't 'abstract') - we can get that string and
     // save it and hilite it.
     String  methodBodyStr = (fromSrcFileMethod != null)
         ? fromSrcFileMethod.body
         : null;

     // Output a tab or else it will look "lopsided"
     if (sw != null) if (firstIteration) { firstIteration = false; sw.print('\t'); }

     // If there was no method body found ... skip to the next method.
     if (methodBodyStr == null)
     {
         if (sw != null)
             sw.print("[NOT-FOUND]: " + C.BRED + fromHTMLFileMethod.name + C.RESET + "  ");

         numMethodsSkipped++;
         continue;
     }

     // PRINT OUT THE METHOD
     if (sw != null) sw.print(C.BGREEN + fromHTMLFileMethod.name + C.RESET + "  ");


     // ********** Compute the Insertion Point *****************
     // The "<DL>  <DT></DT><DD></DD>  </DL>" lists are for the throws, see-also, returns,
     // etc....  The Code HiLited Method-Body HTML needs to be inserted into its own:
     // <DT>Code:</DT>\n
     // <DD> Hi-Lited Method-Body DIV created by HiLite.ME Server</DD>
     //
     // The Insertion point shall be right before the closing </DL> HTML Element.  This
     // means HiLited Code will *always* be the last 'thing' (for lack of a technical 
     // term) that you can see in a Method-Details Section.
     //
     // ALSO: There are some methods for which no Javadoc Comments have been written, and
     //       therefore, there is no HTML "Definition List" already present in that
     //       particular method's "Method Details" Section.  In this case, an HTML
     //       <DL> ... </DL> surrounding element needs to be created.
     // ********** Compute the Insertion Point *****************

     int insertionPoint = TagNodeFind.last
         (fileVec, methodDP.start, methodDP.end, TC.ClosingTags, "dl");

     boolean needToBuildDefList  = insertionPoint == -1;

     // ********** Compute the Insertion Point *****************
     // If we need to build the <DL> (Definition List), then we will also have to find a
     // new insertion point.  The method-details section ends with a closing '</LI>' 
     // element, and then a closing '</UL>' Element.  Right before the '</LI>' is where 
     // the insertion should occur.
     // ********** Compute the Insertion Point *****************

     if (needToBuildDefList) insertionPoint = TagNodeFind.last
         (fileVec, methodDP.start, methodDP.end, TC.ClosingTags, "li");

     if (insertionPoint == -1)
         // This case should never happen, but keep it is here, just in case.
         // (Kind of the point of exceptions).  Guarantees no "Index Out of Bounds" 
         // Exceptions, and a friendly message.
     {
         if (sw != null) sw.println(
             C.BRED + "Could not determine a place to put the hilited code in the JD Page. " +
             "NOT INSERTING CODE." + C.RESET
         );

         continue;
     }

     // ********** Call the Code Hilite Server *****************
     methodBodyStr = StrIndent.chompCallableBraces(methodBodyStr);

     try
     { 
         methodsIter.insertAt(
             hiLiteMethodBody(methodBodyStr, needToBuildDefList, hiLiter),
             insertionPoint
         );
     }
     catch (IOException | HiLiteException e) {
         throw new HiLiteError(
             "Failed to HiLite Method-Body (first three lines): " +
             "[\n" + StringParse.firstNLines(methodBodyStr, 3) + "\n].\n" +
             "Currently Processing Java Source Code File: [" + srcCodeFileName + "].\n" +
             "Currently Processing JavaDoc HTML Documentation Page: [" + jdFileName + "].\n" +
             "Please see getCause() throwable for details.\n" + EXCC.toString(e),
             e
         ); }
     // ********** Call the Code Hilite Server *****************

     // Loop to the next method.
     countNumMethodsHiLited++;
 }

 if ((countNumMethodsHiLited > 0) || (numMethodsSkipped > 0)) 
     if (sw != null) sw.println();

 if (numMethodsSkipped > 0) 
     if (sw != null) sw.println(
         "\t" + C.BRED + "Skipped  " + C.RESET + 
         C.BBLUE + StringParse.zeroPad(numMethodsSkipped, 5) + C.RESET + " Methods."
     );

 if (sw != null) sw.println(
     "\tHilited  " + C.BBLUE + StringParse.zeroPad(countNumMethodsHiLited, 5) + C.RESET +
     " Methods."
 );

 return countNumMethodsHiLited;