001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2025 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 */
028// Needed and used only by ReferencesSelector implementations.
029//
030// TODO: maybe could move it to microbean-reference? microbean-scopelet depends on microbean-reference already?
031public interface DestructorTree extends AutoCloseable, DestructorRegistry {
032
033  /**
034   * Creates a new <dfn>child</dfn> instance of this implementation, or a subtype, {@linkplain #register(Object,
035   * Destructor) registers it} with this implementation, using a method reference to its {@link #close()} method as the
036   * {@link Destructor}, and returns it.
037   *
038   * @return a new (non-{@code null}) child instance of this implementation, or a subtype, {@linkplain #register(Object,
039   * Destructor) registered} with this implementation such that {@link #close() closing} this implementation will also
040   * {@linkplain #close() close} the child instance
041   *
042   * @see #close()
043   *
044   * @see #register(Object, Destructor)
045   */
046  public DestructorTree newChild();
047
048  /**
049   * Closes this {@link DestructorTree} implementation by effectively {@linkplain #remove(Object) removing} all
050   * {@linkplain #register(Object, Destructor) registered} contextual instances and {@linkplain Destructor#destroy()
051   * running their affiliated <code>Destructor</code>s}.
052   *
053   * @see #remove(Object)
054   */
055  @Override // AutoCloseable
056  public void close();
057
058  /**
059   * Removes the supplied contextual instance and the {@link Destructor} that was {@linkplain #register(Object,
060   * Destructor) registered with it}.
061   *
062   * <p>The {@link Destructor#destroy()} will not be invoked by implementations of this method.</p>
063   *
064   * @param instance the contextual instance to remove; may be {@code null} in which case {@code null} will be returned
065   *
066   * @return a {@link Destructor} {@linkplain #register(Object, Destructor) registered} with the supplied instance, or
067   * {@code null} if no such {@link Destructor} exists
068   */
069  public Destructor remove(final Object instance);
070
071}