io.quarkus.arc.runtime.BeanContainer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of quarkus-arc Show documentation
Build time CDI dependency injection
There is a newer version: 3.17.0.CR1
package io.quarkus.arc.runtime;

import java.lang.annotation.Annotation;
import java.util.function.Supplier;

import io.quarkus.arc.ManagedContext;

/**
 * Represents a CDI bean container.
 * 
 * Extensions using this API can also leverage arbitrary methods from running {@link io.quarkus.arc.ArcContainer}
 * which can be obtained by invoking a static method {@link io.quarkus.arc.Arc#container()}.
 */
public interface BeanContainer {

    /**
     * Resolves a bean instance for given bean type and qualifiers.
     * 

     * Performs standard CDI resolution meaning it either returns a bean instance or throws a corresponding exception
     * if the dependency is either unsatisfied or ambiguous.
     *
     * @param beanType type of the bean
     * @param beanQualifiers bean qualifiers
     * @return a bean instance; never {@code null}
     */
     T beanInstance(Class beanType, Annotation... beanQualifiers);

    /**
     * Returns an instance factory for given bean type and qualifiers.
     * 

     * This method performs CDI ambiguous dependency resolution and throws and exception if there are two or more beans
     * with given type and qualifiers.
     * 

     * If no matching bean is found, uses a default fallback factory that will attempt to instantiate a non-CDI object
     * of the given class via no-args constructor.
     * 

     * If you need custom factory behavior, take a look at {@link #beanInstanceFactory(Supplier, Class, Annotation...)}
     *
     * @param type bean type
     * @param qualifiers bean qualifiers
     * @return a bean instance factory, never {@code null}
     */
     Factory beanInstanceFactory(Class type, Annotation... qualifiers);

    /**
     * Returns an instance factory for given bean type and qualifiers.
     * 

     * This method performs CDI ambiguous dependency resolution and throws and exception if there are two or more beans
     * with given type and qualifiers.
     * 

     * If no matching bean is found, delegates all calls to the supplied factory fallback.
     *
     * @param fallbackSupplier supplier to delegate to if there is no bean
     * @param type bean type
     * @param qualifiers bean qualifiers
     * @return a bean instance factory, never {@code null}
     */
     Factory beanInstanceFactory(Supplier> fallbackSupplier, Class type,
            Annotation... qualifiers);

    /**
     * 
     * ManagedContext requestContext = beanContainer.requestContext();
     * if (requestContext.isActive()) {
     *     // Perform action
     * } else {
     *     try {
     *         requestContext.activate();
     *         // Perform action
     *     } finally {
     *         requestContext.terminate();
     *     }
     * }
     * 
     *
     * @return the context for {@link jakarta.enterprise.context.RequestScoped}
     * @throws IllegalStateException If the container is not running
     */
    ManagedContext requestContext();

    interface Factory {

        Factory