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