Package jakarta.enterprise.inject.spi

Interface BeanContainer

All Known Subinterfaces:
BeanManager, ELAwareBeanManager
public interface BeanContainer

BeanContainer is a superclass of BeanManager containing capabilities that are portable across all CDI environments.

Provides operations for obtaining contextual references for beans, along with many other operations of use to CDI applications.

Any bean may obtain an instance of BeanContainer by injecting it: 

 @Inject
 BeanContainer container;
Since:
4.0
Author:
Matej Novotny

  • Method Details

    • getReference

      Object getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx)

      Obtains a contextual reference for a certain bean and a certain bean type of the bean.

      Parameters:
      bean - the Bean object representing the bean
      beanType - a bean type that must be implemented by any client proxy that is returned
      ctx - a CreationalContext that may be used to destroy any object with scope Dependent that is created
      Returns:
      a contextual reference representing the bean
      Throws:
      IllegalArgumentException - if the given type is not a bean type of the given bean
      IllegalStateException - if called during application initialization, before the AfterDeploymentValidation event is fired.

    • createCreationalContext

      <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual)
      Obtain an instance of a CreationalContext for the given contextual type, or for a non-contextual object.
      Type Parameters:
      T - type of the instance
      Parameters:
      contextual - the Contextual, or a null value in the case of a non-contextual object
      Returns:
      the new CreationalContext

    • getBeans

      Set<Bean<?>> getBeans(Type beanType, Annotation... qualifiers)
      Return the set of beans which have the given required type and qualifiers and are available for injection in the module or library containing the class into which the BeanManager/BeanContainer was injected or, in the Jakarta EE environment, the Jakarta EE component from whose JNDI environment namespace the BeanManager/BeanContainer was obtained, according to the rules of typesafe resolution. If no qualifiers are given, the default qualifier is assumed.

      Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return beans discovered by the container before the AfterBeanDiscovery event is fired.

      Parameters:
      beanType - the required bean type
      qualifiers - the required qualifiers
      Returns:
      the resulting set of beans
      Throws:
      IllegalArgumentException - if the given type represents a type variable
      IllegalArgumentException - if two instances of the same non repeating qualifier type are given
      IllegalArgumentException - if an instance of an annotation that is not a qualifier type is given
      IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

    • getBeans

      Set<Bean<?>> getBeans(String name)
      Return the set of beans which have the given EL name and are available for injection in the module or library containing the class into which the BeanManager/BeanContainer was injected or, in the Jakarta EE environment, the Jakarta EE component from whose JNDI environment namespace the BeanManager/BeanContainer was obtained, according to the rules of EL name resolution.

      Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return beans discovered by the container before the AfterBeanDiscovery event is fired.

      Parameters:
      name - the EL name
      Returns:
      the resulting set of beans
      Throws:
      IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

    • resolve

      <X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans)
      Apply the ambiguous dependency resolution rules to a set of beans.

      Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return beans discovered by the container before the AfterBeanDiscovery event is fired.

      Type Parameters:
      X - a common type of the beans
      Parameters:
      beans - a set of beans of the given type
      Returns:
      the resolved bean, or null if null or an empty set is passed
      Throws:
      AmbiguousResolutionException - if the ambiguous dependency resolution rules fail
      IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

    • resolveObserverMethods

      <T> Set<ObserverMethod<? super T>> resolveObserverMethods(T event, Annotation... qualifiers)
      Return an ordered set of observer methods for an event.

      Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return observers discovered by the container before the AfterBeanDiscovery event is fired.

      Type Parameters:
      T - the type of the event
      Parameters:
      event - the event object
      qualifiers - the event qualifiers
      Returns:
      the resulting set of observer methods
      Throws:
      IllegalArgumentException - if the runtime type of the event object contains a type variable
      IllegalArgumentException - if two instances of the same non repeating qualifier type are given
      IllegalArgumentException - if an instance of an annotation that is not a qualifier type is given
      IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

    • resolveInterceptors

      List<Interceptor<?>> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings)
      Return an ordered list of enabled interceptors for a set of interceptor bindings and a type of interception and which are enabled in the module or library containing the class into which the BeanManager/BeanContainer was injected or, in the Jakarta EE environment, the Jakarta EE component from whose JNDI environment namespace the BeanManager/BeanContainer was obtained.

      Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return interceptors discovered by the container before the AfterBeanDiscovery event is fired.

      Parameters:
      type - the type of the interception
      interceptorBindings - the interceptor bindings
      Returns:
      the resulting set of interceptors
      Throws:
      IllegalArgumentException - if no interceptor binding type is given
      IllegalArgumentException - if two instances of the same interceptor binding type are given
      IllegalArgumentException - if an instance of an annotation that is not an interceptor binding type is given
      IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

    • isScope

      boolean isScope(Class<? extends Annotation> annotationType)
      Test the given annotation type to determine if it is a scope type.
      Parameters:
      annotationType - the annotation type
      Returns:
      true if the annotation type is a scope type

    • isNormalScope

      boolean isNormalScope(Class<? extends Annotation> annotationType)
      Test the given annotation type to determine if it is a normal scope type.
      Parameters:
      annotationType - the annotation type
      Returns:
      true if the annotation type is a normal scope type

    • isQualifier

      boolean isQualifier(Class<? extends Annotation> annotationType)
      Test the given annotation type to determine if it is a qualifier type.
      Parameters:
      annotationType - the annotation type
      Returns:
      true if the annotation type is a qualifier type

    • isStereotype

      boolean isStereotype(Class<? extends Annotation> annotationType)
      Test the given annotation type to determine if it is a stereotype.
      Parameters:
      annotationType - the annotation type
      Returns:
      true if the annotation type is a stereotype

    • isInterceptorBinding

      boolean isInterceptorBinding(Class<? extends Annotation> annotationType)
      Test the given annotation type to determine if it is an interceptor binding type .
      Parameters:
      annotationType - the annotation to test
      Returns:
      true if the annotation type is a interceptor binding type

    • getContext

      Context getContext(Class<? extends Annotation> scopeType)
      Obtains an active context object for the given scope .
      Parameters:
      scopeType - the scope
      Returns:
      the context object
      Throws:
      ContextNotActiveException - if there is no active context object for the given scope
      IllegalArgumentException - if there is more than one active context object for the given scope

    • getContexts

      Collection<Context> getContexts(Class<? extends Annotation> scopeType)
      Obtains all context objects, active and inactive, for the given scope.
      Parameters:
      scopeType - the scope; must not be null
      Returns:
      immutable collection of context objects; never null, but may be empty

    • getEvent

      Event<Object> getEvent()
      Returns an instance of Event with specified type java.lang.Object and specified qualifier @Default It allows typesafe synchronous or asynchronous event firing without injection of Event built-in bean requirement.
      Returns:
      a new Event object whose event type is Object and qualifier @Default
      Since:
      2.0

    • createInstance

      Instance<Object> createInstance()
      Obtains an Instance object to access to beans instances.

      The returned Instance object can only access instances of beans that are available for injection in the module or library containing the class into which the BeanManager/BeanContainer was injected or, in the Jakarta EE environment, the Jakarta EE component from whose JNDI environment namespace the BeanContainer was obtained, according to the rules of typesafe resolution.

      Instances of dependent scoped beans obtained with this Instance must be explicitly destroyed by calling Instance.destroy(Object)

      If no qualifier is passed to Instance.select(java.lang.annotation.Annotation...) method, the @Default qualifier is assumed.

      Returns:
      an Instance object to request beans instances
      Throws:
      IllegalStateException - if called during application initialization, before the AfterDeploymentValidation event is fired.
      Since:
      2.0

    • isMatchingBean

      boolean isMatchingBean(Set<Type> beanTypes, Set<Annotation> beanQualifiers, Type requiredType, Set<Annotation> requiredQualifiers)
      Returns true if a bean with given bean types and qualifiers would be assignable to an injection point with given required type and required qualifiers, false otherwise.

      In line with the specification for beans and typesafe resolution, the set of beanTypes is considered to always include java.lang.Object. Types in beanTypes that are not legal bean types are ignored. The set of beanQualifiers is considered to always include @Any and also include @Default when it contains no other qualifier but @Any and @Named. The set of requiredQualifiers is considered to include @Default when it is empty.

      Throws IllegalArgumentException if any of the arguments is null or if any of the beanQualifiers or requiredQualifiers is not a qualifier annotation.

      Parameters:
      beanTypes - bean types of a bean; must not be null
      beanQualifiers - qualifiers of a bean; must not be null
      requiredType - required type of an injection point; must not be null
      requiredQualifiers - required qualifiers of an injection point; must not be null
      Returns:
      true if a bean with given bean types and qualifiers would be assignable to an injection point with given required type and required qualifiers, false otherwise

    • isMatchingEvent

      boolean isMatchingEvent(Type specifiedType, Set<Annotation> specifiedQualifiers, Type observedEventType, Set<Annotation> observedEventQualifiers)
      Returns true if an event with given specified type and specified qualifiers would match an observer method with given observed event type and observed event qualifiers, false otherwise.

      For the purpose of observer resolution, the specifiedType is used as the event type directly (because there is no event object in this API) and specifiedQualifiers are used as event qualifiers. In line with the specification for events and observer resolution, the set of event qualifiers is considered to always include @Any. Further, an empty set of specifiedQualifiers is considered to match the set of observedEventQualifiers which contains @Default.

      Throws IllegalArgumentException if any of the arguments is null, if the specifiedType contains a type variable, or if any of the specifiedQualifiers or observedEventQualifiers is not a qualifier annotation.

      Parameters:
      specifiedType - specified type of an event; must not be null
      specifiedQualifiers - specified qualifiers of an event; must not be null
      observedEventType - observed event type of an observer method; must not be null
      observedEventQualifiers - observed event qualifiers on an observer method; must not be null
      Returns:
      true if an event object with given type and qualifiers would result in notifying an observer method with given observed event type and observed event qualifiers, false otherwise