JavaCompiler's "to do" list

diff -r be95c1c0efcf -r 59439733e87a langtools/src/share/opensource/javac/doc/javac_lifecycle/ToDo.html --- a/langtools/src/share/opensource/javac/doc/javac_lifecycle/ToDo.html Wed Apr 23 14:35:26 2008 +0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,167 +0,0 @@ - - - - - - - - - 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.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) - - - -