Class HiLiteFields

  • public class HiLiteFields
extends java.lang.Object
    HiLiteFields - 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 field within an (already existing) Java-Doc HTML Class, Enumerated-Type, or Interface Page.

    NOTE: This class will only provide Field Declarations as Hilited Code, Constructors and Methods 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 public, static fields defined in this class include an HTMLNode[] array which is used as the header for hilited field 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 Field's that are scraped from a Java Doc Generated HTML Documentation Page for a Class, Enumerated Type, or Interface. The hilited source-code is inserted into the Java-Doc HTML Web-Page in the 'Field Details' section for any / all Field's found on the page.
        Parameters:
        fileVec - This is the local file 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 Field's in a Java-Class. After identifying the correct Field, 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 Field's have had their code-hilited declarations 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("HiLiteFields.run(...) ");

 int countNumFieldsHiLited   = 0;
 int numFieldsSkipped        = 0;

 // ********** Check whether the fileVec has any Fields in the first place  *****************
 if (Details.hasFieldDetails(fileVec) == null)
 {
     if (sw != null) sw.println( "\tJavaDoc File: " + C.BYELLOW + jdFileName + C.RESET +
                                 " does not have a Field-Details-Section, Skipping..."   );
     return 0; // No Fields, Skip this file
 }
 // ********** Check whether the fileVec has any Fields in the first place  *****************


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

 while (fieldsIter.hasNext())
 {
     // Retrieves the next field-details section defined in the HTML file using the
     // "Field Details Iterator"
     DotPair fieldDP = fieldsIter.nextDotPair();

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

     // Now we need to search through all of the fields in the JavaSourceCodeFile for a
     // field with the EXACT SAME NAME.
     Field fromSrcFileField = (fromHTMLFileField != null) 
         ? jscf.findField(fromHTMLFileField)
         : null;

     // Since the instance of "Field" that is retrieved from the Source-Code '.java' file
     // is guaranteed to have the "declaration" (as a String) - we can get that string and
     // save it and hilite it.
     String fieldDeclStr = (fromSrcFileField != null)
         ? fromSrcFileField.signature
         : null;

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

     // If there was no field-definition string found ... skip to the next method.
     if (fieldDeclStr == null) 
     {
         if (sw != null) sw.print
             ("[NOT-FOUND]: " + C.BRED + fromHTMLFileField.name + C.RESET + "  ");
         numFieldsSkipped++;
         continue;
     }

     // PRINT OUT THE FIELD
     if (sw != null) sw.print(C.BGREEN + fromHTMLFileField.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 Field-Definition HTML needs to be inserted into its own:
     // <DT>Code:</DT>\n
     // <DD> Hi-Lited Field-Declaration 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 Field-Details Section.
     //
     // ALSO: There are some fields for which no Javadoc Comments have been written, and
     // therefore, there is no
     //       HTML "Definition List" already present in that particular field's "Field Details"
     //       Section. In this case, an HTML <DL> ... </DL> surrounding element needs to be
     //       created.
     // ********** Compute the Insertion Point *****************

     int insertionPoint = TagNodeFind.last
         (fileVec, fieldDP.start, fieldDP.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 field-details section ends with a closing '</LI>' element, and
     // then a closing '</UL>' Element right before the '</LI>' is where the insertion should
     // occur.
     // NOTE: Most of the time, for fields (different from methods), a <DL> ... </DL> will
     // need to be built.
     // ********** Compute the Insertion Point *****************

     if (needToBuildDefList) insertionPoint = TagNodeFind.last
         (fileVec, fieldDP.start, fieldDP.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 ***************
     // ********************************************************
     try
     {
         fieldsIter.insertAt(hiLiteFieldDeclaration
             (fieldDeclStr, needToBuildDefList, hiLiter), insertionPoint);
     }
     catch (IOException | HiLiteException e)
     {
         throw new HiLiteError(
             "Failed to HiLite Field-Declaration (first three lines): [\n" + 
             StringParse.firstNLines(fieldDeclStr, 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.
     countNumFieldsHiLited++;
 }

 if ((countNumFieldsHiLited > 0) || (numFieldsSkipped > 0))
     if (sw != null) sw.println();

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

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

 return countNumFieldsHiLited;