Top Description Methods
jakarta.enterprise.inject.spi

public Interface BeanContainer

Known Direct Subinterfaces
jakarta.enterprise.inject.spi.BeanManager
Imports
java.lang.annotation.Annotation, java.lang.reflect.Type, java.util.Collection, .List, .Set, jakarta.enterprise.context.ContextNotActiveException, .Dependent, jakarta.enterprise.context.spi.Context, .Contextual, .CreationalContext, jakarta.enterprise.event.Event, jakarta.enterprise.inject.AmbiguousResolutionException, .Default, .Instance, .Stereotype

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;
Author
Matej Novotny
Since
4.0

Method Summary

Modifier and TypeMethod and Description
public <
type of the instance
T
>
CreationalContext<T>

Returns:

the new CreationalContext
createCreationalContext
(Contextual<T>
the Contextual, or a null value in the case of a non-contextual object
contextual
)

Obtain an instance of a CreationalContext for the given contextual type, or for a non-contextual object.

public Instance<Object>

Returns:

an Instance object to request beans instances
createInstance
()

Obtains an Instance object to access to beans instances.

public Set<Bean<?>>

Returns:

the resulting set of beans
getBeans
(Type
the required bean type
beanType
,
Annotation...
the required qualifiers
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.

public Set<Bean<?>>

Returns:

the resulting set of beans
getBeans
(String
the EL name
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.

public Context

Returns:

the context object
getContext
(Class<? extends Annotation>
the scope
scopeType
)

Obtains an active context object for the given scope .

public Collection<Context>

Returns:

immutable collection of context objects; never null, but may be empty
getContexts
(Class<? extends Annotation>
the scope; must not be null
scopeType
)

Obtains all context objects, active and inactive, for the given scope.

public Event<Object>

Returns:

a new Event object whose event type is Object and qualifier @Default
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.

public Object

Returns:

a contextual reference representing the bean
getReference
(Bean<?>
the Bean object representing the bean
bean
,
Type
a bean type that must be implemented by any client proxy that is returned
beanType
,
CreationalContext<?>
a CreationalContext that may be used to destroy any object with scope Dependent that is created
ctx
)

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

public boolean

Returns:

true if the annotation type is a interceptor binding type
isInterceptorBinding
(Class<? extends Annotation>
the annotation to test
annotationType
)

Test the given annotation type to determine if it is an interceptor binding type .

public boolean

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
isMatchingBean
(Set<Type>
bean types of a bean; must not be null
beanTypes
,
Set<Annotation>
qualifiers of a bean; must not be null
beanQualifiers
,
Type
required type of an injection point; must not be null
requiredType
,
Set<Annotation>
required qualifiers of an injection point; must not be null
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.

public boolean

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
isMatchingEvent
(Type
specified type of an event; must not be null
specifiedType
,
Set<Annotation>
specified qualifiers of an event; must not be null
specifiedQualifiers
,
Type
observed event type of an observer method; must not be null
observedEventType
,
Set<Annotation>
observed event qualifiers on an observer method; must not be null
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.

public boolean

Returns:

true if the annotation type is a normal scope type
isNormalScope
(Class<? extends Annotation>
the annotation type
annotationType
)

Test the given annotation type to determine if it is a normal scope type.

public boolean

Returns:

true if the annotation type is a qualifier type
isQualifier
(Class<? extends Annotation>
the annotation type
annotationType
)

Test the given annotation type to determine if it is a qualifier type.

public boolean

Returns:

true if the annotation type is a scope type
isScope
(Class<? extends Annotation>
the annotation type
annotationType
)

Test the given annotation type to determine if it is a scope type.

public boolean

Returns:

true if the annotation type is a stereotype
isStereotype
(Class<? extends Annotation>
the annotation type
annotationType
)

Test the given annotation type to determine if it is a stereotype.

public <
a common type of the beans
X
>
Bean<? extends X>

Returns:

the resolved bean, or null if null or an empty set is passed
resolve
(Set<Bean<? extends X>>
a set of beans of the given type
beans
)

Apply the ambiguous dependency resolution rules to a set of beans.

public List<Interceptor<?>>

Returns:

the resulting set of interceptors
resolveInterceptors
(InterceptionType
the type of the interception
type
,
Annotation...
the interceptor bindings
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.

public <
the type of the event
T
>
Set<ObserverMethod<? super T>>

Returns:

the resulting set of observer methods
resolveObserverMethods
(T
the event object
event
,
Annotation...
the event qualifiers
qualifiers
)

Return an ordered set of observer methods for an event.

Method Detail

createCreationalContextback to summary
public <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual)

Obtain an instance of a CreationalContext for the given contextual type, or for a non-contextual object.

Parameters
<T>
type of the instance
contextual:Contextual<T>

the Contextual, or a null value in the case of a non-contextual object

Returns:CreationalContext<T>

the new CreationalContext

createInstanceback to summary
public 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 method, the @Default qualifier is assumed.

Returns:Instance<Object>

an Instance object to request beans instances

Exceptions
IllegalStateException:
if called during application initialization, before the AfterDeploymentValidation event is fired.
Since
2.0
getBeansback to summary
public 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:Type

the required bean type

qualifiers:Annotation[]

the required qualifiers

Returns:Set<Bean<?>>

the resulting set of beans

Exceptions
IllegalArgumentException:
  • if the given type represents a type variable
  • if two instances of the same non repeating qualifier type are given
  • 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.
getBeansback to summary
public 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:String

the EL name

Returns:Set<Bean<?>>

the resulting set of beans

Exceptions
IllegalStateException:
if called during application initialization, before the AfterBeanDiscovery event is fired.
getContextback to summary
public Context getContext(Class<? extends Annotation> scopeType)

Obtains an active context object for the given scope .

Parameters
scopeType:Class<? extends Annotation>

the scope

Returns:Context

the context object

Exceptions
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
getContextsback to summary
public Collection<Context> getContexts(Class<? extends Annotation> scopeType)

Obtains all context objects, active and inactive, for the given scope.

Parameters
scopeType:Class<? extends Annotation>

the scope; must not be null

Returns:Collection<Context>

immutable collection of context objects; never null, but may be empty

getEventback to summary
public 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:Event<Object>

a new Event object whose event type is Object and qualifier @Default

Since
2.0
getReferenceback to summary
public 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:Bean<?>

the Bean object representing the bean

beanType:Type

a bean type that must be implemented by any client proxy that is returned

ctx:CreationalContext<?>

a CreationalContext that may be used to destroy any object with scope Dependent that is created

Returns:Object

a contextual reference representing the bean

Exceptions
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.
isInterceptorBindingback to summary
public boolean isInterceptorBinding(Class<? extends Annotation> annotationType)

Test the given annotation type to determine if it is an interceptor binding type .

Parameters
annotationType:Class<? extends Annotation>

the annotation to test

Returns:boolean

true if the annotation type is a interceptor binding type

isMatchingBeanback to summary
public 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:Set<Type>

bean types of a bean; must not be null

beanQualifiers:Set<Annotation>

qualifiers of a bean; must not be null

requiredType:Type

required type of an injection point; must not be null

requiredQualifiers:Set<Annotation>

required qualifiers of an injection point; must not be null

Returns:boolean

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

isMatchingEventback to summary
public 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:Type

specified type of an event; must not be null

specifiedQualifiers:Set<Annotation>

specified qualifiers of an event; must not be null

observedEventType:Type

observed event type of an observer method; must not be null

observedEventQualifiers:Set<Annotation>

observed event qualifiers on an observer method; must not be null

Returns:boolean

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

isNormalScopeback to summary
public boolean isNormalScope(Class<? extends Annotation> annotationType)

Test the given annotation type to determine if it is a normal scope type.

Parameters
annotationType:Class<? extends Annotation>

the annotation type

Returns:boolean

true if the annotation type is a normal scope type

isQualifierback to summary
public boolean isQualifier(Class<? extends Annotation> annotationType)

Test the given annotation type to determine if it is a qualifier type.

Parameters
annotationType:Class<? extends Annotation>

the annotation type

Returns:boolean

true if the annotation type is a qualifier type

isScopeback to summary
public boolean isScope(Class<? extends Annotation> annotationType)

Test the given annotation type to determine if it is a scope type.

Parameters
annotationType:Class<? extends Annotation>

the annotation type

Returns:boolean

true if the annotation type is a scope type

isStereotypeback to summary
public boolean isStereotype(Class<? extends Annotation> annotationType)

Test the given annotation type to determine if it is a stereotype.

Parameters
annotationType:Class<? extends Annotation>

the annotation type

Returns:boolean

true if the annotation type is a stereotype

resolveback to summary
public <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.

Parameters
<X>
a common type of the beans
beans:Set<Bean<? extends X>>

a set of beans of the given type

Returns:Bean<? extends X>

the resolved bean, or null if null or an empty set is passed

Exceptions
AmbiguousResolutionException:
if the ambiguous dependency resolution rules fail
IllegalStateException:
if called during application initialization, before the AfterBeanDiscovery event is fired.
resolveInterceptorsback to summary
public 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:InterceptionType

the type of the interception

interceptorBindings:Annotation[]

the interceptor bindings

Returns:List<Interceptor<?>>

the resulting set of interceptors

Exceptions
IllegalArgumentException:
  • if no interceptor binding type is given
  • if two instances of the same interceptor binding type are given
  • 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.
resolveObserverMethodsback to summary
public <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.

Parameters
<T>
the type of the event
event:T

the event object

qualifiers:Annotation[]

the event qualifiers

Returns:Set<ObserverMethod<? super T>>

the resulting set of observer methods

Exceptions
IllegalArgumentException:
  • if the runtime type of the event object contains a type variable
  • if two instances of the same non repeating qualifier type are given
  • 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.