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