From bdc481e96d591adf716aa953132c8b79d27834bb Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Tue, 25 Feb 2020 17:50:08 -0800 Subject: [PATCH] 8193553: Provide better guidance on using javax.lang.model visitors Reviewed-by: jjg --- .../model/element/AnnotationValueVisitor.java | 45 +++++++++++++++-- .../lang/model/element/ElementVisitor.java | 49 ++++++++++++++++++- .../javax/lang/model/type/TypeVisitor.java | 46 ++++++++++++++++- 3 files changed, 135 insertions(+), 5 deletions(-) diff --git a/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java b/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java index dabf7ed29b5..0b3b3602c39 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,9 +27,8 @@ package javax.lang.model.element; import java.util.List; - import javax.lang.model.type.TypeMirror; - +import javax.lang.model.util.*; /** * A visitor of the values of annotation type elements, using a @@ -73,6 +72,46 @@ import javax.lang.model.type.TypeMirror; * packages that are only required to run on Java SE 8 and higher * platform versions. * + * @apiNote + * + * 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}N where N indicates the + * {@linkplain javax.lang.model.SourceVersion source version} the + * visitor is appropriate for. + * + * In particular, a {@code FooVisitor}N is expected to handle + * all language constructs present in source version N. If + * there are no new language constructs added in version + * N + 1 (or subsequent releases), {@code + * FooVisitor}N may also handle that later source version; in + * that case, the {@link + * javax.annotation.processing.SupportedSourceVersion + * SupportedSourceVersion} annotation on the {@code + * FooVisitor}N class will indicate a later version. + * + * When visiting an annotation value representing a language construct + * introduced after source version N, a {@code + * FooVisitor}N will throw an {@link + * UnknownAnnotationValueException} unless that behavior is overridden. + * + *

When choosing which member of a visitor family to subclass, + * subclassing the most recent one increases the range of source + * versions covered. When choosing which visitor family to subclass, + * consider their built-in capabilities: + * + *

+ * * @param the return type of this visitor's methods * @param

the type of the additional parameter to this visitor's methods. * @author Joseph D. Darcy diff --git a/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java b/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java index a04dc0695fc..9e654a36575 100644 --- a/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java +++ b/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -64,6 +64,53 @@ import javax.lang.model.util.*; * packages that are only required to run on Java SE 8 and higher * platform versions. * + * @apiNote + * + * 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}N where N indicates the + * {@linkplain javax.lang.model.SourceVersion source version} the + * visitor is appropriate for. + * + * In particular, a {@code FooVisitor}N is expected to handle + * all language constructs present in source version N. If + * there are no new language constructs added in version + * N + 1 (or subsequent releases), {@code + * FooVisitor}N may also handle that later source version; in + * that case, the {@link + * javax.annotation.processing.SupportedSourceVersion + * SupportedSourceVersion} annotation on the {@code + * FooVisitor}N class will indicate a later version. + * + * When visiting an element representing a language construct + * introduced after source version N, a {@code + * FooVisitor}N will throw an {@link UnknownElementException} + * unless that behavior is overridden. + * + *

When choosing which member of a visitor family to subclass, + * subclassing the most recent one increases the range of source + * versions covered. When choosing which visitor family to subclass, + * consider their built-in capabilities: + * + *

+ * * @param the return type of this visitor's methods. Use {@link * Void} for visitors that do not need to return results. * @param

the type of the additional parameter to this visitor's diff --git a/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java b/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java index a5d19a02d89..e1bc316b485 100644 --- a/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java +++ b/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,6 +26,7 @@ package javax.lang.model.type; import javax.lang.model.element.*; +import javax.lang.model.util.*; /** * A visitor of types, in the style of the @@ -64,6 +65,49 @@ import javax.lang.model.element.*; * packages that are only required to run on Java SE 8 and higher * platform versions. * + * @apiNote + * + * 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}N where N indicates the + * {@linkplain javax.lang.model.SourceVersion source version} the + * visitor is appropriate for. + * + * In particular, a {@code FooVisitor}N is expected to handle + * all language constructs present in source version N. If + * there are no new language constructs added in version + * N + 1 (or subsequent releases), {@code + * FooVisitor}N may also handle that later source version; in + * that case, the {@link + * javax.annotation.processing.SupportedSourceVersion + * SupportedSourceVersion} annotation on the {@code + * FooVisitor}N class will indicate a later version. + * + * When visiting a type representing a language construct + * introduced after source version N, a {@code + * FooVisitor}N will throw an {@link UnknownTypeException} + * unless that behavior is overridden. + * + *

When choosing which member of a visitor family to subclass, + * subclassing the most recent one increases the range of source + * versions covered. When choosing which visitor family to subclass, + * consider their built-in capabilities: + * + *

    + * + *
  • {@link AbstractTypeVisitor6 AbstractTypeVisitor}s: + * Skeletal visitor implementations. + * + *
  • {@link SimpleTypeVisitor6 SimpleTypeVisitor}s: Support + * default actions and a default return value. + * + *
  • {@link TypeKindVisitor6 TypeKindVisitor}s: Visit methods + * provided on a {@linkplain TypeMirror#getKind per-kind} granularity + * as some categories of types can have more than one kind. + * + *
+ * * @param the return type of this visitor's methods. Use {@link * Void} for visitors that do not need to return results. * @param

the type of the additional parameter to this visitor's