JavaCompiler's "to do" list

com.sun.tools.javac.main.JavaCompiler's "to do" list

After the source files have been parsed, and their symbols entered in the symbol table, the top level classes and some other items end up on JavaCompiler's "to do" list.

For each entry on the "to do" list, JavaCompiler processes it as follows:

Some parts of the compilation involve modifying the parse tree, so a copy of the root of the tree is kept prior to such manipulation.

Note: this copy is just used to check whether the class is one of those found in a compilation unit on the command line (i.e. in rootClasses).
The top level classes are "attributed", using Attr, meaning that names and other elements within the parse tree are resolved and associated with the corresponding types and symbols. Many semantic errors may be detected here, either by Attr, or by Check.

While attributing the tree, class files will be read as necessary. In addition, if a class is required, and a source file for the class is found that is newer than the class file, the source file will be automatically parsed and put on the "to do" list. This is done by registering JavaCompiler as an implementation of Attr<//code>.SourceCompleter.

Note: there is a hidden option -attrparseonly which can be used to skip the rest of the processing for this file. In so doing, it "breaks" the protocol use to save and restore the source file used to report error messages (Log.useSource). There is a "try finally" block which could reasonably be used/extended to restore the source file correctly.
If there are no errors so far, flow analysis will be done for the class, using Flow. Flow analysis is used to check for definite assignment to variables, and unreachable statements, which may result in additional errors.

Note: flow analysis can be suppressed with the hidden option -relax.
If the "to do" item is a TopLevel tree, it will be the contents of a package-info.java file, containing annotations for a package. (See notes for Enter.)
- Syntactic sugar is processed, using Lower. Lower is defined to return a list of trees for the translated classes and all the translated inner classes.
- If Lower returns a non-empty list, there is an assertion that the list has a single element, in which case, code is generated, using Gen, and the resulting code is written out using ClassWriter.
- No further processing is done on this "to do" item.
Note that Enter will have processed all other TopLevel putting the individual classes that it finds there on the "to do" (and not the TopLevel node itself.)
If stub outputs have been requested, with the hidden -stubs option,
- If the class was one of those mentioned on the command line and is in java.lang, pretty print the source with no method bodies.
- No further processing is done on this "to do" item.
Code involving generic types is translated to code without generic types, using TransTypes.
If source output has been requested, with the hidden -s option
- If the original tree was from command line, pretty print the source code
- No further processing is done on this "to do" item.
Syntactic sugar is processed, using Lower. This takes care of inner classes, class literals, assertions, foreach loops, etc. Lower is defined to return a list of trees for the translated classes and all the translated inner classes.
Note: see also the use of Lower earlier in the loop, when processing TopLevel trees.
For each class returned by Lower
- If source has been requestion with the hidden -printflat option, the source of the class is printed.
- Otherwise, code for the class is generated, using Gen, and the resulting code is written out using ClassWriter.

Issues

The "to do" list is mostly organized by top level classes, and not by compilation units. This means that if a compilation unit contains several classes, it is possible for code to be generated for some of the classes in the file, at which point at error may be detected for one of the remaining classes, preventing code from being generated for that and any subsequent classes. This means that the compilation unit will be partially compiled, with some but not all of the class files being generated. (Bug 5011101)