Updated type annotations roadmap

[Eric McCorkle]

In previous list discussions, I have outlined a general roadmap for
improving the quality of the type annotations code in javac.  I am now
very actively pursuing these steps; however, as I've gotten into the
development, I've revised my approach a bit.

Therefore, I'm composing this in order to describe how the plans have
evolved, and also to give advanced notice of the changes I'm going to be
implementing.


== Deficiencies of the Current Implementation ==

The current implementation has (or had) the following deficiencies that
need to be addressed:

1) Improper handling of errors (mostly fixed as of now): There were
several places where the implementation handled error conditions with
silent failures, no-ops, or other incorrect behavior.  These have been
largely addressed, but there could be more still in the code.

2) Two separate codepaths for attaching an annotation to a symbol:
Annotations attached to the declaration itself (ie. those without type
paths) are attached through separateAnnotationsKinds; annotations
attached to arguments, arrays, type parameters, etc. are attached
through the findPosition/resolveFrame codepath.  These are executed at
different points in the compiler pipeline.

3) Unable to generate multiple bytecode annotations from a single source
annotation: The current implementation is designed around the assumption
of a one-to-one relation between source and bytecode annotations.  This
is not always the case.

4) Type annotations positions are generated too late, and type
annotations are attached to symbols too late: Presently, the
resolveFrame codepath executes rather late in the pipeline (after
repeating annotations).  This was a source of bugs, as repeating
annotations copied positions that had not yet been updated correctly
(and is presently a source of a rather awkward workaround fix, which I'd
like to get rid of).  This is also a problem for annotation processing
and javadoc, as many annotations aren't attached and given positions
when annotation processing (and therefore, javadoc) runs.

5) Parts of the implementation don't follow javac development guidelines.


== Revised Type Annotations Pipeline ==

I plan to address the above deficiencies by changing the overall type
annotations pipeline to the following (the exact details are still being
designed):

1) Type paths (and possibly complete TypeAnnotationPosition's) are
constructed during memberEnter, and carried forward by Annotate.Worker's
2) All type annotations are attached by a single codepath, adapted from
separateAnnotationsKinds.  The type path information is already
available, as it was generated in memberEnter.
3) Repeating annotations then does its processing, and will correctly
copy the positions from any type annotations.
4) All type annotations should then be attached and have correct
positions when annotation processing runs.

I am currently undecided about where to actually generate the
TypeCompound attributes, though I am leaning towards generating them at
the same point where they are attached to symbols, this eliminates the
need to carry them forward as metadata on the Tree, and will probably be
a cleaner solution in the end.


== Development Roadmap ==

I am implementing these changes using the following roadmap:

1) Remove silent failures or turn them into assertions failures: I have
already removed four silent failures, though there could be more
2) Make some data in TypeAnnotationPosition immutable, clean up
instantiations of TypeAnnotationPosition (patch out for review)
3) Implement logic for building type paths and possibly whole
TypeAnnotationPositions in memberEnter, add fields/arguments necessary
to carry that information forward to the point where annotations are
attached.
4) Implement a unified codepath for (possibly generating and) attaching
annotations to symbols, likely by adapting code from
separateAnnotationsKinds.  Remove findPosition/resolveFrame codepath.
5) Remove miscellaneous dead/useless code (getPosition in attributes, etc)
6) Fix any remaining issues preventing currently @ignore'd tests from
running, implement a comprehensive combo test.


There are some residual issues that are not part of this effort, but
should be addressed:

* It might be preferable to make TypeAnnotationPosition an abstract
superclass with a number of subclasses.
* Currently, Gen modifies parts of TypeAnnotationPosition, which
precludes making the entire structure immutable (this can be seen in
ClassReader as of my latest patch)


== Current Status ==

As of now, I have completed the first and second stages on this roadmap.
 I have already pushed four patches that remove silent failures, and I
have a patch that makes a good portion of TypeAnnotationPosition immutable.

However, the roadmap I've outlined involves rather significant changes
to the current implementation.  Therefore, I propose the following:

* I will indicate whenever I post a webrev for a major change, to allow
the checkers framework tests and other test to be run, thereby ensuring
that these patches don't introduce any errors.  (It is, of course, our
standard practice to require that the langtools jtreg suite run without
errors before any patch is approved.)

* There should be a final merge of the type annotations repository with
the jdk9 langtools repository.  Following that, I propose discontinuing
the type annotations repo.  Any changes to type annotations after that
point should be done as patches to jdk9/dev/langtools.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: eric_mccorkle.vcf
Type: text/x-vcard
Size: 303 bytes
Desc: not available
Url : http://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20140131/91a33f53/eric_mccorkle.vcf