Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8046094

JEP 104: Type Annotations

    XMLWordPrintable

    Details

    • Type: JEP
    • Status: Closed
    • Priority: P4
    • Resolution: Delivered
    • Fix Version/s: 8
    • Component/s: specification
    • Labels:
      None
    • Author:
      Michael Ernst, Alex Buckley
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Subcomponent:
    • Scope:
      SE
    • JSR:
      308
    • Discussion:
      type dash annotations dash dev at openjdk dot java dot net
    • Effort:
      L
    • Duration:
      XL
    • Alert Status:
       Green
    • JEP Number:
      104

      Description

      Summary

      Extend the set of annotatable locations in the syntax of the Java programming language to include names which indicate the use of a type as well as (per Java SE 5.0) the declaration of a type.

      Goals

      Allow development of useful pluggable type checkers that refine Java's built-in type system.

      Non-Goals

      Standardization of pluggable type checkers.

      Success Metrics

      • Three major pluggable type checkers built on Java SE 8 with a framework such as Ernst's "Checker Framework".

      • Possibly, application of at least one annotation scheme (e.g. for controlling null values) to parts of the JDK 8 codebase. This might (or might not) entail standardizing the definition of useful annotation types (e.g. @Nullable) in Java SE.

      Motivation

      Java's annotation system has been an unquestioned success. Programmers can write annotations on type names which appear in the declaration of variables, methods, and classes, which are then read by enterprise frameworks for configuration purposes and by compilers/IDEs for software quality purposes. Annotations allow boilerplate to be removed from code, and enable basic errors to be detected at compile-time.

      Annotations on type uses, not just type declarations, enable error detection by "pluggable type checkers" which strengthen and refine Java's built-in type system. The strengthened type system prevents, at compile-time, the kind of software quality errors which would otherwise manifest themselves at run time. Examples include null pointer errors, side effects on immutable data, race conditions, information leakage, and non-internationalized strings.

      Description

      JSR 308 makes targeted, low-level changes to the grammar of the Java language to allow annotations on the names of types in most places those names can be used. This includes the names of types occurring in Java SE 7 language constructs like try-with-resources and multi-catch.

      JSR 308 defines new attributes for the JVM class file format to store these annotations on type names. Finally, it makes targeted changes to the java.lang.reflect and javax.lang.model API so that annotations on specific instances of type names can be retrieved.

      Alternatives

      • Idiomatic compile-time software quality can be assessed by tools like FindBugs without programmer-supplied annotations.

      • Notation that suggests an annotation could be placed in /* */-style comments adjacent to a type name, thus "hiding" the "annotation" from the language proper. This increases visual clutter and still necessitates class file and reflection changes.

      Testing

      • JCK tests on newly-annotatable constructs of the Java language, newly-generated class file attributes for annotated constructs above the method body level, and the new reflection API.

      • SQE tests on newly-generated class file attributes for annotated constructs below the method body level. (Method body compilation is compiler-specific and hence not standardized, so annotations on constructs within method bodies are outside JCK's scope.)

      • SQE tests are possible on individual pluggable type checkers, but they are not part of JDK 8 or Java SE 8.

      Risks and Assumptions

      • Risk: That the broad Java development community is not interested in developing or using pluggable type systems.

      • Assumption: That the utility of pluggable type checking is worth making significant changes to the Java grammar, class file, and API. (In addition to annotations on type uses, JSR 308 makes improvements to annotations on type declarations which by common consent should have occurred in JSR 175. These improvements do not by themselves justify or predict the broader changes in JSR 308, but by the same token, the improvements are unlikely to occur without 308's "sponsorship".)

      Impact

      • Other JDK components: If annotated for a specific Checker.
      • Compatibility: Any Java language or class file parser.
      • Documentation: javadoc must display annotations on type uses.
      • TCK: Language, class file, and reflection changes.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              mernst Michael Ernst
              Reporter:
              mernst Michael Ernst
              Owner:
              Michael Ernst Michael Ernst
              Reviewed By:
              Brian Goetz
              Endorsed By:
              Brian Goetz, Mikael Vidstedt
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: