By default, {@link Aggregate}s have {@linkplain #EMPTY_DEPENDENCIES no dependencies}.
* @@ -45,9 +49,9 @@ public interface Aggregate { public static final SequencedSetIf an {@link AttributedElement} in the set returns a {@link javax.lang.model.element.TypeElement} from its - * {@link AttributedElement#element()} method that represents this {@link Aggregate} implementation, undefined - * behavior, including the possibility of infinite loops, may result (an {@link Aggregate} may not have itself as a - * dependency).
+ *If an {@link Annotated Annotated<? extends Element>} in the set represents this very {@link Aggregate} + * implementation, undefined behavior, including the possibility of infinite loops, may result (an {@link Aggregate} + * may not have itself as a dependency).
* - *Note that it is permissible for an {@link AttributedElement} in the set to refer to another type by returning a - * {@link javax.lang.model.element.TypeElement} from its {@link AttributedElement#element()} method.
+ *Note that it is permissible for an {@link Annotated Annotated<? extends Element>} in the set to represent + * another type.
* *The default implementation of this method returns the value of the {@link #EMPTY_DEPENDENCIES} field.
* - * @return an immutable, determinate, {@link SequencedSet} of {@link AttributedElement} instances; never {@code null} + * @return an immutable, determinate, {@link SequencedSet} of {@link Annotated Annotated<? extends Element>} + * instances; never {@code null} + * + * @see Annotated * - * @see AttributedElement + * @see Annotated#of(AnnotatedConstruct) */ - public default SequencedSetNote: Undefined behavior may result if an {@link AttributedElement} in the {@linkplain - * #dependencies() dependencies} represents this {@link Aggregate} implementation (an {@link Aggregate} may not have - * itself as a dependency).
+ *Note: Undefined behavior may result if an {@link Annotated Annotated<? extends Element>} + * in the {@linkplain #dependencies() dependencies} represents this {@link Aggregate} implementation (an {@link + * Aggregate} may not have itself as a dependency).
* *Typically there is no need to override this method.
* *Usage of this method is not required.
* - * @param r a {@link Function} that retrieves a contextual reference suitable for an {@link AttributedType}; if {@link - * #dependencies()} returns a non-empty {@link SequencedSet} then this argument must not be {@code null} + * @param r a {@link Function} that retrieves a contextual reference suitable for an {@link Annotated Annotated<? + * extends AnnotatedConstruct>}; if {@link #dependencies()} returns a non-empty {@link SequencedSet} then this + * argument must not be {@code null} * * @return an immutable {@link SequencedSet} of {@link Assignment} instances; never {@code null} * * @exception NullPointerException if {@code r} is {@code null} */ // (Convenience.) - public default SequencedSet> assign(final Function r) { - final Collection ds = this.dependencies(); + public default SequencedSet> assign(final Function, ?> r) { + final Collection> ds = this.dependencies(); if (ds == null || ds.isEmpty()) { return EMPTY_ASSIGNMENTS; } final SequencedSetSemantically significant annotations are included in hashcode and equality computations.
+ * + * @paramThese annotations supersede any annotations that might otherwise be available from objects returned by the + * {@link #annotated()} method.
+ * + * @return a non-{@code null}, immutable, determinate {@link List} of semantically significant {@link + * AnnotationMirror}s. + */ + public ListOptional} if it could not be described.
- *
- * @return an {@link Optional} containing a {@link ConstantDesc} describing this {@link AttributedType}, or an
- * {@linkplain Optional#isEmpty() empty Optional} if it could not be describe; never {@code null}
- */
- @Override // Constable
- public Optional describeConstable() {
- return this.element() instanceof Constable e ? e.describeConstable() : Optional.Optional} if it could not be described.
- *
- * @return an {@link Optional} containing a {@link ConstantDesc} describing this {@link AttributedType}, or an
- * {@linkplain Optional#isEmpty() empty Optional} if it could not be describe; never {@code null}
- */
- @Override // Constable
- public Optional describeConstable() {
- return this.type() instanceof Constable t ? t.describeConstable() : Optional.Implementations of this method must not return {@code null}.
- * - *Implementations of this method must return a determinate value.
- * - *Implementations of this method must be safe for concurrent use by multiple threads.
- * - * @return a non-{@code null} {@link AttributedType} - * - * @see AttributedType - */ - public AttributedType attributedType(); - -} diff --git a/src/main/java/org/microbean/assign/CacheableAnnotatedConstruct.java b/src/main/java/org/microbean/assign/CacheableAnnotatedConstruct.java new file mode 100644 index 0000000..bb2b452 --- /dev/null +++ b/src/main/java/org/microbean/assign/CacheableAnnotatedConstruct.java @@ -0,0 +1,164 @@ +/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- + * + * Copyright © 2026 microBean™. + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on + * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the + * specific language governing permissions and limitations under the License. + */ +package org.microbean.assign; + +import java.util.ArrayList; +import java.util.List; +import java.util.Objects; + +import java.util.function.Predicate; + +import javax.lang.model.AnnotatedConstruct; + +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; + +import org.microbean.construct.element.AnnotationMirrors; + +import static org.microbean.construct.element.AnnotationMirrors.containsAll; +import static org.microbean.construct.element.AnnotationMirrors.sameAnnotation; + +/** + * An {@link Annotated} implementation wrapping an {@link AnnotatedConstruct}. + * + * @author Laird Nelson + */ +// This deliberately doesn't implement TypeMirror or Element and delegate operations since it is used only for caching. +// It would be nice to ensure this class does not have to be public. +// This class may become an inner or nested class of something else. +final class CacheableAnnotatedConstructTwo {@link CacheableAnnotatedConstruct}s are considered equal when their {@linkplain #annotated() annotated object}s are + * {@linkplain Object#equals(Object) equal} and when each {@link AnnotationMirror} is the {@linkplain + * AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) same as} every other {@link + * AnnotationMirror}.
+ * + * @param other the {@link Object} to test; may be {@code null} in which case {@code false} will be returned + * + * @return {@code true} if and only if the supplied {@link Object} is equal to this {@link CacheableAnnotatedConstruct} + * + * @see AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) + */ + @Override // Object + public final boolean equals(final Object other) { + return this == other || switch (other) { + case null -> false; + case CacheableAnnotatedConstruct her -> + this.getClass() == her.getClass() && + Objects.equals(this.annotated(), her.annotated()) && + containsAll(this.annotations(), her.annotations(), this.p) && + containsAll(her.annotations(), this.annotations(), her.p); + default -> false; + }; + } + + /** + * Returns a non-zero hashcode for this {@link CacheableAnnotatedConstruct} based on both its {@linkplain + * #annotations() annotations} and its {@linkplain #annotated() annotated object}. + * + * @return a non-zero hashcode for this {@link CacheableAnnotatedConstruct} based on both its {@linkplain + * #annotations() annotations} and its {@linkplain #annotated() annotated object} + * + * @see #annotations() + * + * @see #annotated() + * + * @see AnnotationMirrors#hashCode(AnnotationMirror, Predicate) + */ + @Override // Object + public final int hashCode() { + if (this.hashCode == 0) { // volatile not needed, computation is determinate and deterministic + int hashCode = 17 * 31 + (this.annotated == null ? 0 : this.annotated().hashCode()); + for (final AnnotationMirror a : this.annotations()) { + hashCode = 17 * hashCode + AnnotationMirrors.hashCode(a, this.p); + } + this.hashCode = hashCode; + } + return hashCode; + } + + @Override // Object + public final String toString() { + return this.annotations() + " " + this.annotated(); + } + +} diff --git a/src/main/java/org/microbean/assign/Matcher.java b/src/main/java/org/microbean/assign/Matcher.java index 30166a3..4d85101 100644 --- a/src/main/java/org/microbean/assign/Matcher.java +++ b/src/main/java/org/microbean/assign/Matcher.java @@ -1,6 +1,6 @@ /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- * - * Copyright © 2025 microBean™. + * Copyright © 2025–2026 microBean™. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at @@ -19,16 +19,16 @@ * A {@link BiPredicate} with particular semantics associated with its {@link #test(Object, Object) test(Object, * Object)} method. * - * @param the criteria object + * @paramThe order of arguments may therefore be significant for {@link Matcher} implementations that do not represent * equality tests.
* - * @param a an object serving as a kind of criteria; must not be {@code null} + * @param c an object serving as a kind of criteria; must not be {@code null} * - * @param b an object to test against the criteria; must not be {@code null} + * @param t an object to test against the criteria; must not be {@code null} * * @return {@code true} if and only if the second argument matches the first argument; {@code false} * otherwise * - * @exception NullPointerException if either {@code a} or {@code b} is {@code null} + * @exception NullPointerException if either {@code c} or {@code t} is {@code null} * * @exception IllegalArgumentException if either non-{@code null} argument is unsuitable for any reason */ - @Override // BiPredicateThe returned {@link Attributes} may be the supplied {@link Attributes} or a different instance.
+ * @param c a non-{@code null} {@link Collection} of {@link AnnotationMirror}s * - * @param a an {@link Attributes}; must not be {@code null} + * @param a a non-{@code null} {@link AnnotationMirror} * - * @return an {@link Attributes} that is {@linkplain Attributes#equals(Object) equal to} the supplied {@link - * Attributes}; never {@code null} + * @return {@code true} if and only if the supplied {@link Collection} of {@link AnnotationMirror}s contains an {@link + * AnnotationMirror} that is {@linkplain AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, + * Predicate) the same} as the supplied {@link AnnotationMirror} * - * @exception NullPointerException if {@code a} is {@code null} + * @exception NullPointerException if {@code c} or {@code a} is {@code null} + * + * @see AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) + * + * @see AnnotationMirrors#contains(Collection, AnnotationMirror, Predicate) + * + * @see #Qualifiers(Domain, AnnotationMirror, Predicate) */ - public Attributes normalize(final Attributes a) { - return switch (a) { - case null -> throw new NullPointerException("a"); - case Attributes q when this.qualifier().equals(q) -> this.qualifier(); - default -> a; - }; + public final boolean contains(final Collection c, final AnnotationMirror a) { + return AnnotationMirrors.contains(c, a, this.annotationElementInclusionPredicate); } /** - * Returns an immutable {@link List} of {@link Attributes}s that is {@linkplain List#equals(Object) equal to} the - * supplied {@link List}. + * Returns {@code true} if and only if {@code c0} contains all {@linkplain + * AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) the same} {@link AnnotationMirror}s + * as are found in {@code c1}, + * + * @param c0 a non-{@code null} {@link Collection} of {@link AnnotationMirror}s * - *The returned {@link List} may be the supplied {@link List} or a different instance.
+ * @param c1 a non-{@code null} {@link Collection} of {@link AnnotationMirror}s * - * @param list a {@link List} of {@link Attributes}s; must not be {@code null} + * @return {@code true} if and only if {@code c0} contains all {@linkplain + * AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) the same} {@link AnnotationMirror}s + * as are found in {@code c1} * - * @return an immutable {@link List} of {@link Attributes}s that is {@linkplain List#equals(Object) equal to} the - * supplied {@link List}; never {@code null} + * @exception NullPointerException if either {@code c0} or {@code c1} is {@code null} * - * @exception NullPointerException if {@code list} is {@code null} + * @see AnnotationMirrors#sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) + * + * @see AnnotationMirrors#containsAll(Collection, Collection, Predicate) + * + * @see #Qualifiers(Domain, AnnotationMirror, Predicate) */ - public ListImplementations of this method must be idempotent and must return a determinate value.
+ *Implementations of this method must be idempotent and must be stable, i. e. return a + * determinate value.
* *Implementations of this method must not return {@code null}.
* * @param criteria the criteria to use; may be {@code null} to indicate no particular criteria should be used during * selection * - * @return an immutable sublist of this {@link Selectable}'s elements effectively selected by the supplied {@code - * criteria}; never {@code null} + * @return a non-{@code null}, immutable, determinate sublist of this {@link Selectable}'s elements effectively selected by the + * supplied {@code criteria} */ // Filters this thing according to the supplied criteria, producing a List. // List not Stream to permit caching diff --git a/src/main/java/org/microbean/assign/Selectables.java b/src/main/java/org/microbean/assign/Selectables.java index 040ca6a..1edcf12 100644 --- a/src/main/java/org/microbean/assign/Selectables.java +++ b/src/main/java/org/microbean/assign/Selectables.java @@ -1,6 +1,6 @@ /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- * - * Copyright © 2025 microBean™. + * Copyright © 2025–2026 microBean™. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at @@ -13,6 +13,7 @@ */ package org.microbean.assign; +import java.util.ArrayList; import java.util.Collection; import java.util.List; import java.util.Map; @@ -23,6 +24,15 @@ import java.util.function.BiFunction; import java.util.function.BiPredicate; import java.util.function.Function; +import java.util.function.Predicate; + +import javax.lang.model.AnnotatedConstruct; + +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; + +import static java.util.Objects.requireNonNull; /** * Utility methods for working with {@link Selectable}s. @@ -36,7 +46,7 @@ public final class Selectables { private Selectables() { super(); } - + /** * Returns a {@link Selectable} that caches its results. * @@ -54,7 +64,7 @@ private Selectables() { * * @see #caching(Selectable, BiFunction) */ - public staticThe {@link Selectable} instances returned by this method may or may not cache their selections.
* - *The selector must (indirectly) designate a sublist from the supplied {@link Collection} as mediated by the - * supplied criteria. The selector must additionally be idempotent and must produce a determinate value when given the - * same arguments.
+ *The selector tests its first argument to see if it is selected by its second argument. The selector + * is invoked repeatedly. If, for any given invocation, the first argument is selected, the selected element is added + * to the selection that is eventually returned as a sublist of the supplied {@link Collection}. The selector must + * additionally be idempotent and must produce a determinate value when given the same arguments.
* *No validation of these semantics of the selector is performed.
* @@ -132,9 +202,38 @@ private static finalNo element in the returned {@link List} will be {@code null}.
* @@ -204,9 +200,9 @@ private final boolean isInterface(final TypeMirror t) { * * * - * @param t a {@link TypeMirror}; must not be {@code null} + * @param t a non-{@code null} {@link TypeMirror} * - * @return a non-{@code null} {@link SupertypeList} of the supertypes of the supplied {@link TypeMirror} + * @return a non-{@code null}, determinate {@link SupertypeList} of the supertypes of the supplied {@link TypeMirror} * * @exception NullPointerException if {@code t} is {@code null} * @@ -225,8 +221,8 @@ public final SupertypeList supertypes(final TypeMirror t) { } /** - * Returns a non-{@code null} {@link SupertypeList} of the supertypes of the supplied {@link TypeMirror}, filtered - * using the supplied {@link Predicate}. + * Returns a non-{@code null}, determinate {@link SupertypeList} of the supertypes of the supplied {@link TypeMirror}, + * filtered using the supplied {@link Predicate}. * *No element in the returned {@link SupertypeList} will be {@code null}.
* @@ -236,8 +232,6 @@ public final SupertypeList supertypes(final TypeMirror t) { *No two elements in the list will be {@linkplain Objects#equals(Object) equal} or {@linkplain * Domain#sameType(TypeMirror, TypeMirror) the same type}. (The {@link SupertypeList} is an ordered set.)
* - *This method returns determinate values.
- * *The elements of the returned {@link SupertypeList} will be in the following (partial) order:
* *Erased name is not a term defined or used by the Java Language Specification. Its definition and * contract follow.
@@ -382,9 +377,9 @@ private static final String erasedName(final QualifiedNameable qn) { *The erased name of any other {@link TypeMirror} is the return value of an invocation of its {@link * Object#toString() toString()} method.
* - * @param t a {@link TypeMirror}; must not be {@code null} + * @param t a non-{@code null} {@link TypeMirror} * - * @return the erased name of the supplied {@link TypeMirror}; never {@code null} + * @return the non-{@code null}, determinate erased name of the supplied {@link TypeMirror} * * @exception NullPointerException if {@code t} is {@code null} */ @@ -413,7 +408,7 @@ public static final String erasedName(final TypeMirror t) { }; } - private static final