External (Java) annotations.

[lahodaj]

This is something I am experimenting for a very long time (the first commit in the old/original personal Mercurial repository holding this experiment is from May 2013).

This proposal is to add a way to (sort-of) add annotations to Java elements that don't appear in the source.

This is useful when the source code cannot be reasonably modified adding the annotations, various editor features may still rely on the annotations.

Note the editor features that want to use this feature need to do so explicitly, as the external annotations are not fully-featured.

The new API is fairly minimal: ElementUtilities.getAugmentedAnnotationMirrors to read the annotations, and SourceUtils.attachAnnotation to add the annotations (augment an element with an annotation). (SourceUtils being the utils class for things that don't naturally fit anywhere, but are important nonetheless.)

This PR also downloads the annotation files for JDK classes from, well, community edition of Idea. So this is not only an "infrastructure building" PR.

The NPECheck hint is tweaked to use the external annotations.

A new MagicConstantHint hint is added to more showcase the external annotations.

To see a demo of the annotations, this sample can be used:

package external.annos.demo;

import java.lang.reflect.Modifier;
import java.util.BitSet;
import java.util.Calendar;

public class ExternalAnnosDemo {

    public static void main(String[] args) {
        BitSet bs = new BitSet();
        bs.or(null);
        Calendar c = Calendar.getInstance();
        c.isSet(Modifier.FINAL);
    }
    
}

There should be two new warnings for this file - the (null) should get a warning as the or method does not accept null, and isSet(Modifier.Final) should get a warning, as Modifier.FINAL is not an expected constant for Calendar.isSet.

There are more usecases for the external annotations, of course.

I am not marking this as a draft, although I expect some cleanup/improvements will still be needed.

What do you think?

Thanks!

---

^Add meaningful description above

Click to collapse/expand PR instructions

By opening a pull request you confirm that, unless explicitly stated otherwise, the changes -

• are all your own work, and you have the right to contribute them.
• are contributed solely under the terms and conditions of the Apache License 2.0 (see section 5 of the license for more information).

Please make sure (eg. git log) that all commits have a valid name and email address for you in the Author field.

If you're a first time contributor, see the Contributing guidelines for more information.

If you're a committer, please label the PR before pressing "Create pull request" so that the right test jobs can run.

PR approval and merge checklist:

1. Was this PR correctly labeled, did the right tests run? When did they run?
2. Is this PR squashed?
3. Are author name / email address correct? Are co-authors correctly listed? Do the commit messages need updates?
4. Does the PR title and description still fit after the Nth iteration? Is the description sufficient to appear in the release notes?

If this PR targets the delivery branch: don't merge. (full wiki article)

[mbien]

interesting! In a way this goes full circle. Originally all metadata was kept in xml parallel to code and the introduction of annotations merged it with the source. Being able to agument the JDK with additional/external API annotations (like null safety etc) sounds quite useful!