Class TreeUtils

  • public class TreeUtils
extends java.lang.Object
    This is a helpful interface to retrieve and extract the utilities provided by the Java-Compiler interface provided by the JDK. This class utilizes the Tree-Classes defined in the Java Package com.sun.source.tree.* (and also com.sun.source.util.*. These AST (Tree's) work and function as an alternative to the JavaParser AST Generator.


    • Constructor Summary

      Constructors 
      Constructor Description
      TreeUtils​(String srcFileName, String srcFileAsStr)
      Constructs an instance of this class.

    • Method Summary

       
      Retrieve Java-Doc Comment Parse-Tree's & Information
      Modifier and Type Method
      DocCommentTree getJavaDocCommentTree​(Tree tree)
      Ret3<Integer,
           ​Integer,
           ​DocCommentTree>      		 getJavaDocInfoLine​(Tree tree)
      Ret3<Integer,
           ​Integer,
           ​DocCommentTree>      		 getJavaDocInfoPos​(Tree tree)
       
      Invoke com.sun.source Line and Position Tools
      Modifier and Type Method
      int endLineNum​(Tree tree)
      int endPos​(Tree tree)
      int startLineNum​(Tree tree)
      int startPos​(Tree tree)
       
      Extract the actual Character-Text from a '.java' Source-File
      Modifier and Type Method
      String substring​(int sPos, int ePos)
      String substring​(Tree tree)
       
      A Walk of the AST, compartmentalized into a TreePath instance
      Modifier and Type Method
      TreePath getTreePath​(Tree tree)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • sourcePositions

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final com.sun.source.util.SourcePositions sourcePositions
        This field is extracted from the CompilationUnitTree which is generated by the Java Compiler. An instance of SourcePositions will accept any node in an AST (Abstract Syntax Tree) and return the specific location (character number) from within a Java Source File where that node is located.

        For instance, when a MethodTree is passed to the method SourcePositions.getEndPosition(CompilationUnitTree, Tree), it returns the exact character number where that method has been declared in the original '.java' Java Source-Code File. Note that the parameter CompilationUnitTree is just a node in an AST also - however, a CompilationUnitTree is itself the root node of the AST that was generated from the '.java' Source-File.

        What is meant by the term 'Character Number', is that if the entire source-file were loaded into a java.lang.String, that source-file's srcFileAsStr.charAt(charNum) would be the first character in whatever tree branch or leaf was searched using class SourcePositions.

        The following list of methods, and their explanations have been copied, verbatim, from the Java 17 Oracle Web-Site Documentation. These are the methods exported by class com.sun.source.util.SourcePositions.
        Modifier and Type Method Description
        long getEndPosition(CompilationUnitTree file, Tree tree) Returns the ending position of tree within file.
        long getStartPosition(CompilationUnitTree file, Tree tree) Returns the starting position of tree within file.

        NOTE:
        The instance of CompilationUnitTree that was generated by the Java Compiler when parsing the Source-Code File is available as a public field in this class.

      • docTrees

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final com.sun.source.util.DocTrees docTrees
        Java's Sun/Oracle Abstract Syntax Tree engine provides AST's for Java-Doc Comments, in addition to trees for the actual source-code. This reference here is merely an instance of the utility class containing tools for traversing Java-Doc Comment Syntax Trees.

        More information about these trees is available in the documentation for the Java package com.sun.source.util.DocTrees.

      • docSourcePositions

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final com.sun.source.util.DocSourcePositions docSourcePositions
        While generating AST's for a Java Source-File, the Java Compiler will also generate a Java-Doc Comment Tree that operates / exists "in parallel" to the Source-Code AST. An instance of DocSourcePositions can be used in the exact same way as an instance of class SourcePositions is used - except it retrieves position & location information within a Source-Code File for Java-Doc Comments.

        The following list of methods, and their explanations have been copied, verbatim, from the Java 17 Oracle Web-Site Documentation. These are the methods exported by class com.sun.source.util.DocSourcePositions.
        Modifier and Type Method Description
        long getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) Returns the ending position of the tree within the comment within the file.
        long getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) Returns the starting position of the tree within the comment within the file.

        NOTE:
        The instance of CompilationUnitTree that was generated by the Java Compiler when parsing the Source-Code File is available as a public field in this class.

      • compilationUnitTree

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final com.sun.source.tree.CompilationUnitTree compilationUnitTree
        This instance is generated by the Java-Compiler when it is asked to perform an AST (Abstract Syntax Tree) parse of a Java Source-Code File (a '.java' File). A CompilationUnitTree is essentially the root node (the 'top' of the tree) of a Source-Code AST.

        Please review the Sun/Oracle Documentation Page for a fuller explanation of this class' features.

      • lineMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final com.sun.source.tree.LineMap lineMap
        This instance is quite similar to the com.sun.source.util.SourcePositions class, except instead of retrieving character locations of node's in an AST, it accepts character positions within a Java-Source File, and converts them into Source-File Line-Numbers.

        An instance of LineMap can also convert a line-number into a character position within a Source-File, and/or convert a line-number & column-number combination into a Source-File Character-Position.

        The following list of methods, and their explanations have been copied, verbatim, from the Java 17 Oracle Web-Site Documentation. These are the methods exported by class com.sun.source.tree.LineMap.
        Modifier and Type Method Description
        long getColumnNumber(long pos) Finds the column for a character position.
        long getLineNumber(long pos) Finds the line containing a position; a line termination character is on the line it terminates.
        long getPosition(long line, long column) Finds the position corresponding to a (line,column).
        long getStartPosition(long line) Finds the start position of a line.

      • srcFileName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String srcFileName
        This is nothing more than a copy of the constructor-parameter by the same name. This shall contain the file-name for the source-code file that has been parsed to create an instance of this class, TreeUtils.

      • srcFileAsStr

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String srcFileAsStr
        This is also a copy of a constructor-parameter, reserved for any needed use by a reference in this class. It holds a '.java' source-code file, loaded into memory and saved as a java.lang.String.

    • Constructor Detail

      • TreeUtils

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public TreeUtils​(java.lang.String srcFileName,
                 java.lang.String srcFileAsStr)
        Constructs an instance of this class. Accepts a Java Source-Code File-Name, and that file alredy fully-loaded into memory - as a java.lang.String. This constructs invokes the internal instance of the Java Compiler, and then fills in all of the public fields for this class.
        Parameters:
        srcFileName - The name of a Java Source-Code File
        srcFileAsStr - The textual-content of that Source-File, loaded into a java.lang.String
        See Also:
        srcFileName, srcFileAsStr

    • Method Detail

      • startPos

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int startPos​(com.sun.source.tree.Tree tree)
        Returns the starting position within the text of the relevant Java Source-Code File for the sub-tree specified by parameter 'tree'.
        Parameters:
        tree - This may be any AST branch or leaf, but it must be sub-node that falls within the root-node compilationUnitTree.
        See Also:
        sourcePositions, compilationUnitTree
        Code:
        Exact Method Body:
         return (int) this.sourcePositions.getStartPosition(this.compilationUnitTree, tree);

      • endPos

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int endPos​(com.sun.source.tree.Tree tree)
        Returns the ending position within the text of the relevant Java Source-Code File for the sub-tree specified by parameter 'tree'.
        Parameters:
        tree - This may be any AST branch or leaf, but it must be sub-node that falls within the root-node compilationUnitTree.
        See Also:
        sourcePositions, compilationUnitTree
        Code:
        Exact Method Body:
         return (int) this.sourcePositions.getEndPosition(this.compilationUnitTree, tree);

      • startLineNum

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int startLineNum​(com.sun.source.tree.Tree tree)
        Returns the line-number within the text of the relevant Java Source-Code File for the first line of code of the element specified by parameter 'tree'.
        Parameters:
        tree - This may be any AST branch or leaf, but it must be sub-node that falls within the root-node compilationUnitTree.
        See Also:
        lineMap, sourcePositions, compilationUnitTree
        Code:
        Exact Method Body:
         return (int) this.lineMap.getLineNumber
     (this.sourcePositions.getStartPosition(this.compilationUnitTree, tree));

      • endLineNum

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int endLineNum​(com.sun.source.tree.Tree tree)
        Returns the line-number within the text of the relevant Java Source-Code File for the last line of code of the element specified by parameter 'tree'.
        Parameters:
        tree - This may be any AST branch or leaf, but it must be sub-node that falls within the root-node compilationUnitTree.
        See Also:
        lineMap, sourcePositions, compilationUnitTree
        Code:
        Exact Method Body:
         return (int) this.lineMap.getLineNumber
     (this.sourcePositions.getEndPosition(this.compilationUnitTree, tree));

      • substring

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String substring​(int sPos,
                                  int ePos)
        Performs a standard Java 'substring' operation on the Source-Code File, which has been saved as a String into internal & public field srcFileAsStr.
        Parameters:
        sPos - The first character-postion within the text-file
        ePos - The last character-postion within the text-file
        Returns:
        The extracted sub-string.
        Code:
        Exact Method Body:
         return this.srcFileAsStr.substring(sPos, ePos);

      • substring

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String substring​(com.sun.source.tree.Tree tree)
        Extracts the exact text / character-data from the original '.java' Source Code File for any node in the AST 'Parse-Tree' that was produced from that Source-File.
        Parameters:
        tree - Any node in the AST that was produced from the Source-File saved inside 'this' instance of TreeUtils
        Returns:
        The original Java-Source, as a java.lang.String
        Code:
        Exact Method Body:
         return this.srcFileAsStr.substring(startPos(tree), endPos(tree));

      • getTreePath

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public com.sun.source.util.TreePath getTreePath​
            (com.sun.source.tree.Tree tree)
        An instance of TreePath is a class which stores node / branch references for a node in an AST extending back to the top-level node in the Compilation-Unit.

        The Parse-Trees produced by the com.sun.source.tree classes do not provide very much in the way of parent or ancestor node pointers. This makes finding where a particular branch in an Abstract Syntax Tree a little more difficult. An instance of 'TreePath' simplifies the process.
        Parameters:
        tree - This should be a node that exists within the AST that is associated / stored inside 'this' reference of TreeUtils.
        Returns:
        A TreePath instance that contains the straight-line path to the root node in the Abstract Syntax Tree.
        Code:
        Exact Method Body:
         return TreePath.getPath(this.compilationUnitTree, tree);

      • getJavaDocInfoPos

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Ret3<java.lang.Integer,​java.lang.Integer,​com.sun.source.doctree.DocCommentTree> getJavaDocInfoPos​
            (com.sun.source.tree.Tree tree)
        Retrieve Java-Doc Comment information (if present / if provided) for any of the entities / members of a CIET / Type.
        Parameters:
        tree - The Entity for which a Java-Doc Comment is sought.
        Returns:
        An instance of Ret3 as follows:

        • Ret3.a: Integer
          The starting character-position of the Java-Doc Comment in the original Source-Code File.

        • Ret3.b: Integer
          The ending character-position of the Java-Doc Comment in the original Source-Code File.

        • Ret3.b: DocCommentTree
          The Parse-Tree for the Java-Doc Comment.


        NOTE: If the Entity / Member of the 'tree' that was passed as input to this method does not have a Java-Doc Comment written, then this method will return null instead.
        See Also:
        docTrees, compilationUnitTree, docSourcePositions, srcFileAsStr
        Code:
        Exact Method Body:
         TreePath treePath = TreePath.getPath(this.compilationUnitTree, tree);

 DocCommentTree dct = (treePath != null)
     ? this.docTrees.getDocCommentTree(treePath)
     : null;

 if (dct == null) return new Ret3<>(-1, -1, null);

 int sPos = (int) this.docSourcePositions.getStartPosition
     (this.compilationUnitTree, dct, dct);

 int ePos = (int) this.docSourcePositions.getEndPosition
     (this.compilationUnitTree, dct, dct);

 // This is a case where there is an "empty comment".  I'm not sure at the moment if there
 // is a "more appropriate" way to be handling this.  However, while writing code, an empty
 // comment did, indeed, generate a **NON-NULL** 'dct' - but sPos and ePos were both -1
 // 
 // For now, I guess, we are going to pretend that a PERFECTLy-EMPTY JavaDoc-Comment (such
 // as /**    */), is identical to have NO-COMMENT at all.

 if ((sPos == -1) && (ePos == -1)) return new Ret3<>(-1, -1, null);

 while (sPos >= 2)
     if (this.srcFileAsStr.charAt(sPos--) == '*')
         if (this.srcFileAsStr.regionMatches(sPos - 1, "/**", 0, 3))
         { sPos--; break; }

 /*
 System.out.println(
     "this.srcFileName: " + this.srcFileName + '\n' +
     "sPos: " + sPos + ", ePos: " + ePos + '\n' +
     "this.srcFileAsStr.substring(sPos, sPos+50): " +
     this.srcFileAsStr.substring(sPos, sPos+50)
 );

 try { System.out.println("str: " + this.srcFileAsStr.substring(sPos, ePos)); }
 catch (Exception e) { System.out.println("e.getMessage(): " + e.getMessage()); }
 */

 // Note that today is the "BIG DAY", I am trying to run my build on OCI rather than GCP.  
 // It is April 29th, 2024.  I have just run into an issue (which never happened on whatever
 // version of `javadoc` is running on GCP).  Here, the first package to have shown the 
 // issue was in Apache.CLI.DefaultParser - which has an internal-static inner-class simply
 // named "Builder".  For "Builder" the ePos is returning '-1'
 // 
 // Thinking about how "TreeUtils" works is not something I've been doing lately, but I 
 // just reviewed all of the sordid details of "com.sun.source.util.DocSourcePositions".
 // 
 // These Methods:
 // getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree)
 // getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree)
 // 
 // Look for the Position in the source file's "comment" for the specific item inside that
 // comment, specifically item "tree".  For static-inner classes, this new version of 
 // javadoc that is running on OCI (rather than GCP) is returning "-1".
 // 
 // Fortunately, for me, there is an answer, but I think this solution could fail if the
 // user included a "*/" Sub-String somwhere inside their comments.
 // 
 // THIS HACK IS TO JUST SET ePos to sPos if "getEndPosition" failed and returned -1
 // 
 // NOTE: I **THINK** - but I'm not 100% that I should switch this "hacky" like line to 
 // one that iterates through the elements in the List<DocTree> returned by this method
 // from class DocCommentTree.  I used to have a method that did just that, but I deleted it
 // last year because iterating the character-data itself was much more efficient.  However,
 // apparently for static-inner classes, newer versions of javadoc are just failing.
 // 
 // default List<? extends DocTree> getFullBody()
 // Returns the entire body of a documentation comment, appearing before any block tags,
 // including the first sentence.

 if (ePos < 0) ePos = sPos;  // "The Hack"

 // And then this stuff below is the original code written in 2023...
 int MAX = this.srcFileAsStr.length() - 2;
 while (ePos < MAX)
     if (this.srcFileAsStr.charAt(ePos++) == '*')
         if (this.srcFileAsStr.regionMatches(ePos - 1, "*/", 0, 2))
         { ePos++; break; }

 return new Ret3<>(sPos, ePos, dct);

      • getJavaDocInfoLine

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Ret3<java.lang.Integer,​java.lang.Integer,​com.sun.source.doctree.DocCommentTree> getJavaDocInfoLine​
            (com.sun.source.tree.Tree tree)
        Retrieve Java-Doc Comment information (if present / if provided) for any of the entities / members of a CIET / Type.
        Parameters:
        tree - The Entity for which a Java-Doc Comment is sought.
        Returns:
        An instance of Ret3 as follows:

        • Ret3.a: Integer
          The starting line-number of the Java-Doc Comment in the original Source-Code File.

        • Ret3.b: Integer
          The ending line-number of the Java-Doc Comment in the original Source-Code File.

        • Ret3.b: DocCommentTree
          The Parse-Tree for the Java-Doc Comment.


        NOTE: If the Entity / Member of the 'tree' that was passed as input to this method does not have a Java-Doc Comment written, then this method will return null instead.
        See Also:
        docTrees, compilationUnitTree, srcFileAsStr, docSourcePositions, lineMap
        Code:
        Exact Method Body:
         TreePath treePath = TreePath.getPath(this.compilationUnitTree, tree);

 DocCommentTree dct = (treePath != null)
     ? this.docTrees.getDocCommentTree(treePath)
     : null;

 if (dct == null) return new Ret3<>(-1, -1, null);

 int sPos = (int) this.docSourcePositions.getStartPosition
     (this.compilationUnitTree, dct, dct);

 int ePos = (int) this.docSourcePositions.getEndPosition
     (this.compilationUnitTree, dct, dct);

 while (sPos >= 2)
     if (this.srcFileAsStr.charAt(sPos--) == '*')
         if (this.srcFileAsStr.regionMatches(sPos - 1, "/**", 0, 3))
         { sPos--; break; }

 int MAX = this.srcFileAsStr.length() - 2;
 while (ePos < MAX)
     if (this.srcFileAsStr.charAt(ePos++) == '*')
         if (this.srcFileAsStr.regionMatches(ePos - 1, "*/", 0, 2))
         { ePos++; break; }

 return new Ret3<>(
     (int) this.lineMap.getLineNumber(sPos),
     (int) this.lineMap.getLineNumber(ePos),
     dct
 );

      • getJavaDocCommentTree

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public com.sun.source.doctree.DocCommentTree getJavaDocCommentTree​
            (com.sun.source.tree.Tree tree)
        Retrieves just the Java-Doc Comment Parse-Tree, and does not include Line-Number or Character-Position information.
        Parameters:
        tree - The Entity / Member of the Type for which the Java-Doc Comment is being sought.
        Returns:
        The Java-Doc Comment Parse-Tree
        See Also:
        compilationUnitTree, docTrees
        Code:
        Exact Method Body:
         TreePath treePath = TreePath.getPath(this.compilationUnitTree, tree);

 if (treePath == null) return null;

 return this.docTrees.getDocCommentTree(treePath);