This method takes no action and returns {@code false} in all other cases.
+ *
+ * @param reference a contextual reference that will be destroyed later; if {@code null} then no action will be taken
+ * and {@code false} will be returned
+ *
+ * @param destructor a {@link Destructor} that, when {@linkplain Destructor#destroy() run}, will destroy the supplied
+ * {@code reference} in some way; if {@code null} then no action will be taken and {@code false} will be returned; if
+ * non-{@code null} of()) {
+ // Already closed; register must therefore be a no-op.
+ return false;
+ }
+ return this.destructors.putIfAbsent(reference, destructor) == null;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ @Override // DestructorTree
+ public final Destructor remove(final Object reference) {
+ if (reference == null) {
+ return null;
+ }
+ lock.lock();
+ try {
+ return this.destructors == null ? null : this.destructors.remove(reference);
+ } finally {
+ lock.unlock();
+ }
+ }
+
+}
diff --git a/src/main/java/org/microbean/reference/DestructorRegistry.java b/src/main/java/org/microbean/reference/DestructorRegistry.java
new file mode 100644
index 0000000..6518898
--- /dev/null
+++ b/src/main/java/org/microbean/reference/DestructorRegistry.java
@@ -0,0 +1,80 @@
+/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
+ *
+ * Copyright © 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.reference;
+
+/**
+ * An interface whose implementations can register contextual instances for idempotent destruction at some later point.
+ *
+ * This interface is often used by implementors of systems of dependent object destruction, and normally by no other
+ * kinds of users.
+ *
+ * Laird Nelson
+ *
+ * @see #register(Object, Destructor)
+ */
+// Needed by "dependent"/"none" scopes/lifecycle managers.
+// Not used by "normal" factories etc.
+//
+// TODO: the package feels wrong, but stashing it in microbean-scopelet, alongside NoneScopelet, doesn't let
+// microbean-reference's Request implement it
+//
+// TODO: maybe could move it to microbean-reference? microbean-scopelet depends on microbean-reference already?
+public interface DestructorRegistry {
+
+ /**
+ * Registers the supplied contextual instance such that at some future moment, or perhaps not at all, the
+ * supplied {@link Destructor} will be {@linkplain Destructor#destroy() run} to destroy it idempotently, and returns
+ * {@code true} if and only if the registration was successful.
+ *
+ * @param instance a contextual instance; may be {@code null} in which case no action will be taken and {@code false}
+ * will be returned
+ *
+ * @param destructor a {@link Destructor}; may be {@code null} in which case no action will be taken and {@code false}
+ * will be returned
+ *
+ * @return {@code true} if and only if registration was successful; {@code false} otherwise
+ *
+ * @see Destructor
+ */
+ public boolean register(final Object instance, final Destructor destructor);
+
+ /**
+ * An interface indicating that an implementation is capable of destroying an object that it opaquely
+ * references such that the destroyed object will no longer be suitable for use.
+ *
+ * @author Laird Nelson
+ *
+ * @see #destroy()
+ *
+ * @see DestructorRegistry#register(Object, Destructor)
+ */
+ @FunctionalInterface
+ public static interface Destructor {
+
+ /**
+ * Destroys an object that this implementation opaquely references such that the destroyed object will no longer be
+ * suitable for use.
+ *
+ * Implementations of this method must be safe for concurrent use by multiple threads.
+ *
+ * Implementations of this method must be idempotent, performing no action if destruction of the implicit object
+ * has already taken place.
+ *
+ * @see DestructorRegistry#register(Object, Destructor)
+ */
+ public void destroy();
+
+ }
+
+}
diff --git a/src/main/java/org/microbean/reference/DestructorTree.java b/src/main/java/org/microbean/reference/DestructorTree.java
new file mode 100644
index 0000000..b34d91a
--- /dev/null
+++ b/src/main/java/org/microbean/reference/DestructorTree.java
@@ -0,0 +1,71 @@
+/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
+ *
+ * Copyright © 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.reference;
+
+/**
+ * A hierarchical {@link DestructorRegistry} that is {@link AutoCloseable}.
+ *
+ * This interface is often used by {@link org.microbean.bean.ReferencesSelector} implementors, and normally by no
+ * other kinds of users.
+ *
+ * @author Laird Nelson
+ *
+ * @see #close()
+ *
+ * @see DestructorRegistry
+ */
+// Needed and used only by ReferencesSelector implementations.
+//
+// TODO: maybe could move it to microbean-reference? microbean-scopelet depends on microbean-reference already?
+public interface DestructorTree extends AutoCloseable, DestructorRegistry {
+
+ /**
+ * Creates a new child instance of this implementation, or a subtype, {@linkplain #register(Object,
+ * Destructor) registers it} with this implementation, using a method reference to its {@link #close()} method as the
+ * {@link Destructor}, and returns it.
+ *
+ * @return a new (non-{@code null}) child instance of this implementation, or a subtype, {@linkplain #register(Object,
+ * Destructor) registered} with this implementation such that {@link #close() closing} this implementation will also
+ * {@linkplain #close() close} the child instance
+ *
+ * @see #close()
+ *
+ * @see #register(Object, Destructor)
+ */
+ public DestructorTree newChild();
+
+ /**
+ * Closes this {@link DestructorTree} implementation by effectively {@linkplain #remove(Object) removing} all
+ * {@linkplain #register(Object, Destructor) registered} contextual instances and {@linkplain Destructor#destroy()
+ * running their affiliated Destructors}.
+ *
+ * @see #remove(Object)
+ */
+ @Override // AutoCloseable
+ public void close();
+
+ /**
+ * Removes the supplied contextual instance and the {@link Destructor} that was {@linkplain #register(Object,
+ * Destructor) registered with it}.
+ *
+ * The {@link Destructor#destroy()} will not be invoked by implementations of this method.
+ *
+ * @param instance the contextual instance to remove; may be {@code null} in which case {@code null} will be returned
+ *
+ * @return a {@link Destructor} {@linkplain #register(Object, Destructor) registered} with the supplied instance, or
+ * {@code null} if no such {@link Destructor} exists
+ */
+ public Destructor remove(final Object instance);
+
+}
diff --git a/src/main/java/org/microbean/reference/Instances.java b/src/main/java/org/microbean/reference/Instances.java
index 736a591..eccc692 100644
--- a/src/main/java/org/microbean/reference/Instances.java
+++ b/src/main/java/org/microbean/reference/Instances.java
@@ -13,25 +13,26 @@
*/
package org.microbean.reference;
+import java.util.function.BooleanSupplier;
import java.util.function.Supplier;
import org.microbean.bean.Bean;
import org.microbean.bean.Id;
import org.microbean.bean.Creation;
+import org.microbean.bean.ReferencesSelector;
/**
* A factory for {@link Supplier}s of contextual instances.
*
+ * {@link Instances} instances are used by {@link Request} instances.
+ *
* @author Laird Nelson
*
* @see #supplier(Bean, Creation)
+ *
+ * @see Request
*/
-public interface Instances extends AutoCloseable {
-
- @Override // AutoCloseable
- public default void close() {
-
- }
+public interface Instances {
/**
* Returns {@code true} if and only if it is possible for a client proxy to be created for contextual instances
diff --git a/src/main/java/org/microbean/reference/ReflectiveClientProxier.java b/src/main/java/org/microbean/reference/ReflectiveClientProxier.java
index 314df2e..9fe83e1 100644
--- a/src/main/java/org/microbean/reference/ReflectiveClientProxier.java
+++ b/src/main/java/org/microbean/reference/ReflectiveClientProxier.java
@@ -101,6 +101,7 @@ protected final Proxy proxy(final ProxySpecification ps,
.computeIfAbsent(ps,
ps0 -> newProxyInstance(this.classLoader(),
interfaces,
+ // Anonymous class, not lambda, due to Throwable in the signature
new InvocationHandler() {
@Override // InvocationHandler
public final Object invoke(final Object p,
diff --git a/src/main/java/org/microbean/reference/Request.java b/src/main/java/org/microbean/reference/Request.java
index 8a5214a..b4e224a 100644
--- a/src/main/java/org/microbean/reference/Request.java
+++ b/src/main/java/org/microbean/reference/Request.java
@@ -14,39 +14,37 @@
package org.microbean.reference;
import java.util.Iterator;
-import java.util.List;
-import java.util.NoSuchElementException;
-import java.util.Objects;
-import javax.lang.model.type.TypeMirror;
+import java.util.function.Supplier;
+
+import org.microbean.assign.AttributedType;
+import org.microbean.assign.Selectable;
-import org.microbean.bean.AmbiguousReductionException;
-import org.microbean.bean.AttributedType;
-import org.microbean.bean.AutoCloseableRegistry;
import org.microbean.bean.Bean;
import org.microbean.bean.BeanException;
import org.microbean.bean.Creation;
-import org.microbean.bean.DefaultAutoCloseableRegistry;
import org.microbean.bean.Destruction;
-import org.microbean.bean.Factory;
import org.microbean.bean.Id;
-import org.microbean.bean.Reducible;
import org.microbean.bean.References;
import org.microbean.bean.ReferencesSelector;
-import org.microbean.bean.Selectable;
-import org.microbean.bean.UnsatisfiedReductionException;
import org.microbean.construct.Domain;
+import org.microbean.proxy.Proxy;
+
+import static java.util.Collections.emptyIterator;
+
+import static java.util.Objects.requireNonNull;
+
/**
* A central object representing a request for dependencies that is a {@link Creation} (and therefore also a {@link
- * Destruction}) and a {@link References}.
+ * Destruction}), a {@link DestructorRegistry}, and a {@link References}.
*
* Instances of this class are the heart and soul of a dependency injection and acquisition system.
*
- * @param the contextual instance type (see for example {@link Creation})
+ * @param the contextual instance type being instantiated (see for example {@link Creation})
*
- * @param the contextual reference type (see {@link References})
+ * @param the contextual reference type being sought (see {@link References})
*
* @author Laird Nelson
*
@@ -54,13 +52,15 @@
*
* @see Destruction
*
+ * @see DestructorRegistry
+ *
* @see References
*
- * @see Factory#create(Creation)
+ * @see org.microbean.bean.Factory#create(Creation)
*
- * @see Factory#destroy(Object, Destruction)
+ * @see org.microbean.bean.Factory#destroy(Object, Destruction)
*/
-public final class Request implements Creation, Destruction, References {
+public final class Request implements Creation, Destruction, DestructorRegistry, References {
/*
@@ -68,17 +68,19 @@ public final class Request implements Creation, Destruction, References
*/
- private final Selectable> s;
+ private final Domain domain;
+
+ private final Selectable> beans;
private final Instances instances;
- private final AutoCloseableRegistry acr;
+ private final DestructorTree destructorTree;
private final ClientProxier cp;
- private final Bean b;
+ private final Bean b; // nullable; B and R must then be (effectively) Void
- private final AttributedType rType;
+ private final AttributedType rType; // nullable; R must then be Void
/*
@@ -89,37 +91,67 @@ public final class Request implements Creation, Destruction, References
/**
* Creates a new {@link Request}.
*
+ * @param d a {@link Domain}; must not be {@code null}
+ *
+ * @param s a {@link Selectable} providing access to {@link Bean}s by {@link AttributedType}; must not be {@code
+ * null}; must be safe for concurrent use by multiple threads; often assembled out of methods present in the {@link
+ * org.microbean.bean.Selectables} and {@link org.microbean.bean.Beans} classes, among other such utility classes
+ *
+ * @param instances an {@link Instances} responsible for using a {@link Bean} to acquire an appropriate {@link
+ * Supplier} of contextual instances; must not be {@code null}
+ *
+ * @param cp a {@link ClientProxier}; must not be {@code null}
+ *
+ * @exception NullPointerException if any argument is {@code null}
+ *
+ * @see #Request(Domain, Selectable, Instances, DestructorTree, ClientProxier)
+ */
+ public Request(final Domain d,
+ final Selectable> s,
+ final Instances instances,
+ final ClientProxier cp) {
+ this(d, s, instances, null, cp, null, null);
+ }
+
+ /**
+ * Creates a new {@link Request}.
+ *
+ * @param d a {@link Domain}; must not be {@code null}
+ *
* @param s a {@link Selectable} providing access to {@link Bean}s by {@link AttributedType}; must not be {@code
* null}; must be safe for concurrent use by multiple threads; often assembled out of methods present in the {@link
* org.microbean.bean.Selectables} and {@link org.microbean.bean.Beans} classes, among other such utility classes
*
* @param instances an {@link Instances} responsible for using a {@link Bean} to acquire an appropriate {@link
- * java.util.function.Supplier} of contextual instances; must not be {@code null}
+ * Supplier} of contextual instances; must not be {@code null}
*
- * @param acr an {@link AutoCloseableRegistry}; may be {@code null} in which case a default implementation will be
- * used instead
+ * @param destructorTree a {@link DestructorTree}; may be {@code null} in which case a default implementation will be used
+ * instead
*
* @param cp a {@link ClientProxier}; must not be {@code null}
*
* @exception NullPointerException if {@code s}, {@code instances}, or {@code cp} is {@code null}
*/
- public Request(final Selectable> s,
+ public Request(final Domain d,
+ final Selectable> s,
final Instances instances,
- final AutoCloseableRegistry acr,
+ final DestructorTree destructorTree, // nullable
final ClientProxier cp) {
- this(s, instances, acr, cp, null, null);
+ this(d, s, instances, destructorTree, cp, null, null);
}
- private Request(final Selectable> s,
+ private Request(final Domain d,
+ final Selectable> s,
final Instances instances,
- final AutoCloseableRegistry acr, // nullable
+ final DestructorTree destructorTree, // nullable
final ClientProxier cp,
- final Bean b,
- final AttributedType rType) { // the type of the references returned; nullable
- this.s = Objects.requireNonNull(s, "s");
- this.instances = Objects.requireNonNull(instances, "instances");
- this.cp = Objects.requireNonNull(cp, "cp");
- this.acr = acr == null ? new DefaultAutoCloseableRegistry() : acr;
+ final Bean b, // nullable
+ final AttributedType rType) { // the type of the references returned (); nullable
+ this.domain = requireNonNull(d, "d");
+ this.beans = requireNonNull(s, "s");
+ this.instances = requireNonNull(instances, "instances");
+ this.cp = requireNonNull(cp, "cp");
+ this.destructorTree = destructorTree == null ? new DefaultDestructorTree() : destructorTree;
this.b = b;
this.rType = rType;
}
@@ -132,7 +164,22 @@ private Request(final Selectable> s,
@Override // Destruction
public final void close() {
- try (this.instances; this.acr) {}
+ this.destructorTree.close();
+ }
+
+ @Override // ReferencesSelector
+ public final boolean destroy(final Object r) {
+ final Destructor destructor = this.destructorTree.remove(r instanceof Proxy p ? p.$proxied() : r);
+ if (destructor != null) {
+ destructor.destroy(); // I keep going back and forth on whether this should be under some kind of lock, or whether the Destructor contract covers it
+ return true;
+ }
+ return false;
+ }
+
+ @Override // ReferencesSelector
+ public final Domain domain() {
+ return this.domain;
}
@Override // Creation
@@ -142,40 +189,65 @@ public final Id id() {
@Override // References (Iterable)
public final Iterator iterator() {
- return new ReferencesIterator();
+ return new ReferencesIterator(); // inner class; see below
}
- // Called by ReferencesIterator below
- private final R get(final Request r) {
- final Bean bean = r.b;
+ @Override // ReferencesSelector
+ public final R reference(final Bean bean) {
+ final Supplier supplier = this.instances.supplier(bean, this.newChild(bean)); // newChild is critical
final Id id = bean.id();
- if (this.instances.proxiable(id)) {
- final R ref = this.cp.clientProxy(id, instances.supplier(bean, r));
- // TODO: we know that ref can be destroyed because it's from a normal scope, i.e. it is not itself a contextual
- // instance, so save it in a collection somewhere so it can be destroyed via the #destroy(R) method (see CDI's
- // Instances#destroy(Object))
- return ref;
- }
- // TODO: ask instances if ref is destroyable and save it off
- return instances.supplier(bean, r).get();
+ return this.instances.proxiable(id) ? this.cp.clientProxy(id, supplier) : supplier.get();
}
@Override // ReferencesSelector
- public final References references(final AttributedType t) {
- return new Request<>(this.s, this.instances, this.acr, this.cp, this.b, t);
+ @SuppressWarnings("unchecked")
+ public final References references(final AttributedType rType) {
+ return this.rType == rType ? (References)this :
+ // This basically returns "this" but with a new rType. But Request is immutable so we make a copy.
+ new Request<>(this.domain,
+ this.beans,
+ this.instances,
+ this.destructorTree, // deliberately NO this.destructorTree.newChild() call
+ this.cp,
+ this.b, // nullable; will then be (effectively) Void
+ rType); // nullable; will then be Void
+ }
+
+ @Override // DestructorTree (DestructorRegistry)
+ public final boolean register(final Object reference, final Destructor destructor) {
+ return this.destructorTree.register(reference, destructor);
}
@Override // References
public final int size() {
- return this.s.select(this.rType).size();
+ return this.rType == null ? 0 : this.beans.select(this.rType).size();
}
- @Override // References
- public final boolean destroy(final R r) {
- if (r != null) { // and is in dependent scope; we'll deal with that later
- // TODO: remove it from a collection of dependent refs returned by get(Request) above
+ /*
+ * Private instance methods.
+ */
+
+ private final Iterator> beanIterator() {
+ return this.rType == null ? emptyIterator() : this.beans.select(this.rType).iterator();
+ }
+
+ @SuppressWarnings("unchecked")
+ private final Request newChild(final Bean b) {
+ if (b == null) {
+ if (this.b == null) {
+ return (Request)this; // both and are effectively Void
+ }
+ } else if (b.equals(this.b)) {
+ return (Request)this;
}
- return false;
+ return
+ new Request(this.domain,
+ this.beans,
+ this.instances,
+ this.destructorTree.newChild(), // critical; !b.equals(this.b)
+ this.cp,
+ b, // nullable; if so, better resolve to Void
+ null); // rType; resolves to Void
}
@@ -184,6 +256,7 @@ public final boolean destroy(final R r) {
*/
+ // NOT thread-safe.
private final class ReferencesIterator implements Iterator {
private Iterator> i;
@@ -192,38 +265,36 @@ private final class ReferencesIterator implements Iterator {
private ReferencesIterator() {
super();
+ if (rType == null) {
+ this.i = emptyIterator();
+ }
}
@Override // Iterator
public final boolean hasNext() {
- if (rType == null) {
- return false;
- }
if (this.i == null) {
- this.i = s.select(rType).iterator();
+ this.i = beanIterator();
}
return this.i.hasNext();
}
@Override // Iterator
+ @SuppressWarnings("unchecked")
public final R next() {
- if (rType == null) {
- throw new NoSuchElementException();
- }
if (this.i == null) {
- this.i = s.select(rType).iterator();
+ this.i = beanIterator();
}
- @SuppressWarnings("unchecked")
- final R ref = get(new Request<>(s, instances, acr.newChild(), cp, (Bean)this.i.next(), null));
- this.ref = ref;
- return ref;
+ return this.ref = reference((Bean)this.i.next());
}
@Override // Iterator
public final void remove() {
final R ref = this.ref;
+ if (ref == null) {
+ throw new IllegalStateException(); // per Iterator#remove() contract
+ }
this.ref = null;
- Request.this.destroy(ref);
+ destroy(ref);
}
}