Package jakarta.enterprise.inject.spi

Interface BeanManager

All Superinterfaces:

BeanContainer

public interface BeanManager
extends BeanContainer

Allows a portable extension to interact directly with the container. Provides operations for obtaining contextual references for beans, along with many other operations of use to portable extensions.

In CDI Lite environment, applications may obtain a BeanManager, but invoking methods that are not inherited from BeanContainer results in non-portable behavior.

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

 @Inject
 BeanManager manager;
 

Java EE components may obtain an instance of BeanManager from JNDI by looking up the name java:comp/BeanManager.

Most operations of BeanManager may be called at any time during the execution of the application.

However, the following operations must not be called before the AfterBeanDiscovery event is fired:

• BeanContainer.getBeans(String),
• BeanContainer.getBeans(java.lang.reflect.Type, java.lang.annotation.Annotation...),
• getPassivationCapableBean(String),
• BeanContainer.resolve(java.util.Set),
• resolveDecorators(java.util.Set, java.lang.annotation.Annotation...),
• BeanContainer.resolveInterceptors(InterceptionType, java.lang.annotation.Annotation...),
• resolveObserverMethods(Object, java.lang.annotation.Annotation...),
• validate(InjectionPoint),
• BeanContainer.createInstance()

and the following operations must not be called before the AfterDeploymentValidation event is fired:

• BeanContainer.getReference(Bean, java.lang.reflect.Type, CreationalContext),
• getInjectableReference(InjectionPoint, CreationalContext),

or the container will throw an Exception.

Author:

Gavin King, Pete Muir, Clint Popetz, David Allen, Antoine Sabot-Durand

Method Summary

Modifier and Type	Method	Description
boolean	areInterceptorBindingsEquivalent(Annotation interceptorBinding1, Annotation interceptorBinding2)	Determine if two interceptor bindings are considered equivalent for the purposes of typesafe resolution, taking into account any members annotated with Nonbinding.
boolean	areQualifiersEquivalent(Annotation qualifier1, Annotation qualifier2)	Determine if two qualifiers are considered equivalent for the purposes of typesafe resolution, taking into account any members annotated with Nonbinding.
<T> AnnotatedType<T>	createAnnotatedType(Class<T> type)	Obtain an AnnotatedType that may be used to read the annotations of the given class or interface.
<T> Bean<T>	createBean(BeanAttributes<T> attributes, Class<T> beanClass, InjectionTargetFactory<T> injectionTargetFactory)	Obtains a Bean for the given BeanAttributes, bean class and InjectionTarget.
<T,X> Bean<T>	createBean(BeanAttributes<T> attributes, Class<X> beanClass, ProducerFactory<X> producerFactory)	Obtains a Bean for the given BeanAttributes, bean class and Producer.
BeanAttributes<?>	createBeanAttributes(AnnotatedMember<?> type)	Obtains a BeanAttributes for the given AnnotatedType.
<T> BeanAttributes<T>	createBeanAttributes(AnnotatedType<T> type)	Obtains a BeanAttributes for the given AnnotatedType.
InjectionPoint	createInjectionPoint(AnnotatedField<?> field)	Obtains a container provided implementation of InjectionPoint for the given AnnotatedField.
InjectionPoint	createInjectionPoint(AnnotatedParameter<?> parameter)	Obtains a container provided implementation of InjectionPoint for the given AnnotatedParameter.
<T> InterceptionFactory<T>	createInterceptionFactory(CreationalContext<T> ctx, Class<T> clazz)	Create an InterceptionFactory for the given CreationalContext and type.
ELResolver	getELResolver()	Returns a ELResolver that resolves beans by EL name.
<T extends Extension> T	getExtension(Class<T> extensionClass)	Obtains the container's instance of an Extension class declared in META-INF/services.
Object	getInjectableReference(InjectionPoint ij, CreationalContext<?> ctx)	Obtains an injectable reference for a certain injection point.
<T> InjectionTargetFactory<T>	getInjectionTargetFactory(AnnotatedType<T> annotatedType)	An implementation of InjectionTargetFactory that provides container created InjectionTarget instances.
Set<Annotation>	getInterceptorBindingDefinition(Class<? extends Annotation> bindingType)	Obtains the set of meta-annotations for a certain interceptor binding type .
int	getInterceptorBindingHashCode(Annotation interceptorBinding)	Determine the hash code of an interceptor binding, using the JDK algorithm for determining an annotation hash code, ignoring any members annotated with Nonbinding.
Bean<?>	getPassivationCapableBean(String id)	Returns the PassivationCapable bean with the given identifier.
<X> ProducerFactory<X>	getProducerFactory(AnnotatedField<? super X> field, Bean<X> declaringBean)	An implementation of ProducerFactory that provides container created Producer instances for the given field.
<X> ProducerFactory<X>	getProducerFactory(AnnotatedMethod<? super X> method, Bean<X> declaringBean)	An implementation of ProducerFactory that provides container created Producer instances for the given method.
int	getQualifierHashCode(Annotation qualifier)	Determine the hash code of a qualifier, using the JDK algorithm for determining an annotation hash code, ignoring any members annotated with Nonbinding.
Set<Annotation>	getStereotypeDefinition(Class<? extends Annotation> stereotype)	Obtains meta-annotations for a certain stereotype.
boolean	isPassivatingScope(Class<? extends Annotation> annotationType)	Test the given annotation type to determine if it is a passivating scope type.
List<Decorator<?>>	resolveDecorators(Set<Type> types, Annotation... qualifiers)	Return an ordered list of decorators for a set of bean types and a set of qualifiers and which are enabled in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained.
<T> Set<ObserverMethod<? super T>>	resolveObserverMethods(T event, Annotation... qualifiers)	Return an ordered set of observer methods for an event.
void	validate(InjectionPoint injectionPoint)	Validate a certain injection point.
ExpressionFactory	wrapExpressionFactory(ExpressionFactory expressionFactory)	Returns a wrapper ExpressionFactory that delegates MethodExpression and ValueExpression creation to the given ExpressionFactory.

Methods inherited from interface jakarta.enterprise.inject.spi.BeanContainer

createCreationalContext, createInstance, getBeans, getBeans, getContext, getEvent, getReference, isInterceptorBinding, isNormalScope, isQualifier, isScope, isStereotype, resolve, resolveInterceptors

Method Detail

getPassivationCapableBean

Bean<?> getPassivationCapableBean(String id)

Returns the PassivationCapable bean with the given identifier. 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:

id - the identifier

Returns:

a Bean that implements PassivationCapable and has the given identifier, or a null value if there is no such bean

Throws:

IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

validate

void validate(InjectionPoint injectionPoint)

Validate a certain injection point. Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only validate injection points discovered by the container before the AfterBeanDiscovery event is fired.

Parameters:

injectionPoint - the injection point to validate

Throws:

InjectionException - if there is a deployment problem (for example, an unsatisfied or unresolvable ambiguous dependency) associated with the injection point

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.

Specified by:

resolveObserverMethods in interface BeanContainer

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.

resolveDecorators

List<Decorator<?>> resolveDecorators(Set<Type> types,
                                     Annotation... qualifiers)

Return an ordered list of decorators for a set of bean types and a set of qualifiers and which are enabled in the module or library containing the class into which the BeanManager was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained. Note that when called during invocation of an AfterBeanDiscovery event observer, this method will only return decorators discovered by the container before the AfterBeanDiscovery event is fired.

Parameters:

types - the set of bean types of the decorated bean

qualifiers - the qualifiers declared by the decorated bean

Returns:

the resulting set of decorators

Throws:

IllegalArgumentException - if the set of bean types is empty

IllegalArgumentException - if an annotation which is not a binding type is passed

IllegalArgumentException - if two instances of the same binding type are passed

IllegalStateException - if called during application initialization, before the AfterBeanDiscovery event is fired.

isPassivatingScope

boolean isPassivatingScope(Class<? extends Annotation> annotationType)

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

Parameters:

annotationType - the annotation type

Returns:

true if the annotation type is a passivating scope type

getInterceptorBindingDefinition

Set<Annotation> getInterceptorBindingDefinition(Class<? extends Annotation> bindingType)

Obtains the set of meta-annotations for a certain interceptor binding type .

Parameters:

bindingType - the interceptor binding type

Returns:

the set of meta-annotations

getStereotypeDefinition

Set<Annotation> getStereotypeDefinition(Class<? extends Annotation> stereotype)

Obtains meta-annotations for a certain stereotype.

Parameters:

stereotype - the stereotype

Returns:

the set of meta-annotations

areQualifiersEquivalent

boolean areQualifiersEquivalent(Annotation qualifier1,
                                Annotation qualifier2)

Determine if two qualifiers are considered equivalent for the purposes of typesafe resolution, taking into account any members annotated with Nonbinding.

Parameters:

qualifier1 - a qualifier to check

qualifier2 - a qualifier to check

Returns:

true if the two qualifiers are equivalent, otherwise false

Since:

1.1

areInterceptorBindingsEquivalent

boolean areInterceptorBindingsEquivalent(Annotation interceptorBinding1,
                                         Annotation interceptorBinding2)

Determine if two interceptor bindings are considered equivalent for the purposes of typesafe resolution, taking into account any members annotated with Nonbinding.

Parameters:

interceptorBinding1 - an interceptor binding to check

interceptorBinding2 - an interceptor binding to check

Returns:

true if the two interceptor bindings are equivalent, otherwise false

Since:

1.1

getQualifierHashCode

int getQualifierHashCode(Annotation qualifier)

Determine the hash code of a qualifier, using the JDK algorithm for determining an annotation hash code, ignoring any members annotated with Nonbinding.

Parameters:

qualifier - the qualifier to consider

Returns:

the hashCode for the qualifier

Since:

1.1

getInterceptorBindingHashCode

int getInterceptorBindingHashCode(Annotation interceptorBinding)

Determine the hash code of an interceptor binding, using the JDK algorithm for determining an annotation hash code, ignoring any members annotated with Nonbinding.

Parameters:

interceptorBinding - the interceptor binding to consider

Returns:

the hashCode for the interceptor binding

Since:

1.1

getELResolver

ELResolver getELResolver()

Returns a ELResolver that resolves beans by EL name.

Returns:

the ELResolver

wrapExpressionFactory

ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory)

Returns a wrapper ExpressionFactory that delegates MethodExpression and ValueExpression creation to the given ExpressionFactory. When a Unified EL expression is evaluated using a MethodExpression or ValueExpression returned by the wrapper ExpressionFactory, the container handles destruction of objects with scope Dependent.

Parameters:

expressionFactory - the ExpressionFactory to wrap

Returns:

the wrapped ExpressionFactory

createAnnotatedType

<T> AnnotatedType<T> createAnnotatedType(Class<T> type)

Obtain an AnnotatedType that may be used to read the annotations of the given class or interface.

Type Parameters:

T - the class or interface

Parameters:

type - the Class object

Returns:

the AnnotatedType

getInjectionTargetFactory

<T> InjectionTargetFactory<T> getInjectionTargetFactory(AnnotatedType<T> annotatedType)

An implementation of InjectionTargetFactory that provides container created InjectionTarget instances.

This factory can be wrapped to add behavior to container created injection targets.

Type Parameters:

T - the type

Parameters:

annotatedType - the annotated type to create the injection target factory for

Returns:

an InjectionTargetFactory

Since:

1.1

getProducerFactory

<X> ProducerFactory<X> getProducerFactory(AnnotatedField<? super X> field,
                                          Bean<X> declaringBean)

An implementation of ProducerFactory that provides container created Producer instances for the given field.

This factory can be wrapped to add behavior to container created producers.

Type Parameters:

X - the declaring type

Parameters:

field - the field to create the producer factory for

declaringBean - the bean declaring the producer. May be null if the producer is static or the declaring object is non-contextual

Returns:

the producer factory for the field

Since:

1.1

getProducerFactory

<X> ProducerFactory<X> getProducerFactory(AnnotatedMethod<? super X> method,
                                          Bean<X> declaringBean)

An implementation of ProducerFactory that provides container created Producer instances for the given method.

This factory can be wrapped to add behavior to container created producers.

Type Parameters:

X - bean type

Parameters:

method - the method to create the producer factory for

declaringBean - the bean declaring the producer. May be null if the producer is static or the declaring object is non-contextual

Returns:

the producer factory for the method

Since:

1.1

createBeanAttributes

<T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> type)

Obtains a BeanAttributes for the given AnnotatedType. The container ignores the annotations and types declared by the elements of the actual Java class and uses the metadata provided via the Annotated interface instead.

Type Parameters:

T - the type

Parameters:

type - the AnnotatedType

Returns:

a container provided implementation of InjectionTarget

Since:

1.1

createBeanAttributes

BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> type)

Obtains a BeanAttributes for the given AnnotatedType. The container ignores the annotations and types declared by the elements of the actual Java class and uses the metadata provided via the Annotated interface instead.

Parameters:

type - the AnnotatedType

Returns:

a container provided implementation of InjectionTarget

Since:

1.1

createBean

<T> Bean<T> createBean(BeanAttributes<T> attributes,
                       Class<T> beanClass,
                       InjectionTargetFactory<T> injectionTargetFactory)

Obtains a Bean for the given BeanAttributes, bean class and InjectionTarget.

The InjectionTarget creates and destroys instances of the bean, performs dependency injection and lifecycle callbacks, and determines the return value of Bean.getInjectionPoints(). The InjectionTarget is obtained from the InjectionTargetFactory. getInjectionTargetFactory(AnnotatedType) allows use of a container created InjectionTarget.

Type Parameters:

T - the type

Parameters:

attributes - a BeanAttributes which determines the bean types, qualifiers, scope, name and stereotypes of the returned Bean, and the return value of BeanAttributes.isAlternative()

beanClass - a class, which determines the return value of Bean.getBeanClass()

injectionTargetFactory - an InjectionTargetFactory, used to obtain an InjectionTarget

Returns:

a container provided implementation of Bean

Since:

1.1

createBean

<T,X> Bean<T> createBean(BeanAttributes<T> attributes,
                               Class<X> beanClass,
                               ProducerFactory<X> producerFactory)

Obtains a Bean for the given BeanAttributes, bean class and Producer.

The Producer creates and destroys instances of the decorator, and determines the return value of Bean.getInjectionPoints(). The Producer is obtained from the ProducerFactory. getProducerFactory(AnnotatedMethod, Bean) or getProducerFactory(AnnotatedField, Bean) allows use of a container created Producer.

Type Parameters:

T - the type

X - the type of the declaring bean

Parameters:

attributes - a BeanAttributes which determines the bean types, qualifiers, scope, name and stereotypes of the returned Bean, and the return value of BeanAttributes.isAlternative()

beanClass - a class, which determines the return value of Bean.getClass()

producerFactory - a ProducerFactory, used to obtain a Producer

Returns:

a container provided implementation of Bean

Since:

1.1

createInjectionPoint

InjectionPoint createInjectionPoint(AnnotatedField<?> field)

Obtains a container provided implementation of InjectionPoint for the given AnnotatedField.

Parameters:

field - the AnnotatedField defining the injection point

Returns:

the container provided InjectionPoint

Throws:

IllegalArgumentException - if there is a definition error associated with the injection point

Since:

1.1

createInjectionPoint

InjectionPoint createInjectionPoint(AnnotatedParameter<?> parameter)

Obtains a container provided implementation of InjectionPoint for the given AnnotatedParameter.

Parameters:

parameter - the AnnotatedParameter defining the injection point

Returns:

the container provided InjectionPoint

Throws:

IllegalArgumentException - if there is a definition error associated with the injection point

Since:

1.1

getExtension

<T extends Extension> T getExtension(Class<T> extensionClass)

Obtains the container's instance of an Extension class declared in META-INF/services.

Type Parameters:

T - the type of the extension

Parameters:

extensionClass - the type of the extension class

Returns:

the extension instance

Throws:

IllegalArgumentException - if the container has no instance of the given class

Since:

1.1

createInterceptionFactory

<T> InterceptionFactory<T> createInterceptionFactory(CreationalContext<T> ctx,
                                                     Class<T> clazz)

Create an InterceptionFactory for the given CreationalContext and type.

Type Parameters:

T - type of the instance this factory will work on

Parameters:

ctx - CreationalContext for the InterceptionFactory to create

clazz - class of the instance this factory will work on

Returns:

a new InterceptionFactory to add services on on instances of T

Since:

2.0

getInjectableReference

Object getInjectableReference(InjectionPoint ij,
                              CreationalContext<?> ctx)

Obtains an injectable reference for a certain injection point.

Parameters:

ij - the target injection point

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

Returns:

the injectable reference

Throws:

UnsatisfiedResolutionException - if typesafe resolution results in an unsatisfied dependency

AmbiguousResolutionException - typesafe resolution results in an unresolvable ambiguous dependency

IllegalStateException - if called during application initialization, before the AfterDeploymentValidation event is fired.