001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2025–2026 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.reference;
015
016/**
017 * A hierarchical {@link DestructorRegistry} that is {@link AutoCloseable}.
018 *
019 * <p>This interface is often used by {@link org.microbean.bean.ReferencesSelector} implementors, and normally by no
020 * other kinds of users.</p>
021 *
022 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
023 *
024 * @see #close()
025 *
026 * @see DestructorRegistry
027 */
028public interface DestructorTree extends AutoCloseable, DestructorRegistry {
029
030  /**
031   * Creates a new <dfn>child</dfn> instance of this implementation, or a subtype, {@linkplain #register(Object,
032   * Destructor) registers it} with this implementation, using a method reference to its {@link #close()} method as the
033   * {@link Destructor}, and returns it.
034   *
035   * @return a new (non-{@code null}) child instance of this implementation, or a subtype, {@linkplain #register(Object,
036   * Destructor) registered} with this implementation such that {@link #close() closing} this implementation will also
037   * {@linkplain #close() close} the child instance
038   *
039   * @see #close()
040   *
041   * @see #register(Object, Destructor)
042   */
043  public DestructorTree newChild();
044
045  /**
046   * Closes this {@link DestructorTree} implementation by effectively {@linkplain #remove(Object) removing} all
047   * {@linkplain #register(Object, Destructor) registered} contextual instances and {@linkplain Destructor#destroy()
048   * running their affiliated <code>Destructor</code>s}.
049   *
050   * @see #remove(Object)
051   */
052  @Override // AutoCloseable
053  public void close();
054
055  /**
056   * Removes the supplied contextual instance and the {@link Destructor} that was {@linkplain #register(Object,
057   * Destructor) registered with it}.
058   *
059   * <p>The {@link Destructor#destroy()} will not be invoked by implementations of this method.</p>
060   *
061   * @param instance the contextual instance to remove; may be {@code null} in which case {@code null} will be returned
062   *
063   * @return a {@link Destructor} {@linkplain #register(Object, Destructor) registered} with the supplied instance, or
064   * {@code null} if no such {@link Destructor} exists
065   */
066  public Destructor remove(final Object instance);
067
068}