JDK 15 RFR of JDK-8240130: Improve and update discussion of visitor evolution warnings
Joe Darcy
joe.darcy at oracle.com
Thu Feb 27 06:00:08 UTC 2020
Hello,
Please review the documentation changes for
JDK-8240130: Improve and update discussion of visitor evolution
warnings
http://cr.openjdk.java.net/~darcy/8240130.0/
Patch below. Some discussion of and rationale for the changes, the
original javax.lang.model visitor interfaces and concrete visitor types
had various warning about the unusual compatibility policies those types
would use. Unlike other post-Java SE 6 era types, it was anticipated
methods would be added to interfaces. Prior to default methods in JDK 8,
such additions were a highly unusual occurrence for public types in the
JDK. After default methods were used commonly in jDK 8, such additions
are of less concern. The risk of a true source compatibility is also low
for a new "visitFoo" method since it will have a parameter of type Foo,
which is new to the release, and thus not have an overloading conflict
with a method in an existing visitor outside of the JDK.
The warnings are thus toned down and adjusted to note that the
envisioned additions have already occurred for prior language additions.
For example, the current policy is only to deprecate the constructors of
obsolete visitor classes rather than the whole class. The "directly or
indirectly call" visitUnknown is to accurately describe, but not limit
to, the current policy of the visitFoo methods in affected concrete
visitors calling the visitFoo default method on the *interface*, which
in turn calls visitUnknown.
The warning text is pulled into an apiNote to avoid getting
inherit-doc-ed for any subclasses. Once the shape of the changes for the
interface and visitor classes are agree to, I'll replicated the changes
for the other types.
Thanks,
-Joe
---
old/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java
2020-02-26 13:13:00.848880601 -0800
+++
new/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java
2020-02-26 13:13:00.512880601 -0800
@@ -40,10 +40,17 @@
* is {@code null}; see documentation of the implementing class for
* details.
*
- * <p> <b>WARNING:</b> It is possible that methods will be added to
+ * @apiNote
+ *
+ * WARNING: It is possible that methods will be added to
* this interface to accommodate new, currently unknown, language
* structures added to future versions of the Java™ programming
- * language. Therefore, visitor classes directly implementing this
+ * language.
+ *
+ * Such additions have already occurred to support language features
+ * added after this API was introduced.
+ *
+ * Visitor classes directly implementing this
* interface may be source incompatible with future versions of the
* platform. To avoid this source incompatibility, visitor
* implementations are encouraged to instead extend the appropriate
@@ -52,21 +59,15 @@
* parameters, return type, etc. rather than one of the abstract
* classes.
*
- * <p>Note that methods to accommodate new language constructs could
- * be added in a source <em>compatible</em> way if they were added as
- * <em>default methods</em>. However, default methods are only
- * available on Java SE 8 and higher releases and the {@code
- * javax.lang.model.*} packages bundled in Java SE 8 were required to
- * also be runnable on Java SE 7. Therefore, default methods
- * were <em>not</em> used when extending {@code javax.lang.model.*}
- * to cover Java SE 8 language features. However, default methods
- * are used in subsequent revisions of the {@code javax.lang.model.*}
- * packages that are only required to run on Java SE 8 and higher
- * platform versions.
- *
- * @apiNote
+ * <p>Methods to accommodate new language constructs are expected to
+ * be added as default methods to provide strong source compatibility,
+ * as done for {@link visitModule visitModule}. The implementations of
+ * the default methods will in turn call {@link visitUnknown
+ * visitUnknown}, behavior that will be overridden in concrete
+ * visitors supporting the source version with the new language
+ * construct.
*
- * There are several families of classes implementing this visitor
+ * <p>There are several families of classes implementing this visitor
* interface in the {@linkplain javax.lang.model.util util
* package}. The families follow a naming pattern along the lines of
* {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
---
old/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java
2020-02-26 13:13:01.560880601 -0800
+++
new/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java
2020-02-26 13:13:01.196880601 -0800
@@ -36,7 +36,9 @@
* appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
* source version.
*
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
+ * @apiNote
+ *
+ * <strong>WARNING:</strong> The {@code ElementVisitor} interface
* implemented by this class may have methods added to it in the
* future to accommodate new, currently unknown, language structures
* added to future versions of the Java™ programming language.
@@ -46,12 +48,12 @@
* methods with names beginning with {@code "visit"}.
*
* <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
+ * implementation in this class will be to directly or indirectly call
the {@link
* #visitUnknown visitUnknown} method. A new abstract element visitor
* class will also be introduced to correspond to the new language
* level; this visitor will have different default behavior for the
- * visit method in question. When the new visitor is introduced, all
- * or portions of this visitor may be deprecated.
+ * visit method in question. When a new visitor is introduced,
+ * portions of this visitor class may be deprecated, including its
constructors.
*
* @param <R> the return type of this visitor's methods. Use {@link
* Void} for visitors that do not need to return results.
More information about the compiler-dev
mailing list