Moves certain classes and interfaces to the microbean-producer project; cleans up documentation (#23)

Signed-off-by: Laird Nelson <[email protected]>

Author: ljnelson

README.md

@@ -19,15 +19,16 @@ microBean™ Bean requires a Java runtime of version 21 or higher.
 
 # Installation
 
-microBean™ Bean is available on [Maven Central](https://search.maven.org/).  Include microBean™ Bean as a Maven
+microBean™ Bean is available on [Maven
+Central](https://central.sonatype.com/artifact/org.microbean/microbean-bean). Include microBean™ Bean as a Maven
 dependency:
 
 ```xml
 <dependency>
   <groupId>org.microbean</groupId>
   <artifactId>microbean-bean</artifactId>
-  <!-- Always check https://search.maven.org/artifact/org.microbean/microbean-bean for up-to-date available versions. -->
-  <version>0.0.15</version>
+  <!-- Always check https://central.sonatype.com/artifact/org.microbean/microbean-bean for up-to-date available versions. -->
+  <version>0.0.16</version>
 </dependency>
 ```
 

pom.xml

@@ -73,14 +73,14 @@
     <java.util.logging.config.file>${project.basedir}/src/test/java/logging.properties</java.util.logging.config.file>
 
     <!-- maven-compiler-plugin properties -->
-    <maven.compiler.release>23</maven.compiler.release>
+    <maven.compiler.release>21</maven.compiler.release>
     <maven.compiler.showDeprecation>true</maven.compiler.showDeprecation>
     <maven.compiler.showWarnings>true</maven.compiler.showWarnings>
 
     <!-- maven-javadoc-plugin properties -->
     <bottom><![CDATA[Copyright &copy; ${project.inceptionYear}&ndash;{currentYear}, <a href="${project.organization.url}" target="_top">${project.organization.name}</a>. All rights reserved.]]></bottom>
     <doctitle>&lt;a href="${project.url}" target="_top"&gt;&lt;span style="font-family:Lobster, cursive;"&gt;µb&lt;/span&gt; ${project.artifactId}&lt;/a&gt; ${project.version}</doctitle>
-    <links>https://microbean.github.io/microbean-assign/apidocs/,https://microbean.github.io/microbean-attributes/apidocs/,https://microbean.github.io/microbean-construct/apidocs/,,https://microbean.github.io/microbean-scope/apidocs/</links>
+    <links>https://microbean.github.io/microbean-assign/apidocs/,https://microbean.github.io/microbean-attributes/apidocs/,https://microbean.github.io/microbean-construct/apidocs/</links>
     <sourcetab>2</sourcetab>
 
     <!-- maven-release-plugin properties -->
@@ -165,12 +165,6 @@
         <version>0.0.10</version>
       </dependency>
 
-      <dependency>
-        <groupId>org.microbean</groupId>
-        <artifactId>microbean-interceptor</artifactId>
-        <version>0.4.0</version>
-      </dependency>
-
     </dependencies>
   </dependencyManagement>
 
@@ -200,12 +194,6 @@
       <scope>compile</scope>
     </dependency>
 
-    <dependency>
-      <groupId>org.microbean</groupId>
-      <artifactId>microbean-interceptor</artifactId>
-      <scope>compile</scope>
-    </dependency>
-
     <!-- Test-scoped dependencies. -->
 
     <dependency>

src/main/java/module-info.java

@@ -26,6 +26,5 @@
   requires transitive org.microbean.attributes;
   requires            org.microbean.constant;
   requires transitive org.microbean.construct;
-  requires transitive org.microbean.interceptor;
 
 }

…/org/microbean/bean/AbstractFactory.java …/microbean/bean/AbstractFactory.java.baksrc/main/java/org/microbean/bean/AbstractFactory.java renamed to src/main/java/org/microbean/bean/AbstractFactory.java.bak src/main/java/org/microbean/bean/AbstractFactory.java renamed to src/main/java/org/microbean/bean/AbstractFactory.java.bak

@@ -3,26 +3,30 @@
  * 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
+ * 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
+ * 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.Collection;
 import java.util.Collections;
-import java.util.LinkedHashSet;
-import java.util.List;
 import java.util.SequencedSet;
 
+import java.util.function.Function;
+
+import static java.util.Collections.unmodifiableSequencedSet;
+
+import static java.util.LinkedHashSet.newLinkedHashSet;
+
 /**
  * An object with {@linkplain AttributedElement dependencies}.
  *
- * <p>By default, {@link Aggregate}s have no dependencies.</p>
+ * <p>By default, {@link Aggregate}s have {@linkplain #EMPTY_DEPENDENCIES no dependencies}.</p>
  *
  * @author <a href="https://about.me/lairdnelson/" target="_top">Laird Nelson</a>
  *
@@ -39,12 +43,12 @@ public interface Aggregate {
   /**
    * An immutable, empty {@link SequencedSet} of {@link Assignment}s.
    */
-  public static final SequencedSet<Assignment<?>> EMPTY_ASSIGNMENTS = Collections.unmodifiableSequencedSet(new LinkedHashSet<>(0));
+  public static final SequencedSet<Assignment<?>> EMPTY_ASSIGNMENTS = unmodifiableSequencedSet(newLinkedHashSet(0));
 
   /**
    * An immutable, empty {@link SequencedSet} of {@link AttributedElement}s.
    */
-  public static final SequencedSet<AttributedElement> EMPTY_DEPENDENCIES = Collections.unmodifiableSequencedSet(new LinkedHashSet<>(0));
+  public static final SequencedSet<AttributedElement> EMPTY_DEPENDENCIES = unmodifiableSequencedSet(newLinkedHashSet(0));
 
 
   /*
@@ -53,9 +57,9 @@ public interface Aggregate {
 
 
   /**
-   * Returns an unmodifiable {@link SequencedSet} of {@link AttributedElement} instances.
+   * Returns an immutable {@link SequencedSet} of {@link AttributedElement} instances.
    *
-   * @return an unmodifiable {@link SequencedSet} of {@link AttributedElement} instances; never {@code null}
+   * @return an immutable {@link SequencedSet} of {@link AttributedElement} instances; never {@code null}
    *
    * @see AttributedElement
    */
@@ -64,24 +68,26 @@ public default SequencedSet<AttributedElement> dependencies() {
   }
 
   /**
-   * Assigns a contextual reference to each of this {@link Aggregate}'s {@link AttributedElement} instances and returns the
-   * resulting {@link List} of {@link Assignment}s.
+   * A convenience method that assigns a contextual reference to each of this {@link Aggregate}'s {@link
+   * AttributedElement} instances and returns the resulting {@link SequencedSet} of {@link Assignment}s.
    *
-   * @param r a {@link Request}; must not be {@code null}
+   * <p>Typically there is no need to override this method.</p>
    *
-   * @return a {@link List} of {@link Assignment} instances; never {@code null}
+   * @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}; normally a
+   * reference to the {@link Request#reference(AttributedType)} method
+   *
+   * @return an immutable {@link SequencedSet} of {@link Assignment} instances; never {@code null}
    *
    * @exception NullPointerException if {@code r} is {@code null}
    */
-  public default SequencedSet<? extends Assignment<?>> assign(final Request<?> r) {
+  public default SequencedSet<? extends Assignment<?>> assign(final Function<? super AttributedType, ?> r) {
     final Collection<? extends AttributedElement> ds = this.dependencies();
     if (ds == null || ds.isEmpty()) {
       return EMPTY_ASSIGNMENTS;
     }
-    final SequencedSet<Assignment<?>> assignments = new LinkedHashSet<>();
-    for (final AttributedElement d : ds) {
-      assignments.add(new Assignment<>(d, r.reference(d.attributedType())));
-    }
+    final SequencedSet<Assignment<?>> assignments = newLinkedHashSet(ds.size());
+    ds.forEach(d -> assignments.add(new Assignment<>(d, r.apply(d.attributedType()))));
     return Collections.unmodifiableSequencedSet(assignments);
   }
 

src/main/java/org/microbean/bean/Aggregate.java

@@ -27,6 +27,7 @@
 
 import javax.lang.model.type.TypeMirror;
 
+import org.microbean.attributes.Attributed;
 import org.microbean.attributes.Attributes;
 
 import org.microbean.constant.Constables;
@@ -43,9 +44,7 @@
  *
  * @author <a href="https://about.me/lairdnelson/" target="_top">Laird Nelson</a>
  */
-public final record AttributedElement(Element element, List<Attributes> attributes) implements Constable {
-
-  private static final ClassDesc CD_Element = ClassDesc.of("javax.lang.model.element.Element");
+public final record AttributedElement(Element element, List<Attributes> attributes) implements Attributed, Constable {
 
   /**
    * Creates a new {@link AttributedElement}.
@@ -94,7 +93,7 @@ public Optional<? extends ConstantDesc> describeConstable() {
       .flatMap(elementDesc -> Constables.describeConstable(this.attributes())
                .map(attributesDesc -> DynamicConstantDesc.of(BSM_INVOKE,
                                                              MethodHandleDesc.ofConstructor(ClassDesc.of(this.getClass().getName()),
-                                                                                            CD_Element,
+                                                                                            ClassDesc.of("javax.lang.model.element.Element"),
                                                                                             CD_List),
                                                              elementDesc,
                                                              attributesDesc)));

src/main/java/org/microbean/bean/AttributedElement.java

@@ -1,18 +1,19 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2023–2024 microBean™.
+ * Copyright © 2023–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
+ * 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
+ * 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.lang.constant.ClassDesc;
 import java.lang.constant.Constable;
 import java.lang.constant.ConstantDesc;
 import java.lang.constant.DynamicConstantDesc;
@@ -22,11 +23,9 @@
 import java.util.Optional;
 import java.util.SequencedSet;
 
-import static java.lang.constant.ConstantDescs.BSM_INVOKE;
+import java.util.function.Function;
 
-import static org.microbean.bean.ConstantDescs.CD_Bean;
-import static org.microbean.bean.ConstantDescs.CD_Factory;
-import static org.microbean.bean.ConstantDescs.CD_Id;
+import static java.lang.constant.ConstantDescs.BSM_INVOKE;
 
 /**
  * A ({@link Constable}) pairing of an {@link Id} with a {@link Factory}.
@@ -59,17 +58,24 @@ public final record Bean<I>(Id id, Factory<I> factory) implements Aggregate, Con
     Objects.requireNonNull(factory, "factory");
   }
 
-  @Override // Alternate
+  @Override // Ranked
   public final boolean alternate() {
     return this.id().alternate();
   }
 
+  @Override // Aggregate
+  public final SequencedSet<? extends Assignment<?>> assign(final Function<? super AttributedType, ?> r) {
+    return this.factory().assign(r);
+  }
+
   /**
    * Returns this {@link Bean}, forcibly cast appropriately.
    *
    * @param <X> the type of contextual instances this {@link Bean} creates
    *
    * @return this {@link Bean}
+   *
+   * @exception ClassCastException if the cast is inappropriate
    */
   @SuppressWarnings("unchecked")
   public final <X> Bean<X> cast() {
@@ -86,30 +92,24 @@ public final Optional<DynamicConstantDesc<Bean<I>>> describeConstable() {
     return (this.factory() instanceof Constable c ? c.describeConstable() : Optional.<ConstantDesc>empty())
       .flatMap(factoryDesc -> this.id().describeConstable()
                .map(idDesc -> DynamicConstantDesc.of(BSM_INVOKE,
-                                                     MethodHandleDesc.ofConstructor(CD_Bean,
-                                                                                    CD_Id,
-                                                                                    CD_Factory),
+                                                     MethodHandleDesc.ofConstructor(ClassDesc.of(Bean.class.getName()),
+                                                                                    ClassDesc.of(Id.class.getName()),
+                                                                                    ClassDesc.of(Factory.class.getName())),
                                                      idDesc,
                                                      factoryDesc)));
   }
 
-  @Override // Object
+  @Override // Record (Object)
   public final boolean equals(final Object other) {
-    if (other == this) {
-      return true;
-    } else if (other != null && other.getClass() == this.getClass()) {
-      return Objects.equals(this.id(), ((Bean<?>)other).id());
-    } else {
-      return false;
-    }
+    return this == other || other != null && this.getClass() == other.getClass() && this.id().equals(((Bean<?>)other).id());
   }
 
-  @Override // Object
-  public int hashCode() {
+  @Override // Record (Object)
+  public final int hashCode() {
     return this.id().hashCode();
   }
 
-  @Override // Alternate (Ranked)
+  @Override // Ranked
   public final int rank() {
     return this.id().rank();
   }

src/main/java/org/microbean/bean/Bean.java

@@ -41,6 +41,8 @@
  *
  * @see #Beans(Selectable, Reducible)
  *
+ * @see #cachingSelectableOf(Collection, Matcher, Map)
+ *
  * @see Selectable
  *
  * @see Reducible
@@ -129,37 +131,47 @@ public Beans(final Domain domain, final Collection<? extends Bean<?>> beans) {
   /**
    * Creates a new {@link Beans}.
    *
-   * <p>{@link Bean} instances selected by the supplied {@link Selectable} will be reduced using a {@link
-   * RankedReducer}.</p>
-   *
    * @param s a {@link Selectable}; must not be {@code null}
    *
    * @exception NullPointerException if {@code s} is {@code null}
    *
-   * @see RankedReducer
+   * @see #Beans(Selectable, Reducer)
+   *
+   * @see RankedReducer#of()
    */
   public Beans(final Selectable<AttributedType, Bean<?>> s) {
-    this(s, Reducible.of(s, RankedReducer.of()));
+    this(s, (Reducer<AttributedType, Bean<?>>)null);
   }
 
   /**
    * Creates a new {@link Beans}.
    *
    * @param s a {@link Selectable}; must not be {@code null}
    *
-   * @param r a {@link Reducible} to apply to elements selected by the supplied {@link Selectable}; must not be {@code
-   * null}
+   * @param r a {@link Reducer}; may be {@code null} in which case a {@link RankedReducer#of() RankedReducer} will be
+   * used instead
    *
-   * @exception NullPointerException if any argument is {@code null}
+   * @exception NullPointerException if {@code s} is {@code null}
    *
-   * @see #cachingSelectableOf(Collection, Matcher, Map)
+   * @see #Beans(Selectable, Reducible)
    *
    * @see Reducible#of(Selectable, Reducer)
+   */
+  public Beans(final Selectable<AttributedType, Bean<?>> s, final Reducer<AttributedType, Bean<?>> r) {
+    this(s, Reducible.of(s, r == null ? RankedReducer.of() : r));
+  }
+
+  /**
+   * Creates a new {@link Beans}.
+   *
+   * @param s a {@link Selectable}; must not be {@code null}
    *
-   * @see RankedReducer
+   * @param r a {@link Reducible} to apply to elements selected by the supplied {@link Selectable}; must not be {@code
+   * null}
+   *
+   * @exception NullPointerException if any argument is {@code null}
    */
-  public Beans(final Selectable<AttributedType, Bean<?>> s,
-               final Reducible<AttributedType, Bean<?>> r) {
+  public Beans(final Selectable<AttributedType, Bean<?>> s, final Reducible<AttributedType, Bean<?>> r) {
     this.s = Objects.requireNonNull(s, "s");
     this.r = Objects.requireNonNull(r, "r");
   }