JDK-6447051 : (ann) Add @Unsupported annotation
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 6
  • Priority: P5
  • Status: Closed
  • Resolution: Won't Fix
  • OS: solaris_10
  • CPU: x86
  • Submitted: 2006-07-10
  • Updated: 2019-07-24
  • Resolved: 2019-07-24
Related Reports
Relates :  
JDK-8008267 - Add @Supported annotation to com.sun.source types
Description
A DESCRIPTION OF THE REQUEST :
The Java API (particularly collections), allows implementation classes to not follow an interface (optional methods) and instead throw an UnsupportedOperationException. Those methods should be annotated with an @Unsupported (or @UnsupportedOperation) annotation to allow tools to distinguish methods that should not be called, and to allow IDEs to highlight those methods when referencing the implementation class directly, the same way some IDEs will highlight deprecated methods.

JUSTIFICATION :
This allows for safer coding by earlier detection of unsupported methods, and may allow for actual compiler warnings, if the compiler can determine the implementation class at compile time.
Comments
Given lack of sufficient interest to further investigate and work on this matter, closing as will not fix. Motivated parties are welcome to pick up this baton and work the issue.
24-07-2019
Too many "Un" words. How about, for simplicity, if a method unconditionally throws UnsupportedOperationException, it is annotated with @UnsupportedOperation
21-11-2014
Agree with consideration for the larger context. In particular there are a couple senses of "unsupported" which could introduce ambiguity. For example, "unsupported" in a technical sense could mean that Collection.add() is not supported, e.g., for an unmodifiable collection. Another sense of "unsupported" is in a customer service sense, that is, not a supported part of the API, perhaps an implementation-specific API, not part of Java SE, or some such. One possible alternative would be something like "@Unimplemented". This annotation might mean that the method unconditionally throws UnsupportedOperationException. This would apply to mutator operations on unmodifiable collections, should they ever appear in the API. (Guava's Immutable* collections currently use @Deprecated for this, in order to provide some warning at compile-time.) Perhaps a better example currently in the JDK is Thread.stop(Throwable) which throws UnsupportedOperationException unconditionally. Note that this is currently marked @Deprecated; a more precise annotation would be something like @Unimplemented.
21-11-2014
This RFE should be considered in a larger context of how methods, classes, etc. should be marked to indicate they are "unsupported," "not recommended for use", etc.
20-11-2014
Even a JDK-specific version of this annotation could be useful to mark parts of the JDK that were supported or not-supported.
12-10-2012