Bug ID: JDK-5009037 document differences between source and class file views of a declaration

Type: Bug
Component: core-libs
Sub-Component: javax.lang.model
Affected Version: 5.0

Priority: P3
Status: Resolved
Resolution: Fixed
OS: generic
CPU: generic

Submitted: 2004-03-06
Updated: 2016-08-19
Resolved: 2006-05-04

JDK 6
6 b83Fixed

In apt, Declaration information about a type can be gotten from the source file for the type or from the class file of the type.  There can be differences in the information returned from these two views including:

* lack of source retention annotation from class files

* lack of source position information from class files

* potentially different modifers for some constructs

  * strictfp-ness of a class

  * final-ness of a parameter

  * protected, private, and static on classes

These differences need to be documented and/or compensated for.

SUGGESTED FIX src/share/classes/javax/lang/model/element>sccs sccsdiff -r1.2 -r1.3 package-info.java ------- package-info.java ------- 10a11,55 > * <p>When used in the context of annotation processing, an accurate > * model of the element being represented must be returned. As this > * is a language model, the source code provides the fiducial > * (reference) representation of the construct in question rather than > * a representation in an executable output like a class file. > * Executable output may serve as the basis for creating a modeling > * element. However, the process of translating source code to > * executable output may not permit recovering some aspects of the > * source code representation. For example, annotations with > * {@linkplain java.lang.annotation.RetentionPolicy#SOURCE source} > * {@linkplain java.lang.annotation.Retention retention} cannot be > * recovered from class files and class files might not be able to > * provide source position information. The {@linkplain > * javax.lang.model.Modifier modifiers} on an element may differ in > * some cases including > * > * <ul> > * <li> {@code strictfp} on a class or interface > * <li> {@code final} on a parameter > * <li> {@code protected}, {@code private}, and {@code static} on classes and interfaces > * </ul> > * > * Additionally, synthetic constructs in a class file, such as > * accessor methods used in implementing nested classes and bridge > * methods used in implementing covariant returns, are translation > * artifacts outside of this model. > * > * <p>During annotation processing, operating on incomplete or > * erroneous programs is necessary; however, there are fewer > * guarantees about the nature of the resulting model. If the source > * code is not syntactically well-formed, a model may or may not be > * provided as a quality of implementation issue. If a program is > * syntactically valid but erroneous in some other fashion, the > * returned model must have no less information than if all the method > * bodies in the program were replaced by {@code "throw new > * RuntimeException();"}. If a program refers to a missing type XYZ, > * the returned model must contain no less information than if the > * declaration of type XYZ were assumed to be {@code "class XYZ {}"}, > * {@code "interface XYZ {}"}, {@code "enum XYZ {}"}, or {@code > * "@interface XYZ {}"}. If a program refers to a missing type {@code > * XYZ<K1, ... ,Kn>}, the returned model must contain no less > * information than if the declaration of XYZ were assumed to be > * {@code "class XYZ<T1, ... ,Tn> {}"} or {@code "interface XYZ<T1, > * ... ,Tn> {}"} > * 13c58 < * to be unmodifiable by the caller. --- > * to be unmodifiable by the caller and unsafe for concurrent access. 22d66 <

02-05-2006

PUBLIC COMMENTS -

17-07-2004

EVALUATION Must be done before fcs. ###@###.### 2004-03-05

05-03-2004