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.bean;
015
016/**
017 * A representation of a {@link Factory}'s {@linkplain Factory#create(Creation) creation activity}.
018 *
019 * <p>Any {@link Creation} implementation must also be a {@link Destruction} implementation, or undefined behavior and
020 * errors may occur.</p>
021 *
022 * <p>Many {@link Creation} implementations are also {@link AutoCloseableRegistry} implementations. This is not a
023 * requirement of the {@link Creation} or {@link Destruction} contracts.</p>
024 *
025 * @param <I> the type of instance being created
026 *
027 * @author <a href="https://about.me/lairdnelson" target="_parent">Laird Nelson</a>
028 *
029 * @see #creating(Object)
030 *
031 * @see AutoCloseableRegistry
032 *
033 * @see Destruction
034 *
035 * @see ReferencesSelector
036 */
037public interface Creation<I> extends ReferencesSelector {
038
039  /**
040   * Returns the {@link Id} of the {@link Bean} {@linkplain Bean#factory() whose} {@link Factory}'s {@link
041   * Factory#create(Creation)} invocation is responsible for the existence of this {@link Creation}.
042   *
043   * <p>Implementations of this method may return {@code null}.</p>
044   *
045   * <p>Implementations of this method must return a determinate value.</p>
046   *
047   * @return an {@link Id}, or {@code null}
048   *
049   * @see Bean
050   *
051   * @see Factory#create(Creation)
052   */
053  public Id id();
054
055  /**
056   * Signals that the supplied {@code instance} is in the process of being created, typically by an invocation of a
057   * {@link Factory}'s {@link Factory#create(Creation) create(Creation)} method, and is about to be made available for
058   * use.
059   *
060   * <p>This method is typically invoked from within a {@link Factory#create(Creation)} implementation immediately
061   * prior to its returning a value.</p>
062   *
063   * <p>It is permissible and very common for an implementation of this method to do nothing. The default implementation
064   * of this method does nothing.</p>
065   *
066   * <p>Implementations of this method <strong>must</strong> ensure that if two or more invocations of this method are
067   * supplied with the same object reference, only one invocation will have any effect, whether by throwing an {@link
068   * IllegalArgumentException} or by simply ignoring redundant invocations.</p>
069   *
070   * @param instance the instance that is in the process of being returned from an invocation of a {@link
071   * Factory#create(Creation)} method; may be {@code null}
072   *
073   * @exception IllegalArgumentException if {@code instance} was found to be unsuitable for any reason
074   */
075  // MUST be idempotent
076  // For incomplete instances; see also https://stackoverflow.com/questions/50202523/creationalcontext-should-a-custom-bean-always-call-push-from-its-create-met
077  public default void creating(final I instance) {
078
079  }
080
081}