Skip to content
Permalink
Browse files
8240130: Improve and update discussion of visitor evolution warnings
Reviewed-by: jjg
  • Loading branch information
jddarcy committed Mar 14, 2020
1 parent 6ead905 commit b0194692322a935d5d25e1c8f749a127e6a1596b
Showing with 416 additions and 979 deletions.
  1. +24 −23 src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java
  2. +25 −26 src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java
  3. +24 −26 src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java
  4. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor14.java
  5. +18 −15 src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor6.java
  6. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor7.java
  7. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor8.java
  8. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor9.java
  9. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor14.java
  10. +18 −15 src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java
  11. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor7.java
  12. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor8.java
  13. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor9.java
  14. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor14.java
  15. +18 −15 src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor6.java
  16. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor7.java
  17. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor8.java
  18. +3 −18 src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor9.java
  19. +6 −24 src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor14.java
  20. +21 −21 src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor6.java
  21. +6 −24 src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor7.java
  22. +6 −24 src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor8.java
  23. +6 −24 src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor9.java
  24. +5 −22 src/java.compiler/share/classes/javax/lang/model/util/ElementScanner14.java
  25. +9 −10 src/java.compiler/share/classes/javax/lang/model/util/ElementScanner6.java
  26. +5 −22 src/java.compiler/share/classes/javax/lang/model/util/ElementScanner7.java
  27. +5 −22 src/java.compiler/share/classes/javax/lang/model/util/ElementScanner8.java
  28. +5 −22 src/java.compiler/share/classes/javax/lang/model/util/ElementScanner9.java
  29. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor14.java
  30. +20 −19 src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor6.java
  31. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor7.java
  32. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor8.java
  33. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor9.java
  34. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor14.java
  35. +21 −19 src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor6.java
  36. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor7.java
  37. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor8.java
  38. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor9.java
  39. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor14.java
  40. +21 −19 src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor6.java
  41. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor7.java
  42. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor8.java
  43. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor9.java
  44. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor14.java
  45. +21 −19 src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor6.java
  46. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor7.java
  47. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor8.java
  48. +6 −22 src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor9.java
@@ -48,33 +48,34 @@
* is {@code null}; see documentation of the implementing class for
* details.
*
* <p> <b>WARNING:</b> It is possible that methods will be added to
* this interface to accommodate new, currently unknown, language
* @apiNote
* <strong>WARNING:</strong> 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&trade; programming
* language. Therefore, 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
* abstract visitor class that implements this interface. However, an
* API should generally use this visitor interface as the type for
* parameters, return type, etc. rather than one of the abstract
* classes.
* language.
*
* <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.
* Such additions have already occurred in another visitor interface in
* this package to support language features added after this API was
* introduced.
*
* @apiNote
* 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 abstract visitor class that
* implements this interface. However, an API should generally use
* this visitor interface as the type for parameters, return type,
* etc. rather than one of the abstract classes.
*
* <p>Methods to accommodate new language constructs are expected to
* be added as default methods to provide strong source compatibility,
* as done for {@link ElementVisitor#visitModule visitModule} in
* {@code ElementVisitor}. The implementations of the default methods
* in this interface 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
@@ -40,33 +40,32 @@
* is {@code null}; see documentation of the implementing class for
* details.
*
* <p> <b>WARNING:</b> 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&trade; programming
* language. Therefore, 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
* abstract visitor class that implements this interface. However, an
* API should generally use this visitor interface as the type for
* 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
*
* There are several families of classes implementing this visitor
* <strong>WARNING:</strong> 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&trade; programming
* 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 abstract visitor class that
* implements this interface. However, an API should generally use
* this visitor interface as the type for parameters, return type,
* etc. rather than one of the abstract classes.
*
* <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.
*
* <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
@@ -41,33 +41,31 @@
* is {@code null}; see documentation of the implementing class for
* details.
*
* <p> <b>WARNING:</b> 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&trade; programming
* language. Therefore, 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
* abstract visitor class that implements this interface. However, an
* API should generally use this visitor interface as the type for
* 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
*
* There are several families of classes implementing this visitor
* <strong>WARNING:</strong> 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&trade; programming
* 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 abstract visitor class that
* implements this interface. However, an API should generally use
* this visitor interface as the type for parameters, return type,
* etc. rather than one of the abstract classes.
*
* <p>Methods to accommodate new language constructs are expected to
* be added as default methods to provide strong source
* compatibility. 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.
*
* <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
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2019, 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
@@ -33,26 +33,11 @@
* A skeletal visitor for annotation values with default behavior
* appropriate for source version {@link SourceVersion#RELEASE_14 RELEASE_14}.
*
* <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
* Therefore, methods whose names begin with {@code "visit"} may be
* added to this class in the future; to avoid incompatibilities,
* classes which extend this class should not declare any instance
* 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
* #visitUnknown visitUnknown} method. A new abstract annotation
* value 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.
*
* @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
@@ -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
@@ -37,22 +37,25 @@
* appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
* source version.
*
* <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
* Therefore, methods whose names begin with {@code "visit"} may be
* added to this class in the future; to avoid incompatibilities,
* classes which extend this class should not declare any instance
* methods with names beginning with {@code "visit"}.
* @apiNote
* <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
* AnnotationValueVisitor} 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&trade; programming language. Therefore, methods whose
* names begin with {@code "visit"} may be added to this class in the
* future; to avoid incompatibilities, classes and subclasses which
* extend this class should not declare any instance methods with
* names beginning with {@code "visit"}.</p>
*
* <p>When such a new visit method is added, the default
* implementation in this class will be to call the {@link
* #visitUnknown visitUnknown} method. A new abstract annotation
* value 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.
* implementation in this class will be to directly or indirectly call
* the {@link #visitUnknown visitUnknown} method. A new abstract
* annotation value 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
* 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
* @param <P> the type of the additional parameter to this visitor's methods.
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2010, 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
@@ -34,26 +34,11 @@
* appropriate for the {@link SourceVersion#RELEASE_7 RELEASE_7}
* source version.
*
* <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
* Therefore, methods whose names begin with {@code "visit"} may be
* added to this class in the future; to avoid incompatibilities,
* classes which extend this class should not declare any instance
* 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
* #visitUnknown visitUnknown} method. A new abstract annotation
* value 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.
*
* @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 AbstractAnnotationValueVisitor8
* @see AbstractAnnotationValueVisitor9
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011, 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
@@ -34,26 +34,11 @@
* appropriate for the {@link SourceVersion#RELEASE_8 RELEASE_8}
* source version.
*
* <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
* Therefore, methods whose names begin with {@code "visit"} may be
* added to this class in the future; to avoid incompatibilities,
* classes which extend this class should not declare any instance
* 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
* #visitUnknown visitUnknown} method. A new abstract annotation
* value 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.
*
* @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 AbstractAnnotationValueVisitor9
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011, 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
@@ -34,26 +34,11 @@
* appropriate for source versions {@link SourceVersion#RELEASE_9
* RELEASE_9} through {@link SourceVersion#RELEASE_14 RELEASE_14}.
*
* <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
* Therefore, methods whose names begin with {@code "visit"} may be
* added to this class in the future; to avoid incompatibilities,
* classes which extend this class should not declare any instance
* 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
* #visitUnknown visitUnknown} method. A new abstract annotation
* value 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.
*
* @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

0 comments on commit b019469

Please sign in to comment.