By default, {@link Aggregate}s have {@linkplain #EMPTY_DEPENDENCIES no dependencies}.
- * - * @author Laird Nelson - * - * @see #dependencies() - */ -public interface Aggregate { - - - /* - * Static fields. - */ - - - /** - * An immutable, empty {@link SequencedSet} of {@link Assignment}s. - */ - public static final SequencedSetTypically there is no need to override this method.
- * - * @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} - * - * @return an immutable {@link SequencedSet} of {@link Assignment} instances; never {@code null} - * - * @exception NullPointerException if {@code r} is {@code null} - * - * @see References - */ - public default SequencedSet> assign(final Function r) { - final Collection ds = this.dependencies(); - if (ds == null || ds.isEmpty()) { - return EMPTY_ASSIGNMENTS; - } - final SequencedSetOptional} 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 may return {@code null}.
* diff --git a/src/main/java/org/microbean/bean/Factory.java b/src/main/java/org/microbean/bean/Factory.java index b743687..6323804 100644 --- a/src/main/java/org/microbean/bean/Factory.java +++ b/src/main/java/org/microbean/bean/Factory.java @@ -21,6 +21,8 @@ import java.util.Optional; +import org.microbean.assign.Aggregate; + import static java.lang.constant.ConstantDescs.BSM_INVOKE; /** diff --git a/src/main/java/org/microbean/bean/Id.java b/src/main/java/org/microbean/bean/Id.java index 0bf8db2..94aca55 100644 --- a/src/main/java/org/microbean/bean/Id.java +++ b/src/main/java/org/microbean/bean/Id.java @@ -13,9 +13,7 @@ */ package org.microbean.bean; -import java.lang.constant.ClassDesc; import java.lang.constant.Constable; -import java.lang.constant.ConstantDesc; import java.lang.constant.DynamicConstantDesc; import java.lang.constant.MethodHandleDesc; diff --git a/src/main/java/org/microbean/bean/IdMatcher.java b/src/main/java/org/microbean/bean/IdMatcher.java index a7a70da..792b62f 100644 --- a/src/main/java/org/microbean/bean/IdMatcher.java +++ b/src/main/java/org/microbean/bean/IdMatcher.java @@ -18,6 +18,7 @@ import javax.lang.model.type.TypeMirror; +import org.microbean.assign.AttributedType; import org.microbean.assign.Matcher; import org.microbean.attributes.Attributes; @@ -31,38 +32,53 @@ * * @see BeanQualifiersMatcher * - * @see InterceptorBindingsMatcher - * * @see BeanTypeMatcher * + * @see Matcher + * * @see Id */ public final class IdMatcher implements MatcherAttributedType's attributes} and the supplied {@linkplain Id#attributes() Id's
* attributes} returns {@code true}AttributedType's attributes} and the supplied {@linkplain Id#attributes() Id's
- * attributes} returns {@code true}AttributedType's type} and the supplied {@linkplain Id#attributes()
@@ -102,20 +116,16 @@ public IdMatcher(final BeanQualifiersMatcher qm,
*
* @see BeanQualifiersMatcher#test(Collection, Collection)
*
- * @see InterceptorBindingsMatcher#test(Collection, Collection)
- *
* @see #test(TypeMirror, Iterable)
*
* @see BeanTypeMatcher#test(TypeMirror, TypeMirror)
*/
@Override // MatcherA {@link TypeMirror} t from the supplied {@link Iterable} matches the supplied {@code type}
* argument if an invocation of the {@link BeanTypeMatcher#test(TypeMirror, TypeMirror)} method invoked on the
- * {@linkplain #IdMatcher(BeanQualifiersMatcher, InterceptorBindingsMatcher, BeanTypeMatcher)
+ * {@linkplain #IdMatcher(BeanTypeMatcher, BeanQualifiersMatcher, InterceptorBindingsMatcher)
* BeanTypeManager supplied at construction time} supplied with {@code type} and t returns
* {@code true}.
The default implementation of this method returns the value of an invocation of the {@link - * InterceptorBindings#interceptorBindings(Collection)} method.
- * - * @param as a {@link Collection}; must not be {@code null} - * - * @return a {@link List} of interceptor bindings; never {@code null} - * - * @exception NullPointerException if {@code as} is {@code null} - */ - protected Collection interceptorBindings(final Collection as) { - return InterceptorBindings.interceptorBindings(as); - } - -} diff --git a/src/main/java/org/microbean/bean/Ranked.java b/src/main/java/org/microbean/bean/Ranked.java index 2df569e..8d76910 100644 --- a/src/main/java/org/microbean/bean/Ranked.java +++ b/src/main/java/org/microbean/bean/Ranked.java @@ -35,7 +35,10 @@ * @see #outranks(int) * * @see #outranks(int, int) + * + * @deprecated This class is deprecated for future removal. */ +@Deprecated public interface Ranked { diff --git a/src/main/java/org/microbean/bean/RankedReducer.java b/src/main/java/org/microbean/bean/RankedReducer.java deleted file mode 100644 index 4c84b0a..0000000 --- a/src/main/java/org/microbean/bean/RankedReducer.java +++ /dev/null @@ -1,185 +0,0 @@ -/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*- - * - * Copyright © 2024–2025 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.bean; - -import java.util.ArrayList; -import java.util.List; - -import java.util.function.BiFunction; - -import static java.util.Collections.unmodifiableList; - -import static org.microbean.bean.Ranked.DEFAULT_RANK; - -/** - * A {@link Reducer} implementation that works with {@link Ranked} objects. - * - * @paramThe reduction may be a simple filtering operation, or may be a summing or aggregating operation, or anything - * else.
- * - *This interface is conceptually subordinate to, but should not be confused with, the {@link Reducible} - * interface.
- * - *{@link Reducer} implementations are often used to help build {@link Reducible} implementations. See, for example, - * {@link Reducible#ofCaching(Selectable, Reducer, BiFunction)}.
- * - * @paramImplementations of this method must return determinate values.
- * - * @param elements an immutable {@link List} to reduce; must not be {@code null}; represents a successful selection - * from a larger collection of elements - * - * @param c the criteria effectively describing the initial selection and the desired reduction; may be {@code null} - * to indicate no criteria; may be ignored if not needed by an implementation - * - * @param failureHandler a {@link BiFunction} receiving a failed reduction (usually a portion of the supplied {@code - * elements}), and the selection and reduction criteria, that returns a substitute reduction (or, more commonly, - * throws an exception); must not be {@code null}; must be invoked if reduction fails or undefined behavior may result - * - * @return a single, possibly {@code null}, element normally drawn or computed from the supplied {@code elements}, or - * a synthetic value returned by an invocation of the supplied {@code failureHandler}'s {@link - * BiFunction#apply(Object, Object) apply(Object, Object)} method - * - * @exception NullPointerException if {@code elements} or {@code failureHandler} is {@code null} - * - * @exception ReductionException if the {@code failureHandler} function throws a {@link ReductionException} - * - * @see #fail(List, Object) - */ - // List, not Stream, for equality semantics and caching purposes. - // List, not Set, because it's much faster and reduction can take care of duplicates if needed - // List, not Collection, because you want easy access to the (possibly) only element without creating iterators - // C, not Predicate, because it may not be necessary to actually filter the List to perform the reduction - // failureHandler will receive only those elements that could not be eliminated - // c is a pass-through used only during failure - public T reduce(final List elements, - final C c, - final BiFunction, ? super C, ? extends T> failureHandler); - - - /* - * Default methods. - */ - - - /** - * Invokes the {@link #reduce(List, Object, BiFunction)} method with the return value of an invocation of the {@link - * Selectable#select(Object) select(Object)} method on the supplied {@link Selectable} supplied with {@code c}, and - * the supplied {@code c} and {@code failureHandler} arguments, and returns the result. - * - * @param f a {@link Selectable}; must not be {@code null} - * - * @param c the criteria effectively describing the initial selection and the desired reduction; may be {@code null} - * to indicate no criteria; may be ignored if not needed by an implementation - * - * @param failureHandler a {@link BiFunction} receiving a failed reduction (usually a portion of the supplied {@code - * elements}), and the selection and reduction criteria, that returns a substitute reduction (or, more commonly, - * throws an exception); must not be {@code null}; must be invoked if reduction fails or undefined behavior may result - * - * @return a single, possibly {@code null}, element normally drawn or computed from the {@link List} returned from the - * supplied {@link Selectable}'s {@link Selectable#select(Object) select(Object)} method, or a synthetic value - * returned by an invocation of the supplied {@code failureHandler}'s {@link BiFunction#apply(Object, Object) - * apply(Object, Object)} method - * - * @exception NullPointerException if {@code f} or {@code failureHandler} is {@code null} - * - * @see #reduce(List, Object, BiFunction) - */ - public default T reduce(final Selectable f, - final C c, - final BiFunction, ? super C, ? extends T> failureHandler) { - return this.reduce(f.select(c), c, failureHandler); - } - - /** - * Invokes the {@link #reduce(List, Object, BiFunction)} method with the return value of an invocation of the {@link - * Selectable#select(Object) select(Object)} method on the supplied {@link Selectable} supplied with {@code c}, and - * the supplied {@code c} and a reference to the {@link #fail(List, Object) fail(List, Object)} method, and returns - * the result. - * - * @param f a {@link Selectable}; must not be {@code null} - * - * @param c the criteria effectively describing the initial selection and the desired reduction; may be {@code null} - * to indicate no criteria; may be ignored if not needed by an implementation - * - * @return a single, possibly {@code null}, element normally drawn or computed from the {@link List} returned from the - * supplied {@link Selectable}'s {@link Selectable#select(Object) select(Object)} method, or the sole element - * returned by an invocation of the {@link #fail(List, Object) fail(List, Object)} method - * - * @exception NullPointerException if {@code f} or {@code failureHandler} is {@code null} - * - * @exception UnsatisfiedReductionException if an invocation of the {@link #fail(List, Object) fail(List, Object)} method throws an {@link UnsatisfiedReductionException} - * - * @exception AmbiguousReductionException if an invocation of the {@link #fail(List, Object) fail(List, Object)} method throws an {@link AmbiguousReductionException} - * - * @see #reduce(Selectable, Object, BiFunction) - * - * @see #fail(List, Object) - */ - public default T reduce(final Selectable f, final C c) { - return this.reduce(f, c, Reducer::fail); - } - - /** - * Invokes the {@link #reduce(List, Object, BiFunction)} method with the supplied arguments and a reference to the - * {@link #fail(List, Object)} method, and returns the result. - * - * @param elements an immutable {@link List} to reduce; must not be {@code null}; represents a successful selection - * from a larger collection of elements - * - * @param c the criteria effectively describing the initial selection and the desired reduction; may be {@code null} - * to indicate no criteria; may be ignored if not needed by an implementation - * - * @return a single, possibly {@code null}, element normally drawn or computed from the supplied {@code elements}, or - * a synthetic value returned by an invocation of the supplied {@code failureHandler}'s {@link - * BiFunction#apply(Object, Object) apply(Object, Object)} method - * - * @exception NullPointerException if {@code elements} is {@code null} - * - * @see #fail(List, Object) - * - * @see #reduce(List, Object, BiFunction) - */ - public default T reduce(final List elements, final C c) { - return this.reduce(elements, c, Reducer::fail); - } - - - /* - * Static methods. - */ - - - /** - * Returns a {@link Reducer} whose {@link #reduce(List, Object, BiFunction)} method, for a given {@link List} of - * elements, returns the {@link List}'s sole element if the {@link List} has exactly one element, and returns the - * result of invoking its supplied failure handler otherwise. - * - * @paramA reference to this method is often used as a failure handler in an invocation of the {@link - * #reduce(List, Object, BiFunction)} method.
- * - * @paramA reference to this method can be used as a failure handler in an invocation of the {@link - * #reduce(List, Object, BiFunction)} method.
- * - * @param the type of the first parameter; ignored - * - * @param the type of the second parameter; ignored - * - * @paramThis interface is related to, but should not be confused with, the {@link Reducer} interface, implementations of - * which can be used to build {@link Reducible} instances.
- * - * @paramMost {@link Reducible} implementations will return determinate values from invocations of this method, but there - * is no requirement to do so.
- * - * @param criteria the criteria; may be {@code null} to indicate no criteria - * - * @return a single object, or {@code null} - * - * @exception ReductionException if reduction could not occur or if an error occurs - */ - public T reduce(final C criteria); - - - /* - * Static methods. - */ - - - /** - * Calls the {@link #of(Selectable, Reducer, BiFunction)} method with the supplied {@code selectable}, the supplied {@code r}, and a reference to the {@link Reducer#fail(List, Object)} method, - * and returns the result. - * - * @paramImplementations of this method must be idempotent and must return a determinate value.
- * - *Implementations of this method must not return {@code null}.
- * - *Implementations of this method should not call {@link #list()}, since that method is typically implemented in - * terms of this one, or undefined behavior may result.
- * - * @param criteria the criteria to use; may be {@code null} - * - * @return an immutable sublist of this {@link Selectable}'s elements; never {@code null} - * - * @see #list() - */ - // Filters this thing according to the supplied criteria, producing a List. - // List not Stream to permit caching - // List not Collection so equals() is well-defined - // List is unmodifiable and is always valid for the supplied criteria (unenforceable) - // C and not Predicate because equality semantics for Predicate are not well-defined (caching again) - public ListImplementations of this method must be idempotent and must return a determinate value.
- * - *Implementations of this method must not return {@code null}.
- * - *The default implementation of this method calls the {@link #select(Object)} method with {@code null} as the sole - * argument.
- * - * @return an immutable {@link List} of all of this {@link Selectable}'s elements; never {@code null} - * - * @see #select(Object) - */ - public default ListThe cache is unbounded.
- * - * @paramList}.
- *
- * @param There is no guarantee that this method will return new {@link Selectable} instances.
- * - *The {@link Selectable} instances returned by this method may or may not cache their selections.
- * - *The selector function must select a sublist from the supplied {@link Collection} as mediated by the supplied - * criteria. The selector function must additionally be idempotent and must produce a determinate value when given the - * same arguments.
- * - *No validation of these semantics of the selector function is performed.
- * - * @param