Class HELPER


  • public class HELPER
    extends java.lang.Object
    Utility class



    • Method Detail

      • getSpanSection

        protected static DotPair getSpanSection​
                    (java.util.Vector<HTMLNode> javaDocConstructorHTML,
                     java.lang.String sectionSpanClassName)
        
        This finds a the requested subsection identified by sectionSpanClassName.

        This method is used in all of the classes named 'DetailsPart'
        Parameters:
        javaDocConstructorHTML - This should be the HTML sub-section of a JavaDoc page that describes the functionality of a single constructor in a java class. It can be retrieved by a call to HNLIIterator.next().
        sectionSpanClassName - This is the name of the sub-section we are looking for. Valid values are limited to 'throwsLabel,' 'returnLabel' and also 'paramLabel.' These are three sections inside of an HTML method description from a Java-Doc generated HTML page.
        Returns:
        The pointers to the starting and ending index of the relevant section, or null if it were not found.
        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
         DetailsException.check(javaDocConstructorHTML);
        
         // There is a surrounding "<DL>" element around the entire @returns, @see, @param, and
         // @throws section
         DotPair dlDP = TagNodeFindInclusive.first(javaDocConstructorHTML, "dl");
        
         // If this was null, just return null, perhaps one day, this might ought to be an
         // exception throw.
         if (dlDP == null) return null;
        
         // The @see, @param, @throws, @returns, etc... starts with a <SPAN CLASS="seeLabel">
         // ... (or throwsLabel, returnLabel, paramLabel...)
         int spanPos = InnerTagFind.first(
             javaDocConstructorHTML, dlDP.start, dlDP.end, "span", "class",
             TextComparitor.C, sectionSpanClassName
         );
        
         // If not found, return null;
         if (spanPos == -1) return null;
        
         // The particular section we are observing ends as soon as another section begins, or we
         // encounter a </DL> element.  a <DT> element implies a new section is starting.
        
         int dlPos = TagNodeFind.first(javaDocConstructorHTML, spanPos, -1, TC.ClosingTags, "dl");
         int dtPos = TagNodeFind.first(javaDocConstructorHTML, spanPos, -1, TC.OpeningTags, "dt");
        
         // 3 out of 4 times, a "new section begin" is how the previous section ends.  However, if
         // the section being observed is the last section, then a </DL> element will be found, and
         // the <DT> search will have returned a value of '-1'.  Since Math.min() is being, used,
         // the '-1' must be changed.
        
         if (dtPos == -1) dtPos = javaDocConstructorHTML.size();
             // Set to maximum size, if not found.
        
         // Whichever comes first... </DL> or another <DT>
         int ePos = Math.min(dlPos, dtPos) - 1;
        
         // Back up through any TextNodes - which are usually just a '\n' newline character.
         while (! (javaDocConstructorHTML.elementAt(ePos) instanceof TagNode)) ePos--;
        
         // NOTE: The element before the span-pos is the <DT> element.
         DotPair ret = new DotPair(spanPos - 1, ePos);
        
         HTMLNode start = javaDocConstructorHTML.elementAt(ret.start);
         HTMLNode end = javaDocConstructorHTML.elementAt(ret.end);
        
         if (    (! (start instanceof TagNode))
             ||  (! ((TagNode) start).tok.equals("dt"))
             ||  ((TagNode) start).isClosing
         )
             throw new JavaDocError(
                 "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                 "First node was not a <DT> Element: [" + start.getClass().getSimpleName() + ": " +
                 start.str + "]"
             );
        
         if (    (! (end instanceof TagNode))
             ||  (! ((TagNode) end).tok.equals("dd"))
             ||  (! ((TagNode) end).isClosing)
         )
             throw new JavaDocError(
                 "Something went wrong.  Not able to return a proper " + sectionSpanClassName + ".  " +
                 "Last node was not a </DD> Element: [" + end.getClass().getSimpleName() + ": " +
                 end.str + "]"
             );
        
         return ret;
        
      • leadingTabs

        public static void leadingTabs​(java.lang.String sourceCodeDirectory,
                                       int numSpacesPerTab,
                                       StorageWriter sw)
        This method calls the tabsToSpace method for every '.java' source-code file found inside the directory specified by parameter String 'sourceCodeDirectory'.

        This method is a legacy-feature that used to automate the sometimes laborious process of making tabs in a source-code file align properly.

        #TABSAREEVIL
        Parameters:
        sourceCodeDirectory - This is the root-directory of a source-code directory tree for java source code files.
        numSpacesPerTab - This identifies the number of spaces a char '\t' is supposed to represent in any source-code editor's settings. In Google Cloud Server, the default value is '4' spaces.
        sw - This parameter is allowed to be null, but if it is not, then logging information shall be printed here.
        See Also:
        FileNode, FileNode.createRoot(java.lang.String)
        Code:
        Exact Method Body:
        1
        2
        3
         FileNode.createRoot(sourceCodeDirectory).loadTree().flatten().stream()
                 .filter((FileNode fn) -> fn.name.endsWith(".java"))
                 .forEach((FileNode fn) -> tabsToSpace(fn.getFullPathName(), numSpacesPerTab, sw));
        
      • tabsToSpace

        public static void tabsToSpace​(java.lang.String fileName,
                                       int numSpacesPerTab,
                                       StorageWriter sw)
        This will replaced leading tabs for each line of text in a source code file with a specified number of spaces. If tabs are supposed to represent 4 spaces, then if a line in a source-code file had three leading tab-characters, then those three leading char '\t' would be replaced with 12 leading space characters ' '.

        This method is a legacy-feature that used to automate the sometimes laborious process of making tabs in a source-code file align properly.
        Parameters:
        fileName - This file-name should represent a java source-code file. It could be any file, in all actuality, however whatever this string-parameter points to, it shall be loaded into memory, and each line of the file that begins with tab-spaces (the '\t' character) will have those tabs replaced with the precise number of spaces as specified by the int 'numSpacesPerTab' parameter.
        numSpacesPerTab - This identifies the number of spaces a char '\t' is supposed to represent in any source-code editor's settings. In Google Cloud Server, the default value is '4' spaces.
        sw - This parameter is allowed to be null, but if it is not, then logging information shall be printed here.
        See Also:
        FileRW.writeFile(CharSequence, String)
        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
         String spaces = "";
         while (numSpacesPerTab-- > 0) spaces += " ";
        
         try {
             if (sw != null) sw.println("Loading file: " + fileName);
        
             Vector<String> f = FileRW.loadFileToVector(fileName, false);
        
             for (int i=0; i < f.size(); i++)
             {
                 String  line    = f.elementAt(i);
                 int     numTabs = 0;
        
                 while (line.startsWith("\t"))   { numTabs++; line = line.substring(1); }
                 while (numTabs-- > 0)           line = spaces + line;
        
                 f.setElementAt(line, i);
             }
             FileRW.writeFile(f, fileName);
         } 
         catch (IOException e)
         {
             if (sw != null) sw.println(
                 "Tab-conversion for file: " + fileName + " FAILED due to an java.io.IOException. " +
                 "Skipping."
             );
         }
        
      • readMapFile

        public static java.util.Hashtable<java.lang.String,​java.lang.String> readMapFile​
                    (java.lang.String tagIDMapFileName)
        
        This parses the '<EMBED>' tag map file.
        Parameters:
        tagIDMapFileName - The name of the text file mapping Tag ID's to File Names.
        Returns:
        An <EMBED>-tag map-file. This is used to initialize the upgrader's internal Upgrade.embedTagIDTable. This result may be passed to the method Upgrade.setEmbedTagsMap(Map).
        Throws:
        UpgradeException - If there are problems accessing the 'tagIDMapFileName' or if the file contains erroneous map entries.
        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
         UpgradeException.checkFileExistsAndCanAccess(
             tagIDMapFileName,
             "HTML <EMBED CLASS='external-html' DATA-FILE-ID='tag'> file-list"
         );
        
         Hashtable<String, String> ret = new Hashtable<>();
        
         Stream<String[]> entriesStream;
         try {
             entriesStream = FileRW.loadFileToVector(tagIDMapFileName, false)
                 .stream()
                 .map    ((String tagHTMLFilePair) -> tagHTMLFilePair.trim())
                 .filter ((String tagHTMLFilePair) -> tagHTMLFilePair.length() > 0)
                 .map    ((String tagHTMLFilePair) -> tagHTMLFilePair.split(StringParse.WHITE_SPACE_REGEX.toString()));
         }
         catch (Exception ex)
         {
             throw new UpgradeException(
                 "Loading the Embed-ID-Tag / HTML-File-Name List-File encountered an error.\n" +
                 "File: [" + tagIDMapFileName + "] did not load properly.\n" +
                 "Please see getCause() cause chain exception for more details.", ex
             );
         }
        
         entriesStream.forEach((String[] entryTagIDFileNamePair) ->
         {
             // This is used for error-reporting.  Likely this is never used.
             StringBuilder tempStrBuffer = new StringBuilder();
             for (String s : entryTagIDFileNamePair) tempStrBuffer.append(s + " ");
             String tempStr = tempStrBuffer.toString();
        
             if (entryTagIDFileNamePair.length != 2)
             {
                 throw new UpgradeException(
                     "There is an entry in this file: [" + tagIDMapFileName + "]\n" +
                     "That contains an invalid entry-line: [" + tempStr + "]\n" +
                     "The String Tokenizer found [" + entryTagIDFileNamePair.length + "] tokens, " +
                     "but it expected to find EXACTLY 2.\n" +
                     "NOTE: Tokens are non-white-space characters separated by white-space.\n" +
                     "Does your filename have spaces?  Change file-names!"
                 );
             }
        
             String  id          = entryTagIDFileNamePair[0].trim();
             String  fileName    = entryTagIDFileNamePair[1].trim();
        
             if ((id.length() == 0) || (fileName.length() == 0)) throw new UpgradeException(
                 "While loading the Embed-ID-Tag / HTML-File-Name List-File, one of the entries " +
                 "found turned out to be invalid.\n" +
                 "Embed-ID-Tag & File-Name Pair-Entry: [" + tempStr + "] cannot be parsed."
             );
        
             UpgradeException.checkFileExistsAndCanAccess
                 (fileName, "External HTML Documentation File to Insert");
        
             if (ret.containsKey(id)) throw new UpgradeException(
                 "There already exists a copy of the ID: [" + id + "], in the Embed-Tag ID-File " +
                 "Map Table.\n" +
                 "It is currently mapped to file: [" + ret.get(id) + "]\n" +
                 "A second copy of an ID cannot be added, please pick a new ID for file:\n" +
                 "[" + fileName + "]"
             );
        
             ret.put(id, fileName);
         });
         return ret;
        
      • getFullNameAndSourceFileName

        public static Ret2<java.lang.String,​java.lang.String> getFullNameAndSourceFileName​
                    (java.util.Vector<HTMLNode> v)
        
        Compute the name of the class, interface or enumerated-type - including the full package name. This method will not include any "Generics" information in the class-name.
        Parameters:
        v - The vectorized-HTML Java-Doc Generated Web-Page for any class, interface or enumerated-type
        Returns:
        An instance of Ret2<String, String> as follows:

        • ret2.a (String)

          This field shall contain the full-class name - with package information included, but without generic-type information - as a String.

        • ret2.b (String)

          This field will contain the computed file-name of the '.java' Source-Code File from which this object would have been built. Usually this is the same location as the class-name, however for static-inner classes, the "Containing Class" is stripped out and returned.
        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
         String titleStr     = TopDescription.titleAsString(v);
         String packageStr   = TopDescription.packageInfoAsString(v).trim().replace(("" + ((char) 160)), " ");
        
         /* Newer javadoc inserts the word 'Package' */
         if (StrCmpr.startsWithIgnoreCase(packageStr, "package ")) 
             packageStr = packageStr.substring("package ".length());
        
         String packageFStr  = packageStr.replace(".", File.separator) + File.separator;
        
         for (String s : sArr)
             if (titleStr.startsWith(s + ' '))
             { titleStr = titleStr.substring(s.length() + 1).trim(); break; }
        
                
         while (titleStr.matches(".*?<.*>.*?")) titleStr = titleStr.replaceFirst("<.*?>", "");
         // { System.out.println("MATCHING IT******"); titleStr = titleStr.replaceFirst("<.*?>", ""); }
        
         int pos;
         if ((pos = titleStr.indexOf(".")) != -1) 
             return new Ret2<String, String>(packageStr + '.' + titleStr, packageFStr + titleStr.substring(0, pos) + ".java");
         else
             return new Ret2<String, String>(packageStr + '.' + titleStr, packageFStr + titleStr + ".java");