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 <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 {@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}.
037   *
038   * <p>Implementations of this method may return {@code null}.</p>
039   *
040   * <p>Implementations of this method must return a determinate value.</p>
041   *
042   * @return an {@link Id}, or {@code null}
043   *
044   * @see Bean
045   *
046   * @see Factory#create(Creation)
047   */
048  public Id id();
049
050  /**
051   * Signals that the supplied {@code instance} is in the process of being created, typically by an invocation of a
052   * {@link Factory}'s {@link Factory#create(Creation) create(Creation)} method, and is about to be made available for
053   * use.
054   *
055   * <p>This method is typically invoked from within a {@link Factory#create(Creation)} implementation immediately
056   * prior to its returning a value.</p>
057   *
058   * <p>It is permissible and very common for an implementation of this method to do nothing. The default implementation
059   * of this method does nothing.</p>
060   *
061   * <p>Implementations of this method <strong>must</strong> ensure that if two or more invocations of this method are
062   * supplied with the same object reference, only one invocation will have any effect, whether by throwing an {@link
063   * IllegalArgumentException} or by simply ignoring redundant invocations.</p>
064   *
065   * @param instance the instance that is in the process of being returned from an invocation of a {@link
066   * Factory#create(Creation)} method; may be {@code null}
067   *
068   * @exception IllegalArgumentException if {@code instance} was found to be unsuitable for any reason
069   */
070  // MUST be idempotent
071  // For incomplete instances; see also https://stackoverflow.com/questions/50202523/creationalcontext-should-a-custom-bean-always-call-push-from-its-create-met
072  public default void creating(final I instance) {
073
074  }
075
076}