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 Strings. The results returned as included as an instance of 'this' class. There are a series of Vector's that contain lists of class Method, class Constructor and also class Field.

    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.
    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

      • 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.
        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
         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'
             String[]                        genParams   = retrieveGenericTypeParameters(cu, name);
        
             // An instance of this class, it is its own return-type.
             JavaSourceCodeFile              ret         = new JavaSourceCodeFile(
                                                             javaSrcFileName, name, pkgName,
                                                             ciet, genParams
                                                         );
        
             // This is sort of like java-script "event-handler" or java "Consumer"
             // HANDLER2 will visit all of the methods, fields, and constructors.
             // It is complicated
             VoidVisitor<?>                  visit       = new HANDLER(ret, javaSrcFileName);
        
             // Call JavaParser, it will use the GETTER class as the "Event Handler"
             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);
        
             // JavaParser's "Lexical Preserving Printer" actually builds a very large cache
             // of String's - so that it doesn't compute answers to 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
             );
         }