001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.inject;
018
019/**
020 * Marker interface for builders that accept an <i>overriding</i> {@link BeanStore} &mdash; a layer
021 * whose entries take precedence over the builder's local bean registrations during construction-time
022 * reflective injection.
023 *
024 * <p>
025 * Implementing builders MUST install the supplied store in the {@code overridingParent} slot of the
026 * underlying {@link BasicBeanStore} (see
027 * {@link BasicBeanStore#BasicBeanStore(BeanStore, BeanStore)}).  The resulting bean-lookup order is:
028 * <ol>
029 *    <li><i>Overriding parent</i> (the store passed to {@link #overridingBeanStore(BeanStore)}) &mdash; wins
030 *       for any {@code (type, name)} it knows about.
031 *    <li>The builder's local entries (e.g. {@code @Bean} factories declared on a {@code @Rest} resource,
032 *       beans registered directly via {@code addBean(...)} / {@code addSupplier(...)}).
033 *    <li>The builder's regular parent bean store (e.g. a Spring {@code ApplicationContext} bridge), if any.
034 *    <li>Framework-default suppliers (registered via {@code addDefaultSupplier(...)}).
035 * </ol>
036 *
037 * <p>
038 * The primary use case is test-time bean substitution: a test builds a {@code TestBeanStore}-style overlay
039 * with mock beans, hands it to the builder via {@link #overridingBeanStore(BeanStore)}, and the system under
040 * test resolves the mocks at construction time without any reflection on the SUT itself.  This is the
041 * <b>Mode INJECT</b> wiring pattern in the test-injection model &mdash; the overlay is installed before the SUT
042 * exists.
043 *
044 * <h5 class='section'>Example:</h5>
045 * <p class='bjava'>
046 *    <jk>var</jk> <jv>overlay</jv> = <jk>new</jk> TestBeanStore().override(MyService.<jk>class</jk>, <jv>mockSvc</jv>);
047 *    <jk>var</jk> <jv>serializers</jv> = SerializerSet.<jsm>create</jsm>()
048 *       .overridingBeanStore(<jv>overlay</jv>)
049 *       .add(JsonSerializer.<jk>class</jk>)
050 *       .build();
051 * </p>
052 *
053 * <h5 class='section'>Why a self-typed interface:</h5>
054 * <p>
055 * The {@code B extends BeanStoreOverridable<B>} self-type lets the method return the concrete builder
056 * type rather than {@code BeanStoreOverridable<?>}, preserving the fluent chain at the call site:
057 *
058 * <p class='bjava'>
059 *    SerializerSet.Builder <jv>builder</jv> = SerializerSet.<jsm>create</jsm>()
060 *       .overridingBeanStore(<jv>overlay</jv>)   <jc>// still SerializerSet.Builder, not BeanStoreOverridable&lt;?&gt;</jc>
061 *       .add(JsonSerializer.<jk>class</jk>);     <jc>// fluent chain preserved</jc>
062 * </p>
063 *
064 * <h5 class='section'>See Also:</h5><ul>
065 *    <li class='jc'>{@link BeanStore} - The base lookup interface this layer extends.
066 *    <li class='jc'>{@link BasicBeanStore} - The default writable implementation with the {@code overridingParent} slot.
067 * </ul>
068 *
069 * @param <B> The implementing builder's self type.
070 * @since 10.0.0
071 */
072public interface BeanStoreOverridable<B extends BeanStoreOverridable<B>> {
073
074   /**
075    * Installs the supplied {@link BeanStore} as the {@code overridingParent} of the underlying bean store
076    * used by this builder during construction-time reflective injection.
077    *
078    * <p>
079    * Passing {@code null} clears any previously-installed overlay.
080    *
081    * @param store The override layer.  Can be <jk>null</jk> to clear a previously-set value.
082    * @return This object.
083    * @since 10.0.0
084    */
085   B overridingBeanStore(BeanStore store);
086}