[Checkers] Skeleton Index Files

[Michael Ernst]

Mahmood-

Thanks for your thoughtful email about annotation index files.

Let me try to rephrase your points, and separate the distinct issues.  I've
split them into four issues, but feel free to let me know if I missed, or
mischaracterized, anything.


1. Use of skeleton files may lead to wrong static final fields being
inlined in bytecode.

Good point!  We need to change this.  The compiler should be able to read
annotation index files (of some variety) instead.


2. It's annoying to remember to pass the right JDK for each checker.

If a mechanism helps the compiler locating the annotation index file
without requiring the user to specify it explicitly, the same mechanism
should work for locating stub libraries.  I agree that such a mechanism is
desirable!  However, it seems unrelated to your other issues.


3. Mahmood doesn't want to reuse the annotation file utilities.  He prefers
to write a new set of similar tools.

If you create a new file format, I feel strongly that you should integrate
it with the annotation file utilities, permitting them to read and write
either file format (or, we could immediately retire the current annotation
index file format), rather than having a special file format that is used
only by the compiler but is not understood by other tools.

Can you explain your reason for not wanting to use the existing tools?
This is the part of your proposal that raises the most red flags for me,
but then again it's been a long time since I read the source code for the
annotation file utilities.


4. The current annotation index file format is annoying to read.  Mahmood
proposes a different format for the same purpose and containing the same
information.

I agree that the current file format is annoying, by the way, and that
another format would probably be better.  The question is whether it would
be enough better to justify rewriting.

I have a slightly different proposal for the format of the new annotation
file.  My proposal is to use the same syntax as a Java file, with all code
bodies eliminated, but permitting identifiers such as parameter names.  I
believe this will be significantly more readable than the current format,
and also more readable than Mahmood's proposal.

For example, this would be the annotation file for Interned:

  package java.lang;

  class String {
    @Interned String intern();
  }

Multiple "package" and "class" declarations would be permitted in a given
file, but a user can also supply many annotation files for a library.

A disadvantage of this format (and Mahmood's) is that it doesn't handle
annotations within a code body.  I don't think that's a serious problem --
those are of limited use, and we can continue to support the old annotation
index file for such uses.

Another possible disadvantage is that the parsing of my proposed file
format is more complicated than parsing of a simpler, less readable format
such as the one Mahmood proposes.  I don't think it will be a lot more
complicated, since the two are fairly similar.  And we can perhaps gut an
existing Java parser, or write our own.

> The index ... would only  
> contain the relevant methods for the checker (e.g. without any other  
> String methods).

Would the index file permit @Default annotations at the level of a package,
class, etc., so that methods that are omitted nonetheless have their type
qualifiers specified?  This may be an important feature, and it keeps the
index file similar to source code.

> Users can then simply  
> have annotation index files for each library rather than using  
> annotation-file-utilities or having stub classes for each binary and  
> each checker they want to use.

These seem pretty similar:  in each case the user runs a program to create
the stubs and then fills in the stubs.  The big advantage, which I like, is
the lack of interference with javac's class library or which .class files
it loads.

                    -Mike