Package org.apache.juneau.commons.inject

Class BeanInstantiator.Builder<T>

java.lang.Object
org.apache.juneau.commons.inject.BeanInstantiator.Builder<T>
Type Parameters:
T - The bean type being created.
Enclosing class:
BeanInstantiator<T>
public static class BeanInstantiator.Builder<T> extends Object
Builder for BeanInstantiator.

Holds all mutable configuration. Configure on a single thread, then call build() to obtain an immutable BeanInstantiator suitable for shared concurrent use. Most call sites use the run() shorthand which is equivalent to build().run().

Thread Safety:

Builder instances are not thread-safe. Configure on one thread, then either call build() to produce a thread-safe immutable BeanInstantiator, or call run() to one-shot create a bean from a single thread.

  • Constructor Details

    • Builder

      protected Builder(Class<T> beanType, BeanStore parentStore, String name, Object enclosingInstance)
      Constructor.
      Parameters:
      beanType - The bean type being created. Must not be null.
      parentStore - The parent bean store to use for resolving dependencies. Can be null (the internal bean store then has no parent fallback).
      name - The bean name. Can be null for unnamed beans.
      enclosingInstance - The enclosing instance object. Can be null (the outer-instance skip rule is then never applied).

  • Method Details

    • add

      public <T2> T2 add(Class<T2> type, T2 bean)
      Adds a bean to the internal bean store and returns it.
      Type Parameters:
      T2 - The bean type.
      Parameters:
      type - The bean type. Must not be null.
      bean - The bean instance. Can be null (stored as an explicit null binding, distinct from no binding at all).
      Returns:
      The bean that was added.

    • addBean

      public <T2> BeanInstantiator.Builder<T> addBean(Class<T2> type, T2 bean)
      Adds a bean to the internal bean store.
      Type Parameters:
      T2 - The bean type.
      Parameters:
      type - The bean type. Must not be null.
      bean - The bean instance. Can be null (stored as an explicit null binding, distinct from no binding at all).
      Returns:
      This object.

    • addBean

      public <T2> BeanInstantiator.Builder<T> addBean(Class<T2> type, T2 bean, String name)
      Adds a named bean to the internal bean store.
      Type Parameters:
      T2 - The bean type.
      Parameters:
      type - The bean type. Must not be null.
      bean - The bean instance. Can be null (stored as an explicit null binding, distinct from no binding at all).
      name - The bean name. Can be null for unnamed beans.
      Returns:
      This object.

    • asOptional

      public Optional<T> asOptional()
      Attempts to create the bean, returning an Optional instead of throwing an exception on failure.

      This is a non-throwing variant of run() that wraps the result in an Optional. If bean creation fails for any reason (missing dependencies, abstract class, interface, no matching constructor, etc.), this method returns Optional.empty() instead of throwing ExecutableException.

      This method is useful when bean creation failure is expected and should not be treated as exceptional, such as when implementing optional features or trying multiple creation strategies.

      Notes:
      • Unlike run(), this method catches ExecutableException and returns empty.
      • If a fallback is registered via fallback(Supplier), it will be used before returning empty, so this method will only return empty if both normal creation AND fallback fail.
      • The created bean is cached via Memoizer, so subsequent calls return the same instance unless reset() is called or configuration changes.
      • Post-creation hooks are still executed if creation succeeds.
      • Other exceptions (e.g., from post-creation hooks or fallback suppliers) are NOT caught and will propagate to the caller.
      Example:

      // Try to create, use default if it fails MyBean bean = BeanInstantiator .of(MyBean.class, myBeanStore) .asOptional() .orElse(new DefaultMyBean()); // Chain multiple creation attempts MyService service = BeanInstantiator.of(AdvancedService.class, store) .asOptional() .or(() -> BeanInstantiator.of(BasicService.class, store) .asOptional()) .orElseGet(() -> new FallbackService()); // Check if optional feature is available Optional<OptionalFeature> feature = BeanInstantiator .of(OptionalFeature.class, store) .asOptional(); if (feature.isPresent()) { feature.get().enable(); }

      Returns:
      An Optional containing the created bean, or Optional.empty() if creation failed.

    • asMemoizer

      public Memoizer<T> asMemoizer()
      Converts this creator into a memoizer.

      A Memoizer caches the result of the first Memoizer.get() call and returns that cached value for subsequent calls. The Memoizer.reset() method can be used to clear the cache, forcing the bean to be recreated on the next get() call.

      This is particularly useful when the bean store contents change and you want to recreate the bean with updated dependencies.

      Notes:
      • The returned Memoizer is thread-safe.
      • Each call to Memoizer.get() after a reset() will invoke run(), which may trigger dependency injection and post-creation hooks.
      • The memoizer inherits all Optional-like methods from NullableSupplier.
      Example:

      // Create a memoizer for a bean with dependencies BeanStore store = new BasicBeanStore(null); store.addBean(String.class, "initial"); Memoizer<MyBean> supplier = BeanInstantiator .of(MyBean.class, store) .asMemoizer(); // First call creates and caches the bean MyBean bean1 = supplier.get(); // Subsequent calls return the cached bean MyBean bean2 = supplier.get(); assertSame(bean1, bean2); // Update the bean store store.addBean(String.class, "updated"); // Reset forces recreation with updated dependencies supplier.reset(); MyBean bean3 = supplier.get(); assertNotSame(bean1, bean3); // New instance with updated deps

      Returns:
      A resettable supplier that caches the created bean until reset.

    • asSupplier

      public Supplier<T> asSupplier()
      Converts this creator into a supplier.
      Returns:
      A supplier that returns the results of the run() method.

    • type

      public BeanInstantiator.Builder<T> type(Class<? extends T> value)
      Specifies a subclass of the bean type to create.

      This allows you to create a specific implementation when the bean type is an interface, abstract class, or when you want to instantiate a customized subclass of a concrete class.

      Parameters:
      value - The subclass type to create. Cannot be null. Must be a subclass of beanType.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is not a subclass of beanType.

    • type

      public BeanInstantiator.Builder<T> type(ClassInfo value)
      Specifies a subclass of the bean type to create, via a ClassInfo reference.

      Convenience overload of type(Class) that accepts ClassInfo (or any subtype such as ClassMeta). The underlying class is extracted via ClassInfo.inner() and the subtype-relationship check happens at runtime.

      Parameters:
      value - The subclass type to create. Cannot be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is null or its underlying class is not a subclass of beanType.

    • builder

      public BeanInstantiator.Builder<T> builder(Class<?> value)
      Specifies the builder type to use for creating the bean.

      This method triggers builder type detection and instantiation for the specified type.

      The builder type must be valid, meaning it must have a build(), create(), or get() method that returns the bean type (or a parent of the bean type). The method may have @Inject or @Autowired annotation to allow injected parameters; otherwise, it must have no parameters.

      If the builder type is invalid (does not have a valid build method), this method throws an IllegalArgumentException.

      The builder will be instantiated by looking for:

      1. A static create() or builder() method that returns the builder type.
      2. A public constructor on the builder type with parameters that can be resolved from the bean store.
      3. A protected constructor on the builder type with parameters that can be resolved from the bean store.
      4. A package-private constructor on the builder type with parameters that can be resolved from the bean store. Private constructors are deliberately excluded.
      Parameters:
      value - The builder type. Cannot be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the builder type is invalid (does not have a valid build/create/get method).

    • builder

      public BeanInstantiator.Builder<T> builder(Object value)
      Specifies an existing builder instance to use for creating the bean.

      The builder instance's class must be a valid builder type, meaning it must have a build(), create(), or get() method that returns the bean type (or a parent of the bean type). The method may have @Inject or @Autowired annotation to allow injected parameters; otherwise, it must have no parameters.

      If the builder instance's class is invalid (does not have a valid build method), this method throws an IllegalArgumentException.

      Notes:
      • When specified, the builder type detection is bypassed.
      • The builder will be used to create the bean via:
        • A build()/create()/get() method on the builder (required). The method may have @Inject annotation to allow injected parameters.
      • The explicit builder instance is preserved even when reset() is called, unlike cached results from suppliers.
      Parameters:
      value - The builder instance. Cannot be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the builder instance's class is invalid (does not have a valid build/create/get method).

    • builderClassNames

      public BeanInstantiator.Builder<T> builderClassNames(String... names)
      Specifies custom class names to look for when auto-detecting builder inner classes.

      By default, BeanInstantiator looks for inner classes named "Builder". This method allows you to specify alternative class names.

      Notes:
      • Inner builder classes must be public, static, and pass builder validation (have a build/create/get method or be accepted by a bean constructor).
      • If multiple inner classes match, the first valid one found will be used.
      • This only affects inner class detection. It does not affect builders specified via builder(Class), builder(Object), or the @Builder annotation.
      • Calling this method replaces the default builder class names.
      Example:

      // Support alternative builder class naming conventions MyBean bean = BeanInstantiator .of(MyBean.class, myBeanStore) .builderClassNames("BuilderImpl", "Factory") .run();

      Parameters:
      names - The builder class names to look for. Cannot be null or contain null elements.
      Returns:
      This object.

    • builderMethodNames

      public BeanInstantiator.Builder<T> builderMethodNames(String... names)
      Specifies custom method names to look for when auto-detecting builder factory methods.

      By default, BeanInstantiator looks for static methods named "create" or "builder" that return a builder type. This method allows you to specify alternative method names.

      Notes:
      • Builder factory methods must be public, static, non-deprecated, and return a builder type (not the bean type itself).
      • If multiple builder factory methods match, the one with the most parameters that can be resolved from the bean store will be used.
      • This affects both builder type detection and builder instance creation.
      • Calling this method replaces the default builder method names.
      Example:

      // Support alternative builder factory method naming conventions MyBean bean = BeanInstantiator .of(MyBean.class) .builderMethodNames("newBuilder", "instance") .run();

      Parameters:
      names - The builder factory method names to look for. Cannot be null or contain null elements.
      Returns:
      This object.

    • buildMethodNames

      public BeanInstantiator.Builder<T> buildMethodNames(String... names)
      Specifies custom method names to look for when calling build methods on builder instances.

      By default, BeanInstantiator looks for instance methods named "build", "create", or "get" on the builder that return the bean type. This method allows you to specify alternative method names.

      Notes:
      • Build methods must be public, non-static, non-deprecated, and return the bean type (or a parent type of the bean type).
      • If the method has @Inject or @Autowired annotation, its parameters are resolved from the bean store.
      • If the method does not have @Inject annotation, it must have no parameters.
      • Calling this method replaces the default build method names.
      Example:

      // Support alternative build method naming conventions MyBean bean = BeanInstantiator .of(MyBean.class) .buildMethodNames("execute", "make") .run();

      Parameters:
      names - The build method names to look for. Cannot be null or contain null elements.
      Returns:
      This object.

    • cached

      public BeanInstantiator.Builder<T> cached()
      Enables caching mode.

      When caching mode is enabled, bean instances are cached using Memoizer, so multiple calls to run() will return the same instance unless reset() is called or configuration changes.

      When caching mode is disabled (the default), each call to run() will create a new bean instance by calling findBeanImpl() directly.

      Example:

      // Enable caching mode - same instance returned on each run() var creator = BeanInstantiator .of(MyBean.class) .cached(); MyBean bean1 = creator.run(); MyBean bean2 = creator.run(); // bean1 and bean2 are the same instance

      Returns:
      This object.

    • factoryAbstainOnNull

      public BeanInstantiator.Builder<T> factoryAbstainOnNull()
      Treat a null return value from a static factory method as a deliberate "abstain" signal.

      By default, when a static factory method (one of factoryMethodNames(String...)) matches and is invoked, but returns null, run() falls through to constructor lookup as if the factory method weren't there. This works well when the factory method is just an alternate construction path.

      Some factory-method patterns instead use a null return value as a deliberate "this implementation does not handle the input — try the next strategy" signal, expecting the caller to interpret the null as a definitive answer. The classic example is a RestOpArg subclass whose static create(ParameterInfo) returns null when the parameter isn't annotated with the marker the subclass handles, so the caller can move on to the next subclass in the chain. Falling through to the (always-present) constructor in that case would silently materialize an arg that doesn't apply.

      When this flag is enabled, a null return from the matching factory method is propagated out of run() unchanged — constructor lookup is skipped. This matches legacy BeanCreator semantics for static create() / builder() / getInstance() methods.

      Example:

      // AttributeArg.create(ParameterInfo) returns null if @Attr is not present. // Without factoryAbstainOnNull, BeanInstantiator would then invoke the AttributeArg(ParameterInfo) // constructor and return a bogus instance. RestOpArg arg = BeanInstantiator .of(RestOpArg.class, store) .type(AttributeArg.class) .factoryMethodNames("getInstance", "create") .factoryAbstainOnNull() .run();

      Returns:
      This object.

    • preferZeroArgConstructor

      public BeanInstantiator.Builder<T> preferZeroArgConstructor()
      Prefer a zero-argument constructor when one exists, instead of injecting via the longest constructor.

      By default, BeanInstantiator sorts public constructors by parameter count descending: the constructor with the most resolvable parameters wins, encouraging full constructor injection. This is the right default for most beans, but it doesn't fit every use case.

      The classic mismatch is parameterized container types like TreeMap, which expose:

      • TreeMap()
      • TreeMap(Comparator)
      • TreeMap(Map<? extends K,? extends V>)
      • TreeMap(SortedMap)
      The default selection picks the Map copy-constructor — but that Map<? extends K,? extends V> parameter doesn't satisfy v2 inject-collection auto-resolution (which only handles Map<String,T>), so injection fails at runtime even though ParameterInfo.canResolve(BeanStore, Object...) optimistically said yes. Callers that just want "give me a fresh empty container" should use this flag.

      When this flag is enabled, if beanSubType declares a public no-arg constructor, that constructor is used unconditionally and other constructors are ignored. This matches legacy BeanCreator behavior for the same use case (legacy filtered out the multi-arg ctors via hasAllParams returning false, since the legacy bean store didn't auto-resolve raw Map/Collection parameter types).

      Example:

      // Instantiating an arbitrary Map subclass — prefer the no-arg ctor over copy-ctors. Map<?,?> m = BeanInstantiator .of(Map.class) .type(treeMapClass) .preferZeroArgConstructor() .run();

      Returns:
      This object.

    • build

      public BeanInstantiator<T> build()
      Compiles this builder into a BeanInstantiator.

      The returned instance exposes only run/read methods (no setters). The compiled instance shares its caching state with this builder so that cached() memoization is consistent across both compiled and shorthand call paths.

      Returns:
      A new BeanInstantiator backed by this builder's configuration.

    • run

      public T run()
      Shortcut for build().run().

      Most call sites do not store the BeanInstantiator and therefore call this shortcut. Repeated calls share caching with any compiled BeanInstantiator produced by build().

      Returns:
      A new bean with all dependencies injected.
      Throws:
      ExecutableException - if bean could not be created.

    • debug

      public BeanInstantiator.Builder<T> debug()
      Enables debug mode to track the bean creation process.

      When debug mode is enabled, the creator logs each step of the bean creation process to an internal list. This log can be retrieved via getDebugLog() to understand which creation path was taken, why creation might have failed, or to troubleshoot unexpected behavior.

      Notes:
      • Debug logs include: builder detection, factory method attempts, constructor attempts, dependency resolution, injection, hooks execution, validation, and fallback usage.
      • The debug log is reset each time run() or asOptional() is called.
      • Debug mode has minimal performance impact but should generally be disabled in production.
      • The debug log is stored in memory and can be retrieved after bean creation.
      • When caching is enabled via cached(), the log reflects the first creation only (subsequent calls return the cached instance unless reset() is called).
      Example:

      // Enable debug mode var creator = BeanInstantiator .of(MyBean.class, store) .debug(); MyBean bean = creator.run(); // Print debug log creator.getDebugLog().forEach(System.out::println);

      Returns:
      This object.

    • factoryMethodNames

      public BeanInstantiator.Builder<T> factoryMethodNames(String... names)
      Specifies custom static factory method names to look for when creating the bean.

      By default, BeanInstantiator looks for a static getInstance() method when attempting to create beans without a builder. This method allows you to specify alternative factory method names to support non-standard naming conventions.

      Notes:
      • Factory methods must be public, static, non-deprecated, and return the bean type.
      • If multiple factory methods match, the one with the most parameters that can be resolved from the bean store will be used.
      • Factory methods are attempted before constructors in the bean creation order.
      • This setting only affects factory method detection; it does not affect builder detection.
      • Calling this method replaces the default factory method names.
      Example:

      // Support multiple factory method naming conventions MyBean bean = BeanInstantiator .of(MyBean.class, myBeanStore) .factoryMethodNames("of", "from", "create", "newInstance") .run();

      Parameters:
      names - The factory method names to look for. Cannot be null or contain null elements.
      Returns:
      This object.

    • fallback

      public BeanInstantiator.Builder<T> fallback(Supplier<? extends T> fallback)
      Specifies a fallback supplier to use if bean creation fails.

      When a fallback supplier is registered, if bean creation fails (throws ExecutableException), instead of propagating the exception, the fallback supplier will be invoked to provide a default instance.

      This enables graceful degradation when bean creation cannot succeed, such as when optional features or dependencies are not available.

      Notes:
      • The fallback supplier is only invoked if bean creation fails. If bean creation succeeds normally, the fallback is never called.
      • Fallbacks are checked after all normal creation attempts (builders, factory methods, constructors).
      • The fallback-provided instance will have post-creation hooks executed on it.
      • If the fallback is used, that instance is cached via Memoizer and returned on subsequent calls unless reset() is called or configuration changes.
      • Only one fallback can be registered. Subsequent calls to this method will replace the previous fallback.
      • If the fallback supplier itself throws an exception, that exception will propagate to the caller.
      • To use a pre-created instance as a fallback, wrap it in a supplier: fallback(() -> myInstance).
      Example:

      // Provide a default instance if creation fails MyService service = BeanInstantiator .of(MyService.class, myBeanStore) .fallback(() -> new DefaultMyService()) .run(); // Use a pre-created instance as fallback MyService defaultService = new DefaultMyService(); MyService service2 = BeanInstantiator .of(MyService.class, myBeanStore) .fallback(() -> defaultService) .run();

      Parameters:
      fallback - The fallback supplier. Cannot be null.
      Returns:
      This object.

    • getBeanSubType

      protected ClassInfo getBeanSubType()
      Returns the bean subtype class info if specified, or the normal bean type if not.

      If type(Class) was called to specify a subtype, returns that subtype. Otherwise, returns the original bean type passed to BeanInstantiator.of(Class).

      Returns:
      The bean subtype class info, or the bean type class info if no subtype was specified.

    • getName

      public String getName()
      Returns the name of the bean being created.

      Returns the name that was passed to BeanInstantiator.of(Class, BeanStore, String, Object), or null if no name was specified.

      Returns:
      The bean name, or null if not set.

    • getBeanSubTypes

      protected List<ClassInfo> getBeanSubTypes()
      Returns the list of bean subtype classes, including the bean subtype, bean type, and all classes in between.

      This method returns a list that starts with the bean subtype (if different from bean type) and includes all parent classes up to and including the bean type. If no subtype was specified, the list will contain only the bean type.

      Example:

      // If beanType is A and beanSubType is C (extends B extends A) // getBeanSubTypes() returns: [C, B, A]

      Returns:
      A list of bean subtype class info objects, never null.

    • getBuilder

      public <B> Optional<B> getBuilder()
      Returns the builder instance if one has been created or specified.
      Type Parameters:
      B - The builder type.
      Returns:
      The builder instance wrapped in an Optional, or an empty optional if no builder exists.

    • getBuilderType

      protected ClassInfo getBuilderType()
      Returns the builder type class info determined by findBuilderType().
      Returns:
      The builder type class info, or null if no builder type was determined.

    • getBuilderTypes

      protected List<ClassInfo> getBuilderTypes()
      Returns the list of builder types, including the primary builder type and any builder types found in the builder's parent hierarchy.

      This method returns a list that includes the primary builder type and all builder types found by traversing the builder's parent hierarchy. This allows parent builders to be resolved as injectable types.

      Example:

      // Class A with builder class A { static class Builder { A create() { return new A(); } } } // Class B extends A with builder class B extends A { static class Builder extends A.Builder { B create() { return new B(); } } } // When creating B, getBuilderTypes() returns: [B.Builder, A.Builder]

      Returns:
      A list of builder type class info objects, never null.

    • getDebugLog

      public List<String> getDebugLog()
      Returns an unmodifiable list of debug log entries from the last bean creation attempt.

      This method returns the detailed log of steps taken during the most recent call to run() or asOptional(). The log is only populated when debug() mode is enabled.

      Notes:
      • Returns an empty list if debug() was not called or if no creation has been attempted.
      • The log is reset at the beginning of each run() call.
      • Since run() uses a cached Memoizer, the log reflects only the first creation (subsequent calls return the cached instance unless reset() is called).
      • The returned list is unmodifiable.
      Example:

      var creator = BeanInstantiator.of(MyBean.class, store) .debug(); try { creator.run(); } catch (ExecutableException e) { // Print debug log to understand why creation failed creator.getDebugLog().forEach(System.err::println); }

      Returns:
      An unmodifiable list of debug log entries.

    • impl

      public BeanInstantiator.Builder<T> impl(T value)
      Specifies an existing bean implementation to use instead of creating a new instance.

      When specified, the bean creation logic is bypassed and this implementation is returned directly from run(), after performing dependency injection on it.

      Notes:
      • The bean implementation will still have its fields and methods injected via ClassInfo.inject(Object, BeanStore).
      • This is useful when you want to provide a pre-configured instance but still benefit from dependency injection.
      • The explicit implementation is preserved even when reset() is called, unlike cached results from suppliers.
      Parameters:
      value - The bean implementation instance. Can be null, in which case no explicit implementation is used.
      Returns:
      This object.

    • postCreateHook

      public BeanInstantiator.Builder<T> postCreateHook(Consumer<T> hook)
      Registers a post-creation hook to run after the bean is created.

      Post-creation hooks are executed after the bean is instantiated and after dependency injection has been performed via ClassInfo.inject(Object, BeanStore).

      Multiple hooks can be registered and they will be executed in the order they were added.

      Notes:
      • Hooks are executed every time run() is called. Since run() uses a cached Memoizer, hooks are only executed once unless reset() is called.
      • Hooks are executed after dependency injection, so all @Inject fields and methods will have been populated before the hook runs.
      • Hooks can be used for custom initialization logic, logging, wrapping beans with proxies, or any other post-creation processing.
      • If a hook throws an exception, bean creation will fail and the exception will propagate to the caller.
      • The hook receives the fully initialized bean instance as its parameter.
      Example:

      // Register multiple post-creation hooks MyService service = BeanInstantiator .of(MyService.class, myBeanStore) .postCreateHook(s -> s.initialize()) .postCreateHook(s -> s.loadConfiguration()) .postCreateHook(s -> logger.info("Created service: " + s)) .run();

      Parameters:
      hook - The post-creation hook to run after bean creation. Cannot be null.
      Returns:
      This object.

    • silent

      public BeanInstantiator.Builder<T> silent()
      Suppresses warning-level log output from this builder.

      Useful when asOptional() is preferred and you don't want the underlying log noise that accompanies fallback or factory-abstention paths.

      Errors and exceptions are still thrown normally; only descriptive log entries are suppressed.

      Returns:
      This object.

    • description

      public BeanInstantiator.Builder<T> description(String value)
      Sets a human-readable description used in log entries and error messages.

      Useful when the bean type alone doesn't provide enough context (e.g. multiple instances of the same type).

      Parameters:
      value - The description. Cannot be null.
      Returns:
      This object.

    • wrap

      public BeanInstantiator.Builder<T> wrap(UnaryOperator<T> wrapper)
      Registers a transformation to apply to the created bean before it is returned.

      Multiple wrappers may be registered; they are applied in registration order. Each wrapper receives the output of the previous wrapper.

      Example:

      BeanInstantiator.of(MyService.class, store) .wrap(LoggingProxy::wrap) .wrap(MetricsProxy::wrap) .run();

      Parameters:
      wrapper - The wrapper. Cannot be null.
      Returns:
      This object.

    • validate

      public BeanInstantiator.Builder<T> validate(Predicate<T> predicate, String message)
      Registers a post-creation validator.

      The predicate is invoked on the created bean. If it returns false, an ExecutableException is thrown with the supplied message.

      Parameters:
      predicate - The predicate. Cannot be null.
      message - The error message used when the predicate returns false. Cannot be null.
      Returns:
      This object.

    • or

      public BeanInstantiator.Builder<T> or(BeanInstantiator.Builder<? extends T> alternative)
      Registers an alternative BeanInstantiator.Builder to consult if this builder fails to create the bean.

      Multiple alternatives may be registered. They are tried in registration order. The first one that succeeds returns its bean; if all fail, the last exception is propagated.

      Parameters:
      alternative - The alternative builder. Cannot be null.
      Returns:
      This object.

    • builderInitializer

      public BeanInstantiator.Builder<T> builderInitializer(Consumer<Object> initializer)
      Registers a callback that is invoked on the builder instance before build() is called.

      Multiple initializers may be registered; they are applied in registration order. The callback receives the builder instance after it has been retrieved (from the bean store, static factory, or constructor) but before any auto-wiring or inject-based processing.

      The callback is typed as Consumer<Object> because the builder type is generally not statically known at the call site (an unchecked cast will typically be required inside the lambda).

      Parameters:
      initializer - The initializer. Cannot be null.
      Returns:
      This object.

    • injectBuilder

      public BeanInstantiator.Builder<T> injectBuilder()
      Enables @Inject / @Autowired field and method injection on the builder instance.

      When set, after the builder is retrieved (from the bean store, static factory, or constructor), its fields and methods annotated with @Inject or @Autowired are auto-resolved from the bean store. This is similar to the post-construction injection performed on the resulting bean, but applied to the builder.

      Default is false (opt-in).

      Returns:
      This object.

    • autoWireBuilder

      public BeanInstantiator.Builder<T> autoWireBuilder()
      Enables auto-wiring of bean store entries into matching setter methods on the builder.

      When set, after the builder is retrieved, every public single-argument setter method is inspected. If the bean store has a bean of a type assignable to the setter's parameter type, the setter is invoked with that bean.

      If a parameter is of type Supplier<X> and the bean store has a bean of type X, the bean is wrapped in a supplier and passed to the setter (when unwrapSuppliers defaulting to true).

      Default is false (opt-in).

      Returns:
      This object.

    • noBuilder

      public BeanInstantiator.Builder<T> noBuilder()
      Disables builder-based bean creation entirely.

      When set, builder detection is skipped and the bean is instantiated directly via static factory methods or constructors. This is useful when a Builder class is co-located with the bean type (e.g. Foo.Builder) but the caller wants to use a builder-taking constructor instead.

      Example:

      BeanInstantiator.of(BasicSwaggerProvider.class, beanStore) .add(SwaggerProvider.Builder.class, this) .noBuilder() .run();

      Returns:
      This object.

    • scope

      public BeanInstantiator.Builder<T> scope(BeanInstantiator.Scope value)
      Sets the lifecycle scope of the bean being created.

      BeanInstantiator.Scope.SINGLETON is equivalent to calling cached(); BeanInstantiator.Scope.PROTOTYPE resets the cached flag.

      Parameters:
      value - The scope. Cannot be null.
      Returns:
      This object.

    • copy

      public BeanInstantiator.Builder<T> copy()
      Returns a copy of this builder with the same configuration.

      The returned builder shares no mutable state with this one and may be configured independently.

      Returns:
      A new builder pre-populated with this builder's configuration.

    • reset

      public BeanInstantiator.Builder<T> reset()
      Resets the builder, builderType, and beanImpl suppliers.

      This causes them to be re-evaluated on the next call to run().

      Notes:
      • If an explicit builder instance was set via builder(Object), it is preserved and not cleared by this method.
      • If an explicit implementation was set via impl(Object), it is preserved and not cleared by this method.
      • Only the cached results from suppliers are reset, not the configuration itself.
      Returns:
      This object.