RFR: 8329644: Discuss expected visitor evolution patterns in javax.lang.model.util [v2]

[Joe Darcy]

On Wed, 17 Apr 2024 15:45:28 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> > We mark the preview-related entry points of the javax.lang.model and Trees API with `@PreviewFeature(..., reflective=true)`, and this then produces warnings like:
> > ```
> > $ javac  /tmp/TestPreview.java
> > /tmp/TestPreview.java:3: warning: [preview] COMPONENT_LOCAL_VARIABLE is a reflective preview API and may be removed in a future release.
> >         System.err.println(javax.lang.model.element.ElementKind.COMPONENT_LOCAL_VARIABLE);
> >                                                                ^
> > 1 warning
> > ```
> > 
> > 
> >     
> >       
> >     
> > 
> >       
> >     
> > 
> >     
> >   
> > I.e. the potential removal is not without a warning. (The difference between "reflective" and non-"reflective" Preview API is that the reflective API can be used without `--enable-preview`.)
> 
> Ah! I didn't notice that `*(Visitor|Scanner)*Preview` classes were annotated with `@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)` because the diffs _in_ the doc comment didn't contain them. Good to know this has been taken care of, thanks! But what about constants and methods this PR proposes to add to `ElementKind`, `ElementVisitor`, and the likes? How does that work?

I'll add some text in the start of this note to indicate:

Any new API elements are marked as reflective preview (without saying how this is done). And any existing methods that are updated to support the new feature are *not* marked as preview.

If the feature is eventually withdrawn instead of being added to the platform, any API elements associated with it are expected to be removed.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/18804#issuecomment-2061778213