Summary

Add a set of persistent preview visitors to support new language changes in development.

Problem

When new language features are added, the javax.lang.model API may need to be updated. For certain categories of features, the API update includes introducing a new set of concrete visitors to model the language feature.

The API scaffolding of introducing new visitors to support the new feature tends to dwarf the API specifically for the new feature.

By having the scaffolding already present, the incremental API directly related to a new language feature is easier to write and review.

Solution

Add a layer of preview visitor subclasses with direct superclasses of the corresponding latest GA'ed JDK visitors, currently "14". These preview visitors as initially added are plain subclasses with just constructors and no support for any particular language change.

The anticipated usage of the preview visitors is as follows:

Any new methods particular to supporting preview feature P can be annotated accordingly to indicate that connection. When P goes to a final feature, a new set of JDK $N visitors would be inserted between the latest numbered set of visitors and the preview visitors. Methods particular to P would be moved up into the new JDK $N visitors.

For example, if feature P went final in JDK 25, there would be a new set of JDK 25 concrete visitors extending the existing JDK 14 visitors and the superclass of the preview visitors would be changed from the JDK 14 visitor to the corresponding JDK 25 visitor. Methods associated with feature P would be moved up from the preview visitors into the JDK 25 visitors.

Approximate coding pattern:

Before when P is a preview feature

class FooVisitor14<R,P> ...{
    ...
    // preview method
    R visitP(PElement e, p) {return visitUnknown(e, p);}
}

class FooVisitorPreview<R,P> extends FooVisitor14<R, P>{
    ...
    // preview method
    @Override
    R visitP(PElement e, p) {/* do something appropriate to visit a P*/}
}

After P is a non-preview feature

class FooVisitor14<R,P> ...{
    ...
    R visitP(PElement e, p) {return visitUnknown(e, p);}
}

class FooVisitor25<R,P> extends FooVisitor14<R, P>{
    ...
   @Override
    R visitP(PElement e, p) {/* do something appropriate to visit a P*/}
}

class FooVisitorPreview<R,P> extends FooVisitor25<R, P>{
    ...
    // use inherited visitP method.
}

Specification

Patch with licensing headers removed below:

diff --git a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitorPreview.java
new file mode 100644
index 0000000000000..1991319d6640d
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitorPreview.java
@@ -0,0 +1,60 @@
 +
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import static javax.lang.model.SourceVersion.*;
+import javax.lang.model.SourceVersion;
+import javax.annotation.processing.SupportedSourceVersion;
+
+/**
+ * A skeletal visitor for annotation values with default behavior
+ * appropriate for a preview source version.
+ *
+ * @param <R> the return type of this visitor's methods
+ * @param <P> the type of the additional parameter to this visitor's methods.
+ *
+ * @see <a href="AbstractAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see AbstractAnnotationValueVisitor6
+ * @see AbstractAnnotationValueVisitor7
+ * @see AbstractAnnotationValueVisitor8
+ * @see AbstractAnnotationValueVisitor9
+ * @see AbstractAnnotationValueVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public abstract class AbstractAnnotationValueVisitorPreview<R, P> extends AbstractAnnotationValueVisitor14<R, P> {
+
+    /**
+     * Constructor for concrete subclasses to call.
+     */
+    protected AbstractAnnotationValueVisitorPreview() {
+        super();
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitorPreview.java
new file mode 100644
index 0000000000000..717bb41182049
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitorPreview.java
@@ -0,0 +1,64 @@
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.ElementVisitor;
+import javax.lang.model.element.RecordComponentElement;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A skeletal visitor of program elements with default behavior
+ * appropriate for a preview source version.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="AbstractElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see AbstractElementVisitor6
+ * @see AbstractElementVisitor7
+ * @see AbstractElementVisitor8
+ * @see AbstractElementVisitor9
+ * @see AbstractElementVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public abstract class AbstractElementVisitorPreview<R, P> extends AbstractElementVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses to call.
+     */
+    protected AbstractElementVisitorPreview(){
+        super();
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitorPreview.java
new file mode 100644
index 0000000000000..aaac94528cae7
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitorPreview.java
@@ -0,0 +1,62 @@
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A skeletal visitor of types with default behavior appropriate for a
+ * preview source version.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="AbstractTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see AbstractTypeVisitor6
+ * @see AbstractTypeVisitor7
+ * @see AbstractTypeVisitor8
+ * @see AbstractTypeVisitor9
+ * @see AbstractTypeVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public abstract class AbstractTypeVisitorPreview<R, P> extends AbstractTypeVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses to call.
+     */
+    protected AbstractTypeVisitorPreview() {
+        super();
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitorPreview.java
new file mode 100644
index 0000000000000..a782e075ae350
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitorPreview.java
@@ -0,0 +1,87 @@
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.lang.model.element.*;
+import javax.annotation.processing.SupportedSourceVersion;
+import static javax.lang.model.SourceVersion.*;
+import javax.lang.model.SourceVersion;
+
+/**
+ * A visitor of program elements based on their {@linkplain
+ * ElementKind kind} with default behavior appropriate for a preview
+ * source version.
+ *
+ * For {@linkplain
+ * Element elements} <code><i>Xyz</i></code> that may have more than one
+ * kind, the <code>visit<i>Xyz</i></code> methods in this class delegate
+ * to the <code>visit<i>Xyz</i>As<i>Kind</i></code> method corresponding to the
+ * first argument's kind.  The <code>visit<i>Xyz</i>As<i>Kind</i></code> methods
+ * call {@link #defaultAction defaultAction}, passing their arguments
+ * to {@code defaultAction}'s corresponding parameters.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="ElementKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see ElementKindVisitor6
+ * @see ElementKindVisitor7
+ * @see ElementKindVisitor8
+ * @see ElementKindVisitor9
+ * @see ElementKindVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class ElementKindVisitorPreview<R, P> extends ElementKindVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses; uses {@code null} for the
+     * default value.
+     */
+    protected ElementKindVisitorPreview() {
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses; uses the argument for the
+     * default value.
+     *
+     * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
+     */
+    protected ElementKindVisitorPreview(R defaultValue) {
+        super(defaultValue);
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/ElementScannerPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/ElementScannerPreview.java
new file mode 100644
index 0000000000000..60c07bc0c421a
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScannerPreview.java
@@ -0,0 +1,103 @@
+
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import java.util.List;
+import java.util.ArrayList;
+import javax.lang.model.element.*;
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.ElementVisitor;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A scanning visitor of program elements with default behavior
+ * appropriate for a preview source version.
+ *
+ * The <code>visit<i>Xyz</i></code> methods in this class scan their
+ * component elements by calling {@link ElementScanner6#scan(Element,
+ * Object) scan} on their {@linkplain Element#getEnclosedElements
+ * enclosed elements}, {@linkplain ExecutableElement#getParameters
+ * parameters}, etc., as indicated in the individual method
+ * specifications.  A subclass can control the order elements are
+ * visited by overriding the <code>visit<i>Xyz</i></code> methods.
+ * Note that clients of a scanner may get the desired behavior by
+ * invoking {@code v.scan(e, p)} rather than {@code v.visit(e, p)} on
+ * the root objects of interest.
+ *
+ * <p>When a subclass overrides a <code>visit<i>Xyz</i></code> method, the
+ * new method can cause the enclosed elements to be scanned in the
+ * default way by calling <code>super.visit<i>Xyz</i></code>.  In this
+ * fashion, the concrete visitor can control the ordering of traversal
+ * over the component elements with respect to the additional
+ * processing; for example, consistently calling
+ * <code>super.visit<i>Xyz</i></code> at the start of the overridden
+ * methods will yield a preorder traversal, etc.  If the component
+ * elements should be traversed in some other order, instead of
+ * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
+ * should call {@code scan} with the elements in the desired order.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="ElementScanner6.html#note_for_subclasses"><strong>Compatibility note for subclasses</strong></a>
+ * @see ElementScanner6
+ * @see ElementScanner7
+ * @see ElementScanner8
+ * @see ElementScanner9
+ * @see ElementScanner14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class ElementScannerPreview<R, P> extends ElementScanner14<R, P> {
+    /**
+     * Constructor for concrete subclasses; uses {@code null} for the
+     * default value.
+     */
+    protected ElementScannerPreview(){
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses; uses the argument for the
+     * default value.
+     *
+     * @param defaultValue the default value
+     */
+    protected ElementScannerPreview(R defaultValue){
+        super(defaultValue);
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitorPreview.java
new file mode 100644
index 0000000000000..bae1c172aa762
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitorPreview.java
@@ -0,0 +1,78 @@
+
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A simple visitor for annotation values with default behavior
+ * appropriate for a preview source version.
+ *
+ * Visit methods call {@link #defaultAction
+ * defaultAction} passing their arguments to {@code defaultAction}'s
+ * corresponding parameters.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods
+ * @param <P> the type of the additional parameter to this visitor's methods.
+ *
+ * @see <a href="SimpleAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see SimpleAnnotationValueVisitor6
+ * @see SimpleAnnotationValueVisitor7
+ * @see SimpleAnnotationValueVisitor8
+ * @see SimpleAnnotationValueVisitor9
+ * @see SimpleAnnotationValueVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class SimpleAnnotationValueVisitorPreview<R, P> extends SimpleAnnotationValueVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses; uses {@code null} for the
+     * default value.
+     */
+    protected SimpleAnnotationValueVisitorPreview() {
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses; uses the argument for the
+     * default value.
+     *
+     * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
+     */
+    protected SimpleAnnotationValueVisitorPreview(R defaultValue) {
+        super(defaultValue);
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitorPreview.java
new file mode 100644
index 0000000000000..41afd6a50916b
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitorPreview.java
@@ -0,0 +1,83 @@
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.ElementVisitor;
+import javax.lang.model.element.RecordComponentElement;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A simple visitor of program elements with default behavior
+ * appropriate for a preview source version.
+ *
+ * Visit methods corresponding to {@code RELEASE_14} and earlier
+ * language constructs call {@link #defaultAction defaultAction},
+ * passing their arguments to {@code defaultAction}'s corresponding
+ * parameters.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@code Void}
+ *             for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's methods.  Use {@code Void}
+ *              for visitors that do not need an additional parameter.
+ *
+ * @see <a href="SimpleElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see SimpleElementVisitor6
+ * @see SimpleElementVisitor7
+ * @see SimpleElementVisitor8
+ * @see SimpleElementVisitor9
+ * @see SimpleElementVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class SimpleElementVisitorPreview<R, P> extends SimpleElementVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses; uses {@code null} for the
+     * default value.
+     */
+    protected SimpleElementVisitorPreview(){
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses; uses the argument for the
+     * default value.
+     *
+     * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
+     */
+    protected SimpleElementVisitorPreview(R defaultValue){
+        super(defaultValue);
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitorPreview.java
new file mode 100644
index 0000000000000..3dfd11bfe554b
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitorPreview.java
@@ -0,0 +1,82 @@
+
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A simple visitor of types with default behavior appropriate for a
+ * preview source version.
+ *
+ * Visit methods corresponding to {@code RELEASE_14} and earlier
+ * language constructs call {@link #defaultAction defaultAction},
+ * passing their arguments to {@code defaultAction}'s corresponding
+ * parameters.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="SimpleTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see SimpleTypeVisitor6
+ * @see SimpleTypeVisitor7
+ * @see SimpleTypeVisitor8
+ * @see SimpleTypeVisitor9
+ * @see SimpleTypeVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class SimpleTypeVisitorPreview<R, P> extends SimpleTypeVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses; uses {@code null} for the
+     * default value.
+     */
+    protected SimpleTypeVisitorPreview(){
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses; uses the argument for the
+     * default value.
+     *
+     * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
+     */
+    protected SimpleTypeVisitorPreview(R defaultValue){
+        super(defaultValue);
+    }
+}
diff --git a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitorPreview.java b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitorPreview.java
new file mode 100644
index 0000000000000..5da0c370e5a63
--- /dev/null
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitorPreview.java
@@ -0,0 +1,86 @@
+
+package javax.lang.model.util;
+
+import jdk.internal.javac.PreviewFeature;
+
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.type.*;
+import static javax.lang.model.SourceVersion.*;
+
+/**
+ * A visitor of types based on their {@linkplain TypeKind kind} with
+ * default behavior appropriate for a preview source version.
+ *
+ * For {@linkplain
+ * TypeMirror types} <code><i>Xyz</i></code> that may have more than one
+ * kind, the <code>visit<i>Xyz</i></code> methods in this class delegate
+ * to the <code>visit<i>Xyz</i>As<i>Kind</i></code> method corresponding to the
+ * first argument's kind.  The <code>visit<i>Xyz</i>As<i>Kind</i></code> methods
+ * call {@link #defaultAction defaultAction}, passing their arguments
+ * to {@code defaultAction}'s corresponding parameters.
+ *
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @see <a href="TypeKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
+ * @see TypeKindVisitor6
+ * @see TypeKindVisitor7
+ * @see TypeKindVisitor8
+ * @see TypeKindVisitor9
+ * @see TypeKindVisitor14
+ * @since 23
+ */
+@SupportedSourceVersion(RELEASE_23)
+@PreviewFeature(feature=PreviewFeature.Feature.LANGUAGE_MODEL, reflective=true)
+public class TypeKindVisitorPreview<R, P> extends TypeKindVisitor14<R, P> {
+    /**
+     * Constructor for concrete subclasses to call; uses {@code null}
+     * for the default value.
+     */
+    protected TypeKindVisitorPreview() {
+        super(null);
+    }
+
+    /**
+     * Constructor for concrete subclasses to call; uses the argument
+     * for the default value.
+     *
+     * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
+     */
+    protected TypeKindVisitorPreview(R defaultValue) {
+        super(defaultValue);
+    }
+}