Find JSRs
Submit this Search

Ad Banner

Summary  |  Proposal  |  Detail (Summary & Proposal)
JSRs: Java Specification Requests
JSR 305: Annotations for Software Defect Detection

Stage Access Start Finish
Expert Group Formation   12 Sep, 2006  
JSR Review Ballot View results 29 Aug, 2006 11 Sep, 2006
Status: Dormant
JCP version in use: 2.6
Java Specification Participation Agreement version in use: 2.0

This JSR will work to develop standard annotations (such as @NonNull) that can be applied to Java programs to assist tools that detect software defects.

Please direct comments on this JSR to the Spec Lead(s)

Specification Leads
  William Pugh Pugh, William
Expert Group
  Ernst, Michael Google Inc. Oracle
  Pugh, William

This JSR has been Dormant
Reason: The Executive Committee voted to list this JSR as dormant in May 2012.

Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member: William Pugh

Name of Contact Person: William Pugh

E-Mail Address:

Telephone Number: +1 301 405 2705

Fax Number: +1 301 405 6707

Specification Lead: William Pugh

E-Mail Address:

Telephone Number: +1 301 405 2705

Fax Number: +1 301 405 6707

Initial Expert Group Membership:

William Pugh
Doug Lea

Supporting this JSR:

William Pugh
Doug Lea
Michael Ernst

Section 2: Request

2.1 Please describe the proposed Specification:

This JSR would attempt to develop a standard set of annotations that can assist defect detection tools. Such annotations have been found to be useful in tools such as FindBugs and IntelliJ, but developers are hesitant to invest time in providing annotations if they don't know that their annotations will be portable across tools.

These annotations will be applied using the existing annotations capabilities introduced in Java 5, and may also utilize any additional annotation capabilities introduced in Java SE 7.

Some annotations already identified as potential candidates include:

Nullness annotations (e.g., @NonNull and @CheckForNull). Both FindBugs and IntelliJ already support their own versions of nullness annotations.

Check return value annotation - an annotation that says ignoring the return value of a method is likely incorrect (e.g., String.toLowerCase())

Taint annotations - We want to check for errors such as SQL injection and cross-site scripting (see Detecting Format-String Vulnerabilities with Type Qualifiers, Umesh Shankar, Kunal Talwar, Jeffrey S. Foster, and David Wagner 10th USENIX Security Symposium. Washington, D.C., August 2001 for a discussion of using taint annotations in static analysis).

concurrency - We all know that concurrency is hard and statically detecting concurrency errors is very hard. We can look at the annotations proposed by Java Concurrency In Practice and by the CMU Fluid project as a starting point.

Internationalization annotations, such as @NonNls or @Nls, indicating values that either are or are not natural language strings that need to be localized for different locations. These annotations are currently used by IntelliJ.

Many of these annotations could be much more useful if annotations could be supplied in places where that can't currently be applied (e.g., to generic type parameters), and if default annotations could be supplied (e.g., marking all methods in a class or package as having nonnull parameters unless otherwise specifically so annotated).

In addition to FindBugs and IntelliJ, other tools could benifit from such annotations, such as Fortify Software's SCA, Coverity's forthcoming Java analysis tool, the Netbeans Jackpot tool, and IBM's SAFE tool.

We would try to develop annotations that could be usefully applied with a low annotation burden (e.g., making only a few annotations per class), although more intensive annotations might provide additional value.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

This technology targets all Java platforms that support Java annotations, as introduced in Java SE 5.

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

To gain maximum benefit of this technology is needs to be deployed as part Java standard, thus we believe it should be part of Java SE 7. Much or all of the technology developed for this JSR will be available as a separate download that can be used with other Java editions.

2.4 Should this JSR be voted on by both Executive Committees?

No. Just the Java SE/EE executive committee should suffice.

2.5 What need of the Java community will be addressed by the proposed specification?

There is considerable interest in the Java community in developing reliable software and in using tools to assist in that process. One such tool, FindBugs, has been downloaded more than 250,000 times and is used in many companies. Making such tools more effective will require standard annotations to denote developer intentions and constraints that are not easily determined by automatic techniques.

2.6 Why isn't this need met by existing specifications?

The only defect detection annotations at the moment are specific to particular tools. To be broadly useful, developers will need to know that the annotations they write can be understood by multiple tools.

The annotations defined by JSR-250 (Common Annotations) are aimed at Java EE issues and not particularly useful for general purpose defect detection tool.

2.7 Please give a short description of the underlying technology or technologies:

The specification would depend on JSR 175(A Metadata Facility for the Java Programming Language) and hence Java SE 5.

The following paper describes how FindBugs detects potential null pointer bugs, and how the use of annotations was essential to detecting a substantial number of errors in a set of student programming projects:
David Hovemeyer, Jaime Spacco, and William Pugh. Evaluating and Tuning a Static Analysis to Find Null Pointer Bugs, Proceedings of the 2005 ACM SIGPLAN-SIGSOFT Workshop on Program Analysis for Software Tools and Engineering (PASTE 2005), Lisbon, Portugal, September, 2005.

2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

Perhaps javax.annotations

2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?


2.10 Are there any security issues that cannot be addressed by the current security model?

The use of annotations could make it easier for developers to use tools to detect security vulnerabilities in software.

2.11 Are there any internationalization or localization issues?


2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

We might revisit existing SuppressWarnings annotation.

2.13 Please describe the anticipated schedule for the development of this specification.

September 2006 Expert group formed
November 2006 Early Draft Review
February 2007 Public Review
July 2007 Proposed Final Draft

2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.

The primary means of communication will be email, with conference calls and face-to-face meetings scheduled as needed.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

The plan is to conduct the vast majority of JSR process via an exceptionally open process, with early drafts and discussion available for public view and comments via The development process used for JSR-133 (the Java Memory Model) and JSR-166 (Concurrency utilities) will be used as a model.

2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

The RI and TCK will be initially delivered standalone. However it is also hoped that the JSR will be bundled into a future Java SE platform release (Java SE 7).

2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).


2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The Reference Implementation and TCK will be made available at no charge without support.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Existing work on Java annotations for defect detection tools:

Findbugs annotations (edu.umd.cs.findbugs.annotations package)

IntelliJ annotations for nullness (
and internationalization support (

Concurrency annotations for Java Concurrency in Practice

There is lots of work on performing static analysis for defect detection (for example, see ), that might suggest things that would be useful.

ESC/Java2 and Java Modeling language (JML) are examples of annotations facilities for showing correctness properties of Java programs. These technologies do not use the annotation technology offered in Java SE 5, and generally impose a higher annotation burden that we would be looking to impose. However, we will consider how their ideas might be adopted.

3.2 Explanation of how these items might be used as a starting point for the work.

The common concepts from these specifications would be the starting point for this JSR.

Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.