Unless otherwise specified in a particular implementation, the * collections returned by methods in this package should be expected * to be unmodifiable by the caller and unsafe for concurrent access. * *
Unless otherwise specified, methods in this package will throw * a {@code NullPointerException} if given a {@code null} argument. * * @apiNote * *
The remainder of this note will show two examples of the API * changes in the model and visitors that can be added to support a * language feature. The examples will use additions to the elements * portion of the language model, but the updates to visitors for * types or annotation values would be analogous. * * Two distinct cases are: *
* package javax.lang.model.element;
* /**
* * Represents a preview feature 1.
* *
* * @since N
* */
* public interface PreviewFeature1Element extends Element {
* // Methods to retrieve information specific to the preview feature...
* }
*
* A new element kind would also be introduced to model such a feature:
*
* * // Sample diff of ElementKind.java * + /** * + * A preview feature 1. * + * @since N * + */ * + PREVIEW_FEATURE_1, ** * A {@code default} method is added to {@code ElementVisitor} to accommodate the new construct: *
* // Sample diff for ElementVisitor.java
* + /**
* + * Visits a preview feature 1.
* + *
* + * @implSpec The default implementation visits a {@code
* + * PreviewFeature1Element} by calling {@code visitUnknown(e, p)}.
* + *
* + * @param e the element to visit
* + * @param p a visitor-specified parameter
* + * @return a visitor-specified result
* + * @since N
* + */
* + default R visitPreviewFeature1(PreviewFeature1Element e, P p) {
* + return visitUnknown(e, p);
* + }
*
*
* Given the {@code default} method on the visitor interface, the
* preview visitor classes need to override this method and take an
* action appropriate for the visitor's semantics:
*
*
* // Sample diff for AbstractElementVisitorPreview.java
* // Re-abstract visitPreviewFeature1.
* + /**
* + * {@inheritDoc ElementVisitor}
* + *
* + * @implSpec Visits a {@code PreviewFeature1Element} in a manner
* + * defined by a subclass.
* + *
* + * @param e {@inheritDoc ElementVisitor}
* + * @param p {@inheritDoc ElementVisitor}
* + * @return a visitor-specified result
* + * @since N
* + */
* + @Override
* + public abstract R visitPreviewFeature1(PreviewFeature1Element e, P p);
*
* // Sample diff for ElementKindVisitorPreview.java
* // Take the default action for a preview feature 1.
* +
* + /**
* + * {@inheritDoc ElementVisitor}
* + *
* + * @implSpec This implementation calls {@code defaultAction}.
* + *
* + * @param e {@inheritDoc ElementVisitor}
* + * @param p {@inheritDoc ElementVisitor}
* + * @return the result of {@code defaultAction}
* + * @since N
* + */
* + @Override
* + public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
* + return defaultAction(e, p);
* + }
*
* // Sample diff for ElementScannerPreview.java
* // Scan the enclosed elements of a preview feature 1.
* +
* + /**
* + * {@inheritDoc ElementVisitor}
* + *
* + * @implSpec This implementation scans the enclosed elements.
* + *
* + * @param e {@inheritDoc ElementVisitor}
* + * @param p {@inheritDoc ElementVisitor}
* + * @return {@inheritDoc ElementScanner6}
* + * @since N
* + */
* + @Override
* + public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
* + return scan(e.getEnclosedElements(), p);
* + }
*
* // Sample diff for SimpleElementVisitorPreview.java
* // Take the default action for a preview feature 1.
* + /**
* + * {@inheritDoc ElementVisitor}
* + *
* + * @implSpec Visits a {@code PreviewFeature1Element} by calling
* + * {@code defaultAction}.
* + *
* + * @param e {@inheritDoc ElementVisitor}
* + * @param p {@inheritDoc ElementVisitor}
* + * @return {@inheritDoc ElementVisitor}
* + * @since N
* + */
* + @Override
* + public R visitPreviewFeature1(PreviewFeature1Element e, P p) {
* + return defaultAction(e, p);
* + }
*
*
* When preview feature 1 exits preview in JDK (N+k), a set of
* visitors for language level (N+k) would be added. The
* methods operating over the feature would be moved from the preview
* visitors to the new language level (N+k) visitors. Each
* preview visitor would then have its direct superclass changed to
* the new corresponding (N+k) visitor.
*
*
* // Sample diff for ElementKind.java
* + /**
* + * A preview feature 2.
* + * @since N
* + */
* + PREVIEW_FEATURE_2,
* ...
* // Update existing methods as needed
* public boolean isVariable() {
* return switch(this) {
* case ENUM_CONSTANT, FIELD, PARAMETER,
* LOCAL_VARIABLE, EXCEPTION_PARAMETER, RESOURCE_VARIABLE,
* - BINDING_VARIABLE -> true;
* + BINDING_VARIABLE, PREVIEW_FEATURE_2 -> true;
* default -> false;
* };
* }
*
*
* The kind visitors need support for the new variety of element:
*
* // Update visitVariable in ElementKindVisitor6:
* ...
* * @implSpec This implementation dispatches to the visit method for
* * the specific {@linkplain ElementKind kind} of variable, {@code
* * ENUM_CONSTANT}, {@code EXCEPTION_PARAMETER}, {@code FIELD},
* - * {@code LOCAL_VARIABLE}, {@code PARAMETER}, or {@code RESOURCE_VARIABLE}.
* + * {@code LOCAL_VARIABLE}, {@code PARAMETER}, {@code RESOURCE_VARIABLE},
* + * or {@code PREVIEW_FEATURE_2}.
* *
* * @param e {@inheritDoc ElementVisitor}
* * @param p {@inheritDoc ElementVisitor}
* * @return the result of the kind-specific visit method
* */
* @Override
* public R visitVariable(VariableElement e, P p) {
* ...
* case BINDING_VARIABLE:
* return visitVariableAsBindingVariable(e, p);
*
* + case PREVIEW_FEATURE_2:
* + return visitVariableAsPreviewFeature2(e, p);
* +
* default:
* throw new AssertionError("Bad kind " + k + " for VariableElement" + e);
* ...
* + /**
* + * Visits a {@code PREVIEW_FEATURE_2} variable element.
* + *
* + * @implSpec This implementation calls {@code visitUnknown}.
* + *
* + * @param e the element to visit
* + * @param p a visitor-specified parameter
* + * @return the result of {@code visitUnknown}
* + *
* + * @since N
* + */
* + public R visitVariableAsPreviewFeature2(VariableElement e, P p) {
* + return visitUnknown(e, p);
* + }
*
*
* The preview element kind visitor in turn overrides {@code
* visitVariableAsPreviewFeature2}:
*
* // Sample diff for ElementKindVisitorPreview:
* + /**
* + * {@inheritDoc ElementKindVisitor6}
* + *
* + * @implSpec This implementation calls {@code defaultAction}.
* + *
* + * @param e {@inheritDoc ElementKindVisitor6}
* + * @param p {@inheritDoc ElementKindVisitor6}
* + * @return the result of {@code defaultAction}
* + *
* + * @since N
* + */
* + @Override
* + public R visitVariableAsPreviewFeature2(VariableElement e, P p) {
* + return defaultAction(e, p);
* + }
*
*
* As in the case where a new interface is introduced, when preview
* feature 2 exits preview in JDK (N+k), a set of visitors for
* language level (N+k) would be added. The methods operating
* over the new feature in the kind visitors would be moved from the
* preview visitors to new language level (N+k) visitors. Each
* preview visitor would then have its direct superclass changed to
* the new corresponding (N+k) visitor.
*
* @since 1.6
*
* @see
* JSR 269: Pluggable Annotation Processing API
*/
package javax.lang.model.util;