31 import javax.lang.model.util.*;
32
33 /**
34 * A visitor of the values of annotation type elements, using a
35 * variant of the visitor design pattern. Unlike a standard visitor
36 * which dispatches based on the concrete type of a member of a type
37 * hierarchy, this visitor dispatches based on the type of data
38 * stored; there are no distinct subclasses for storing, for example,
39 * {@code boolean} values versus {@code int} values. Classes
40 * implementing this interface are used to operate on a value when the
41 * type of that value is unknown at compile time. When a visitor is
42 * passed to a value's {@link AnnotationValue#accept accept} method,
43 * the <code>visit<i>Xyz</i></code> method applicable to that value is
44 * invoked.
45 *
46 * <p> Classes implementing this interface may or may not throw a
47 * {@code NullPointerException} if the additional parameter {@code p}
48 * is {@code null}; see documentation of the implementing class for
49 * details.
50 *
51 * <p> <b>WARNING:</b> It is possible that methods will be added to
52 * this interface to accommodate new, currently unknown, language
53 * structures added to future versions of the Java™ programming
54 * language. Therefore, visitor classes directly implementing this
55 * interface may be source incompatible with future versions of the
56 * platform. To avoid this source incompatibility, visitor
57 * implementations are encouraged to instead extend the appropriate
58 * abstract visitor class that implements this interface. However, an
59 * API should generally use this visitor interface as the type for
60 * parameters, return type, etc. rather than one of the abstract
61 * classes.
62 *
63 * <p>Note that methods to accommodate new language constructs could
64 * be added in a source <em>compatible</em> way if they were added as
65 * <em>default methods</em>. However, default methods are only
66 * available on Java SE 8 and higher releases and the {@code
67 * javax.lang.model.*} packages bundled in Java SE 8 were required to
68 * also be runnable on Java SE 7. Therefore, default methods
69 * were <em>not</em> used when extending {@code javax.lang.model.*}
70 * to cover Java SE 8 language features. However, default methods
71 * are used in subsequent revisions of the {@code javax.lang.model.*}
72 * packages that are only required to run on Java SE 8 and higher
73 * platform versions.
74 *
75 * @apiNote
76 *
77 * There are several families of classes implementing this visitor
78 * interface in the {@linkplain javax.lang.model.util util
79 * package}. The families follow a naming pattern along the lines of
80 * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
81 * {@linkplain javax.lang.model.SourceVersion source version} the
82 * visitor is appropriate for.
83 *
84 * In particular, a {@code FooVisitor}<i>N</i> is expected to handle
85 * all language constructs present in source version <i>N</i>. If
86 * there are no new language constructs added in version
87 * <i>N</i> + 1 (or subsequent releases), {@code
88 * FooVisitor}<i>N</i> may also handle that later source version; in
89 * that case, the {@link
90 * javax.annotation.processing.SupportedSourceVersion
91 * SupportedSourceVersion} annotation on the {@code
92 * FooVisitor}<i>N</i> class will indicate a later version.
93 *
94 * When visiting an annotation value representing a language construct
95 * introduced <strong>after</strong> source version <i>N</i>, a {@code
96 * FooVisitor}<i>N</i> will throw an {@link
97 * UnknownAnnotationValueException} unless that behavior is overridden.
|
31 import javax.lang.model.util.*;
32
33 /**
34 * A visitor of the values of annotation type elements, using a
35 * variant of the visitor design pattern. Unlike a standard visitor
36 * which dispatches based on the concrete type of a member of a type
37 * hierarchy, this visitor dispatches based on the type of data
38 * stored; there are no distinct subclasses for storing, for example,
39 * {@code boolean} values versus {@code int} values. Classes
40 * implementing this interface are used to operate on a value when the
41 * type of that value is unknown at compile time. When a visitor is
42 * passed to a value's {@link AnnotationValue#accept accept} method,
43 * the <code>visit<i>Xyz</i></code> method applicable to that value is
44 * invoked.
45 *
46 * <p> Classes implementing this interface may or may not throw a
47 * {@code NullPointerException} if the additional parameter {@code p}
48 * is {@code null}; see documentation of the implementing class for
49 * details.
50 *
51 * @apiNote
52 * <strong>WARNING:</strong> It is possible that methods will be added
53 * to this interface to accommodate new, currently unknown, language
54 * structures added to future versions of the Java™ programming
55 * language.
56 *
57 * Such additions have already occurred in another visitor interface in
58 * this package to support language features added after this API was
59 * introduced.
60 *
61 * Visitor classes directly implementing this interface may be source
62 * incompatible with future versions of the platform. To avoid this
63 * source incompatibility, visitor implementations are encouraged to
64 * instead extend the appropriate abstract visitor class that
65 * implements this interface. However, an API should generally use
66 * this visitor interface as the type for parameters, return type,
67 * etc. rather than one of the abstract classes.
68 *
69 * <p>Methods to accommodate new language constructs are expected to
70 * be added as default methods to provide strong source compatibility,
71 * as done for {@link ElementVisitor#visitModule visitModule} in
72 * {@code ElementVisitor}. The implementations of the default methods
73 * in this interface will in turn call {@link visitUnknown
74 * visitUnknown}, behavior that will be overridden in concrete
75 * visitors supporting the source version with the new language
76 * construct.
77 *
78 * <p>There are several families of classes implementing this visitor
79 * interface in the {@linkplain javax.lang.model.util util
80 * package}. The families follow a naming pattern along the lines of
81 * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
82 * {@linkplain javax.lang.model.SourceVersion source version} the
83 * visitor is appropriate for.
84 *
85 * In particular, a {@code FooVisitor}<i>N</i> is expected to handle
86 * all language constructs present in source version <i>N</i>. If
87 * there are no new language constructs added in version
88 * <i>N</i> + 1 (or subsequent releases), {@code
89 * FooVisitor}<i>N</i> may also handle that later source version; in
90 * that case, the {@link
91 * javax.annotation.processing.SupportedSourceVersion
92 * SupportedSourceVersion} annotation on the {@code
93 * FooVisitor}<i>N</i> class will indicate a later version.
94 *
95 * When visiting an annotation value representing a language construct
96 * introduced <strong>after</strong> source version <i>N</i>, a {@code
97 * FooVisitor}<i>N</i> will throw an {@link
98 * UnknownAnnotationValueException} unless that behavior is overridden.
|