Class JavaSourceCodeFile

  • All Implemented Interfaces:
    java.io.Serializable

    public class JavaSourceCodeFile
    extends ParsedFile
    implements java.io.Serializable
    Java Parser Bridge, Java Source Code File - Documentation.

    This class is capable of parsing a java-source file, and returning the parse results as a series of String's. The parse-results are returned as an instance of 'this' class. There are a series of Vector's that contain lists of Method's, Constructor's and also Field's.

    There is a Java-Parser Library that is required to use this Package. The Java Doc Upgrader Package / Tool will not work without this '.jar'file being placed in your CLASSPATH environment-variable. That '.jar'is available here:

    http://developer.torello.directory/ralphsReference/jars/javaparser-core-3.16.2.jar

    There is a book available and an internet "Gitter" support web-site chat-room with some of the people involved in writing this library. There are quite a number of available jars in the "Master Jar Distribution" - but the core library jar is fully sufficient for running the tasks needed by this Java-Doc Upgrade Tool's logic.

    Below is the Inheritance Diagram for the two File-Parser Classes. Both of these classes (in the diagram) parse into an identical set of class-fields. The parsers, themselves, though achieve this through two very different means. One class is derived from a '.html' file, and the other a '.java' file.

    Parsed File Inheritance

    In order to retrieve Java Method and Constructor bodies as String's - and perform the syntax hiliting needed to insert them into the JavaDoc Web-Pages, both of these parsers are needed to do an upgrade.
    See Also:
    Serialized Form




    • Field Detail

      • serialVersionUID

        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final long serialVersionUID = 1;
        
    • Method Detail

      • main

        public static void main​(java.lang.String[] argv)
                         throws java.lang.Exception
        Throws:
        java.lang.Exception
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
         String fName = "Torello/HTML/Attributes.java";
         String src = Torello.Java.LFEC.loadFile(fName);
         System.out.println(fName + ":");
         parse(src, fName, "Attributes", CIET.CLASS);
        
         fName = "Torello/HTML/Scrape.java";
         src = Torello.Java.LFEC.loadFile(fName);
         System.out.println(fName + ":");
         parse(src, fName, "Scrape", CIET.CLASS);
        
         fName = "Torello/HTML/Debug.java";
         src = Torello.Java.LFEC.loadFile(fName);
         System.out.println(fName + ":");
         parse(src, fName, "Debug", CIET.CLASS);
        
      • parse

        public static JavaSourceCodeFile parse​
                    (java.lang.String javaSrcFileAsString,
                     java.lang.String javaSrcFileName,
                     java.lang.String name,
                     CIET ciet)
                throws SourceCodeParseException
        
        This will parse a java source-code file, and retrieve details about the methods, constructors and fields found by the package JavaParser.

        IMPORTANT NOTE: Before any of the classes in this package JavaParserBridge will successfully compile with user's code, the JAR-File for the JavaParser must first be downloaded. Although any programmer who wishes to explore further the API that this package provides, only a portion of the entire parser package is necessary. There are quite a few jar-files available, but the only one necessary to implement the classes in package JavaParserBridge are available for download via a link at the top of this class, and also in the package summary page.
        Parameters:
        javaSrcFileAsString - This may be any valid java source-code file which has already been retrieved from disk, or elsewhere. If this is not a valid java source file (as a String), the results that occur are based on how the underlying jar file handles it. Please consult the JavaParser.org website for more details.
        javaSrcFileName - This is required in the case that an exception has thrown. If any exceptions throw, then this String will be included with the internal data of the thrown exception. This will, perhaps, make error checking and debugging easier.
        name - This is the un-qualified name of the CIET. If this class is an inner-class, the enclosing class name is included. Package-Name information is not included.
        Returns:
        An instance of this class. The instance will have had it's result-Vectors filled with the appropriate Method, Constructor and Field Vectors.
        Throws:
        SourceCodeParseException - If while processing and reading the '.java' source-code file there are any problems parsing and converting the file that cause an exception, this exception will "wrap" the underlying exception. For more information about what has gone wrong, use the 'SourceCodeParseException.getCause()' method. Also, this exception provides a public final String 'javaSrcFileName' that details which file was being processed when the original exception was thrown.
        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
         try
         {
             // JavaParser "Main A.P.I." method to request a parse of '.java' source-code file
             // (passed a complete-file-string)
             CompilationUnit cu = StaticJavaParser.parse(javaSrcFileAsString);
        
             // Get the package-name of the file (if any, 'null' is sufficient if there isn't one)
        
             Optional<PackageDeclaration> optPD = cu.getPackageDeclaration();
        
             String pkgName = optPD.isPresent() ? optPD.get().getName().asString() : null;
        
             // If this is a java generic (like Vector<E>), retrieve the 'E' (or list of params),
             // and simply saves them into a String-array.  For class java.util.TreeMap<K,V>, the
             // array would contain 'K' and 'V' in it's array cells.  This probably ought to be
             // converted to a 'char' array one-day (instead of String-array)
             String[] genParams = retrieveGenericTypeParameters(cu, name);
        
             // An instance of **THIS** class.  This class is its own return-type.
             // NOTE: This method could have been re-written as a constructor, instead of as 'parse'
             JavaSourceCodeFile ret = new JavaSourceCodeFile
                 (javaSrcFileName, name, pkgName, ciet, genParams);
        
             // This is sort of like a java-script "event-handler" or (also) java "Consumer"
             // HANDLER will visit all of the methods, fields, and constructors inside this 
             // source-code file that were found by Java-Parser.  It is complicated.
             VoidVisitor<?> visit = new HANDLER(ret, javaSrcFileName);
        
             // Call JavaParser, it will use the HANDLER static-inner-class as the "Event Handler"
             // It will iterate through all methods, constructors and fields in this source code
             // file.
             visit.visit(cu, null);
        
             // Feeble minded attempt to clear out the AST tree, quickly (wasn't the problem!).
             // AST's are automatically garbage collected pretty well when they go out of scope.
             // There *WAS* (past tense) a horrible memory leak somewhere...
             // 
             // NULL_THE_TREE(cu); // Method erased, didn't work.  "PhantomNodeLogic" worked...
        
             // JavaParser's "Lexical Preserving Printer" actually builds a very large cache
             // of String's - so that it doesn't compute answers to its methods more than once.
             // This cache doesn't clear automatically when an AST goes out of scope.  Seems
             // a little silly, but this invocation definitely did the trick. (The memory leak
             // disappeared)
             PhantomNodeLogic.cleanUpCache();
        
             return ret;
         }
         catch (Exception e)
         {
             // This exception will already have properly formatted error messages.
             // Just re-throw it.
             if (e instanceof SourceCodeParseException) throw e;
        
             try { FileRW.writeFile(javaSrcFileAsString, "t.java"); } catch (IOException ioe) { }
        
             // We should wrap the exception, to make sure to include the file-name.
             throw new SourceCodeParseException(
                 "An exception has occurred while parsing a '.java' source-code file: " +
                 "[" + javaSrcFileName + "].  Unable to determine if a specific method, " +
                 "constructor, etc... declaration caused this exception.  Therefore this " +
                 "information is not available.  Please see this exception's e.getCause() " +
                 "method for more information on what underlying exception was thrown.",
                 e, javaSrcFileName, null
             );
         }