JDK-8001614 : Include annotation type to documented supported-ness of JDK-specific types
  • Type: Enhancement
  • Component: other-libs
  • Sub-Component: other
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2012-10-26
  • Updated: 2017-05-17
  • Resolved: 2013-02-01
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
8 b77Fixed
Related Reports
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
In addition to supported types defined by the Java SE specification, the JDK implementation contains various other types, some of which are part of the official interface of the JDK and others of which are definitely not.  Some packages contain a mix of official/unofficial (or supported/unsupported) types.

Having an annotation to document supported-ness would allow users of the JDK to more easily determine if they were using inappropriate functionality.
Once we move to modules then only supported APIs will likely be exported, internal/private implementation API will mostly likely be permitted to be used by modules that are part of the JDK. In any case, the problematic namespace is primarily com.sun where it's just not obvious to people what is supported/documented and what is JDK internal. An annotation or some means for tools to identify the supported/official APIs could be very useful.

Such an annotation could reasonably live in the org.openjdk package and be named something like "JdkSupported" with a boolean value() method.