Type Annotations (JSR 308) and the Checker Framework

Contents:

• What are type annotations?
• Download
• Support and community
  • Documentation
  • Mailing lists
  • Bug reports

For the impatient: Download and use pluggable type-checkers now.

What are type annotations?

Java's declaration annotation syntax is useful but limited. As of Java 8, Java's type annotation syntax permits annotations to be written in more places, such as generic type arguments: List<@NonNull Object>. Programmers can use type annotations to write more informative types, and then tools such as type-checkers can detect and prevent more errors.

The Java Language Specification (Java 8 or later) describes type annotations. An earlier version of the Type Annotations Specification (also known as "JSR 308") is available below. It describes the minor, backward-compatible changes to the Java language and classfile format that were adopted in Java 8.

Download

Most users only need to download the Checker Framework. Just follow the Installation instructions and tutorial.

More details and additional downloads appear below.

• The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins. It includes the type annotations compiler. Most users only need this.
  • Documentation:
    • Checker Framework Manual (PDF, HTML)
    • Tutorial
    • Installation instructions
  • source code repository
  • Inference tools automatically add annotations to your code, making it even easier to start using the checkers.
• The Annotation File Utilities extract annotations from, and write annotations to, .java and .class files. It also provides a representation (called an “annotation file”) for annotations that is outside the source code or the .class file. The tools support both Java 5 annotations, and the type annotations defined in JSR 308.
  • Documentation is included in the zip archive and in the repository.
  • Installation instructions
  • source code repository
• Type annotations are specified by the Java Language Specification. An earlier version, the Type Annotations Specification (JSR 308), describes how to write type annotations, both in the Java language and in the classfile format.
  • Type Annotations Specification (PDF)
  • Type Annotations Specification (HTML)
  • FAQ
  • Changelog
• Since all Java 8+ compilers support type annotations, you no longer need the Type annotations compiler.
  The type annotations compiler is fully backward-compatible with javac version 7 and 8. You can use it in place of javac without any change in behavior, except that you will be permitted to place annotations in comments so your code compiles under Java 7. Most users don't need it, since a compiled version (without source code) is already included in the Checker Framework distribution.
  • jsr308-langtools-2.4.0.zip version 2.4.0, 1 Mar 2018
  • README file
  • Changelog

Support and community

If you have a question, then first see whether your question is answered in one of the manuals listed under Documentation below. If none of those documents answers your question, then use one of the mailing lists.

Documentation

• Checker Framework tutorial
• Checker Framework Manual (PDF, HTML)
• Type Annotations (JSR 308) Specification (PDF, HTML)
• Compiler manual
• FAQ: Frequently Asked Questions (with answers)
  • FAQ for type annotations
  • FAQ for the Checker Framework

Mailing lists

The mailing lists are appropriate for discussing the Type Annotations (JSR 308) specification, any tool that processes type annotations (compiler, the Checker Framework, the Annotation File Utilities, etc.), and any other issue related to type annotations. We welcome questions, bug reports, suggestions, reports about case studies, and other contributions. Let us know how we can make type annotations even better!

• jsr308-discuss: for general discussion about the type annotations syntax (view archives, view old archives, view old archives for annotations on statements)
• checker-framework-discuss: for general discussion about the Checker Framework for building pluggable type systems (view archives, view old archives)

Bug reports

To submit a bug report, use the issue tracker for the relevant tool:

• Java Bug Database (for javac bugs)
• Checker Framework issue tracker (please read these instructions first)
• Annotation File Utilities issue tracker

Last updated: September 2, 2020