001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2024–2025 microBean™.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
006 * the License. You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
011 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
012 * specific language governing permissions and limitations under the License.
013 */
014package org.microbean.construct.element;
015
016import java.util.ArrayList;
017import java.util.Collection;
018import java.util.Collections;
019import java.util.List;
020import java.util.Optional;
021import java.util.Set;
022
023import java.util.function.Supplier;
024
025import javax.lang.model.element.Element;
026import javax.lang.model.element.ElementKind;
027import javax.lang.model.element.ElementVisitor;
028import javax.lang.model.element.ExecutableElement;
029import javax.lang.model.element.Modifier;
030import javax.lang.model.element.ModuleElement;
031import javax.lang.model.element.NestingKind;
032import javax.lang.model.element.PackageElement;
033import javax.lang.model.element.Parameterizable;
034import javax.lang.model.element.QualifiedNameable;
035import javax.lang.model.element.RecordComponentElement;
036import javax.lang.model.element.TypeElement;
037import javax.lang.model.element.TypeParameterElement;
038import javax.lang.model.element.VariableElement;
039
040import javax.lang.model.type.TypeKind;
041import javax.lang.model.type.TypeMirror;
042
043import org.microbean.construct.UniversalConstruct;
044import org.microbean.construct.Domain;
045
046import org.microbean.construct.type.UniversalType;
047
048/**
049 * An {@link Element} and {@link UniversalConstruct} implementation.
050 *
051 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
052 *
053 * @see Element#getKind()
054 *
055 * @see UniversalConstruct
056 */
057@SuppressWarnings("preview")
058public final class UniversalElement
059  extends UniversalConstruct<Element>
060  implements ExecutableElement,
061             ModuleElement,
062             PackageElement,
063             RecordComponentElement,
064             TypeElement,
065             TypeParameterElement,
066             VariableElement {
067
068  // volatile not needed
069  private Supplier<? extends List<? extends UniversalElement>> enclosedElementsSupplier;
070
071  /**
072   * Creates a new {@link UniversalElement}.
073   *
074   * @param delegate an {@link Element} to which operations will be delegated; must not be {@code null}
075   *
076   * @param domain a {@link Domain} from which the supplied {@code delegate} is presumed to have originated; must not be
077   * {@code null}
078   *
079   * @exception NullPointerException if either argument is {@code null}
080   *
081   * @see #delegate()
082   */
083  @SuppressWarnings("try")
084  public UniversalElement(final Element delegate, final Domain domain) {
085    super(delegate, domain);
086    this.enclosedElementsSupplier = () -> {
087      final List<? extends UniversalElement> ees;
088      try (var lock = domain.lock()) {
089        ees = this.wrap(this.delegate().getEnclosedElements());
090        this.enclosedElementsSupplier = () -> ees;
091      }
092      return ees;
093    };
094  }
095
096  @Override // Element
097  public final <R, P> R accept(final ElementVisitor<R, P> v, final P p) {
098    return switch (this.getKind()) {
099    case
100      ANNOTATION_TYPE,
101      CLASS,
102      ENUM,
103      INTERFACE,
104      RECORD                 -> v.visitType(this, p);
105    case TYPE_PARAMETER      -> v.visitTypeParameter(this, p);
106    case
107      BINDING_VARIABLE,
108      ENUM_CONSTANT,
109      EXCEPTION_PARAMETER,
110      FIELD, LOCAL_VARIABLE,
111      PARAMETER,
112      RESOURCE_VARIABLE      -> v.visitVariable(this, p);
113    case RECORD_COMPONENT    -> v.visitRecordComponent(this, p);
114    case
115      CONSTRUCTOR,
116      INSTANCE_INIT,
117      METHOD,
118      STATIC_INIT            -> v.visitExecutable(this, p);
119    case PACKAGE             -> v.visitPackage(this, p);
120    case MODULE              -> v.visitModule(this, p);
121    case OTHER               -> v.visitUnknown(this, p);
122    };
123  }
124
125  @Override // Element
126  public final UniversalType asType() {
127    return UniversalType.of(this.delegate().asType(), this.domain());
128  }
129
130  /**
131   * Returns {@code true} if and only if this {@link UniversalElement} is a <dfn>generic class declaration</dfn>.
132   *
133   * @return {@code true} if and only if this {@link UniversalElement} is a <dfn>generic class declaration</dfn>
134   *
135   * @spec https://docs.oracle.com/javase/specs/jls/se23/html/jls-8.html#jls-8.1.2 Java Language Specification, section
136   * 8.1.2
137   */
138  public final boolean generic() {
139    return switch (this.getKind()) {
140    case CLASS, CONSTRUCTOR, ENUM, INTERFACE, METHOD, RECORD -> !this.getTypeParameters().isEmpty();
141    default -> false;
142    };
143  }
144
145  @Override // RecordComponentElement
146  public final UniversalElement getAccessor() {
147    return switch (this.getKind()) {
148    case RECORD_COMPONENT -> this.wrap(((RecordComponentElement)this.delegate()).getAccessor());
149    default -> null;
150    };
151  }
152
153  @Override // TypeParameterElement
154  public final List<? extends UniversalType> getBounds() {
155    return switch (this.getKind()) {
156    case TYPE_PARAMETER -> UniversalType.of(((TypeParameterElement)this.delegate()).getBounds(), this.domain());
157    default -> List.of();
158    };
159  }
160
161  @Override // VariableElement
162  @SuppressWarnings("try")
163  public final Object getConstantValue() {
164    return switch (this.getKind()) {
165    case BINDING_VARIABLE, ENUM_CONSTANT, EXCEPTION_PARAMETER, FIELD, LOCAL_VARIABLE, PARAMETER, RESOURCE_VARIABLE -> {
166      try (var lock = this.domain().lock()) {
167        // There is a LOT going on here; take the domain lock for safety. See
168        // https://github.com/openjdk/jdk/blob/jdk-25%2B3/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Symbol.java#L1813-L1829
169        yield
170          ((VariableElement)this.delegate()).getConstantValue(); // will be a boxed type or String
171      }
172    }
173    default -> null;
174    };
175  }
176
177  @Override // ExecutableElement
178  public final UniversalAnnotationValue getDefaultValue() {
179    return switch (this.getKind()) {
180      // See
181      // https://github.com/openjdk/jdk/blob/jdk-25%2B3/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Symbol.java#L2287-L2290;
182      // no concurrent Name access so no lock needed
183    case METHOD -> UniversalAnnotationValue.of(((ExecutableElement)this.delegate()).getDefaultValue(), this.domain());
184    default -> null;
185    };
186  }
187
188  @Override // ModuleElement
189  public final List<? extends UniversalDirective> getDirectives() {
190    return switch (this.getKind()) {
191    case MODULE -> UniversalDirective.of(((ModuleElement)this.delegate()).getDirectives(), this.domain());
192    default -> List.of();
193    };
194  }
195
196  /*
197    java.lang.AssertionError: Filling jrt:/java.base/java/lang/String$CaseInsensitiveComparator.class during DirectoryFileObject[/modules/java.base:java/lang/Integer$IntegerCache.class]
198    at jdk.compiler/com.sun.tools.javac.util.Assert.error(Assert.java:162)
199    at jdk.compiler/com.sun.tools.javac.code.ClassFinder.fillIn(ClassFinder.java:366)
200    at jdk.compiler/com.sun.tools.javac.code.ClassFinder.complete(ClassFinder.java:302)
201    at jdk.compiler/com.sun.tools.javac.code.Symbol.complete(Symbol.java:687)
202    at jdk.compiler/com.sun.tools.javac.code.Symbol$ClassSymbol.complete(Symbol.java:1455)
203    at jdk.compiler/com.sun.tools.javac.code.Symbol.apiComplete(Symbol.java:693)
204    at jdk.compiler/com.sun.tools.javac.code.Symbol$TypeSymbol.getEnclosedElements(Symbol.java:864)
205    at jdk.compiler/com.sun.tools.javac.code.Symbol$ClassSymbol.getEnclosedElements(Symbol.java:1420)
206    at jdk.compiler/com.sun.tools.javac.code.Symbol$ClassSymbol.getEnclosedElements(Symbol.java:1264)
207    at org.microbean.construct@0.0.10-SNAPSHOT/org.microbean.construct.element.UniversalElement.getEnclosedElements(UniversalElement.java:195)
208  */
209  // See https://github.com/microbean/microbean-construct/issues/18
210  @Override // Element
211  public final List<? extends UniversalElement> getEnclosedElements() {
212    return this.enclosedElementsSupplier.get();
213  }
214
215  @Override // Element
216  public final UniversalElement getEnclosingElement() {
217    return this.wrap(this.delegate().getEnclosingElement());
218  }
219
220  @Override // TypeParameterElement
221  public final UniversalElement getGenericElement() {
222    return switch (this.getKind()) {
223    case TYPE_PARAMETER -> this.wrap(((TypeParameterElement)this.delegate()).getGenericElement());
224    default -> this.getEnclosingElement(); // illegal state
225    };
226  }
227
228  @Override // TypeElement
229  public final List<? extends UniversalType> getInterfaces() {
230    return switch (this.getKind()) {
231    case ANNOTATION_TYPE, CLASS, ENUM, INTERFACE, RECORD ->
232      UniversalType.of(((TypeElement)this.delegate()).getInterfaces(), this.domain());
233    default -> List.of();
234    };
235  }
236
237  @Override // Element
238  public final ElementKind getKind() {
239    return this.delegate().getKind();
240  }
241
242  @Override // Element
243  public final Set<Modifier> getModifiers() {
244    return this.delegate().getModifiers();
245  }
246
247  @Override // TypeElement
248  public final NestingKind getNestingKind() {
249    return switch (this.getKind()) {
250    case ANNOTATION_TYPE, CLASS, ENUM, INTERFACE, RECORD -> ((TypeElement)this.delegate()).getNestingKind();
251    default -> NestingKind.TOP_LEVEL; // illegal state
252    };
253  }
254
255  @Override // ExecutableElement
256  public final List<? extends UniversalElement> getParameters() {
257    return switch (this.getKind()) {
258    case CONSTRUCTOR, METHOD -> this.wrap(((ExecutableElement)this.delegate()).getParameters());
259    default -> List.of();
260    };
261  }
262
263  @Override // ModuleElement, PackageElement, TypeElement
264  @SuppressWarnings("try")
265  public final StringName getQualifiedName() {
266    return switch (this.getKind()) {
267    case ANNOTATION_TYPE, CLASS, ENUM, INTERFACE, MODULE, PACKAGE, RECORD -> {
268      try (var lock = this.domain().lock()) {
269        yield StringName.of(((QualifiedNameable)this.delegate()).getQualifiedName().toString(), this.domain());
270      }
271    }
272    default -> StringName.of("", this.domain());
273    };
274  }
275
276  @Override // ExecutableElement
277  public final UniversalType getReceiverType() {
278    return
279      this.getKind().isExecutable() ?
280      UniversalType.of(this.asType(), this.domain()).getReceiverType() :
281      UniversalType.of(this.domain().noType(TypeKind.NONE), this.domain());
282  }
283
284  @Override // TypeElement
285  public final List<? extends UniversalElement> getRecordComponents() {
286    return switch (this.getKind()) {
287    case RECORD -> this.wrap(((TypeElement)this.delegate()).getRecordComponents());
288    default -> List.of();
289    };
290  }
291
292  @Override // ExecutableElement
293  public final UniversalType getReturnType() {
294    return UniversalType.of(this.asType(), this.domain()).getReturnType();
295  }
296
297  @Override // Element
298  @SuppressWarnings("try")
299  public final StringName getSimpleName() {
300    try (var lock = this.domain().lock()) {
301      return new StringName(this.delegate().getSimpleName().toString(), this.domain());
302    }
303  }
304
305  @Override // TypeElement
306  public final UniversalType getSuperclass() {
307    return switch (this.getKind()) {
308    case ANNOTATION_TYPE, CLASS, ENUM, INTERFACE, RECORD ->
309      UniversalType.of(((TypeElement)this.delegate()).getSuperclass(), this.domain());
310    default -> UniversalType.of(this.domain().noType(TypeKind.NONE), this.domain());
311    };
312  }
313
314  @Override // ExecutableElement
315  public final List<? extends UniversalType> getThrownTypes() {
316    return
317      this.getKind().isExecutable() ?
318      UniversalType.of(((ExecutableElement)this.delegate()).getThrownTypes(), this.domain()) :
319      List.of();
320  }
321
322  @Override // ExecutableElement
323  public final List<? extends UniversalElement> getTypeParameters() {
324    return switch (this.getKind()) {
325    case CLASS, CONSTRUCTOR, ENUM, INTERFACE, RECORD, METHOD ->
326      this.wrap(((Parameterizable)this.delegate()).getTypeParameters());
327    default -> List.of();
328    };
329  }
330
331  @Override // ExecutableElement
332  public final boolean isDefault() {
333    return switch (this.getKind()) {
334    case METHOD -> ((ExecutableElement)this.delegate()).isDefault();
335    default -> false;
336    };
337  }
338
339  @Override // ModuleElement
340  public final boolean isOpen() {
341    return switch (this.getKind()) {
342    case MODULE -> ((ModuleElement)this.delegate()).isOpen();
343    default -> false;
344    };
345  }
346
347  @Override // ModuleElement, PackageElement
348  public final boolean isUnnamed() {
349    return switch (this.getKind()) {
350    case MODULE  -> ((ModuleElement)this.delegate()).isUnnamed();
351    case PACKAGE -> ((PackageElement)this.delegate()).isUnnamed();
352    default -> false;
353    };
354  }
355
356  @Override // ExecutableElement
357  public final boolean isVarArgs() {
358    return switch (this.getKind()) {
359    case CONSTRUCTOR, METHOD -> ((ExecutableElement)this.delegate()).isVarArgs();
360    default -> false;
361    };
362  }
363
364  /**
365   * A convenience method that returns {@code true} if this {@link UniversalElement} represents the class declaration
366   * for {@code java.lang.Object}.
367   *
368   * @return {@code true} if this {@link UniversalElement} is the class declaration for {@code java.lang.Object}
369   */
370  public final boolean javaLangObject() {
371    return switch (this.getKind()) {
372    case CLASS -> this.getQualifiedName().contentEquals("java.lang.Object");
373    default -> false;
374    };
375  }
376
377  private final UniversalElement wrap(final Element e) {
378    return of(e, this.domain());
379  }
380
381  private final List<? extends UniversalElement> wrap(final Collection<? extends Element> es) {
382    return of(es, this.domain());
383  }
384
385
386  /*
387   * Static methods.
388   */
389
390
391  /**
392   * Returns a non-{@code null}, immutable {@link List} of {@link UniversalElement}s whose elements wrap the supplied
393   * {@link List}'s elements.
394   *
395   * @param es a {@link Collection} of {@link Element}s; must not be {@code null}
396   *
397   * @param domain a {@link Domain}; must not be {@code null}
398   *
399   * @return a non-{@code null}, immutable {@link List} of {@link UniversalElement}s
400   *
401   * @exception NullPointerException if either argument is {@code null}
402   */
403  public static final List<? extends UniversalElement> of(final Collection<? extends Element> es, final Domain domain) {
404    if (es.isEmpty()) {
405      return List.of();
406    }
407    final List<UniversalElement> newEs = new ArrayList<>(es.size());
408    for (final Element e : es) {
409      newEs.add(of(e, domain));
410    }
411    return Collections.unmodifiableList(newEs);
412  }
413
414  /**
415   * Returns a {@link UniversalElement} that is either the supplied {@link Element} (if it itself is {@code null} or is
416   * a {@link UniversalElement}) or one that wraps it.
417   *
418   * @param e an {@link Element}; may be {@code null} in which case {@code null} will be returned
419   *
420   * @param domain a {@link Domain}; must not be {@code null}
421   *
422   * @return a {@link UniversalElement}, or {@code null} (if {@code e} is {@code null})
423   *
424   * @exception NullPointerException if {@code domain} is {@code null}
425   *
426   * @see #UniversalElement(Element, Domain)
427   */
428  public static final UniversalElement of(final Element e, final Domain domain) {
429    return switch (e) {
430    case null -> null;
431    case UniversalElement ue -> ue;
432    default -> new UniversalElement(e, domain);
433    };
434  }
435
436}