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 Summary

Modifier and Type	Method	Description
<T> CreationalContext<T>	createCreationalContext(Contextual<T> contextual)	Obtain an instance of a CreationalContext for the given contextual type, or for a non-contextual object.
Instance<Object>	createInstance()	Obtains an Instance object to access to beans instances.
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.
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.
Context	getContext(Class<? extends Annotation> scopeType)	Obtains an active context object for the given scope .
Collection<Context>	getContexts(Class<? extends Annotation> scopeType)	Obtains all context objects, active and inactive, for the given scope.
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.
Object	getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx)	Obtains a contextual reference for a certain bean and a certain bean type of the bean.
boolean	isInterceptorBinding(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is an interceptor binding type .
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.
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.
boolean	isNormalScope(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is a normal scope type.
boolean	isQualifier(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is a qualifier type.
boolean	isScope(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is a scope type.
boolean	isStereotype(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is a stereotype.
<X> Bean<? extends X>	resolve(Set<Bean<? extends X>> beans)	Apply the ambiguous dependency resolution rules to a set of beans.
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.
<T> Set<ObserverMethod<? super T>>	resolveObserverMethods(T event, Annotation... qualifiers)	Return an ordered set of observer methods for an event.

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