javax.enterprise.inject.spi

Interface BeanManager

public interface BeanManager

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.

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.

Any operation of BeanManager may be called at any time during the execution of the application.

Author:

Gavin King, Pete Muir, Clint Popetz, David Allen

Method Summary

Methods

Modifier and Type	Method and 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<?> beanClass, Producer<T> producer) Obtains a Bean for the given BeanAttributes, bean class and Producer.
<T> Bean<T>	createBean(BeanAttributes<T> attributes, Class<T> beanClass, InjectionTarget<T> injectionTarget) Obtains a Bean for the given BeanAttributes, bean class and InjectionTarget.
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.
<T> CreationalContext<T>	createCreationalContext(Contextual<T> contextual) Obtain an instance of a CreationalContext for the given contextual type, or for a non-contextual object.
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> InjectionTarget<T>	createInjectionTarget(AnnotatedType<T> type) Obtains an InjectionTarget for the given AnnotatedType.
<X> Producer<?>	createProducer(AnnotatedField<? super X> field, Bean<X> declaringBean) Obtains a Producer for the given AnnotatedField.
<X> Producer<?>	createProducer(AnnotatedMethod<? super X> method, Bean<X> declaringBean) Obtains a Producer for the given AnnotatedKetuod.
void	fireEvent(Object event, Annotation... qualifiers) Fire an event and notify observers.
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 was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules of EL name resolution.
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 was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules of typesafe resolution.
Context	getContext(Class<? extends Annotation> scopeType) Obtains an active context object for the given scope .
javax.el.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.
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.
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.
Object	getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx) Obtains a contextual reference for a certain bean and a certain bean type of the bean.
Set<Annotation>	getStereotypeDefinition(Class<? extends Annotation> stereotype) Obtains meta-annotations for a certain stereotype.
boolean	isInterceptorBinding(Class<? extends Annotation> annotationType) Test the given annotation type to determine if it is an interceptor binding type .
boolean	isNormalScope(Class<? extends Annotation> annotationType) Test the given annotation type to determine if it is a normal scope type.
boolean	isPassivatingScope(Class<? extends Annotation> annotationType) Test the given annotation type to determine if it is a passivating 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<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.
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 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 the set of observers for an event.
void	validate(InjectionPoint injectionPoint) Validate a certain injection point.
javax.el.ExpressionFactory	wrapExpressionFactory(javax.el.ExpressionFactory expressionFactory) Returns a wrapper ExpressionFactory that delegates MethodExpression and ValueExpression creation to the given ExpressionFactory.

Method Detail

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

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

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.

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 was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules of typesafe resolution. If no qualifiers are given, the default qualifier is assumed.

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 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

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 was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained, according to the rules of EL name resolution.

Parameters:

name - the EL name

Returns:

the resulting set of beans

Throws:

IllegalStateException - if called during application initialization

getPassivationCapableBean

Bean<?> getPassivationCapableBean(String id)

Returns the PassivationCapable bean with the given identifier.

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

resolve

<X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans)

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

Type Parameters:

X - a common type of the beans

Parameters:

beans - a set of beans of the given type

Throws:

AmbiguousResolutionException - if the ambiguous dependency resolution rules fail

IllegalStateException - if called during application initialization

validate

void validate(InjectionPoint injectionPoint)

Validate a certain injection point.

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 before the AfterDeploymentValidation event is fired

fireEvent

void fireEvent(Object event,
             Annotation... qualifiers)

Fire an event and notify observers.

Parameters:

event - the event object

qualifiers - the event qualifiers

Throws:

IllegalArgumentException - if the runtime type of the event object contains a type variable

IllegalArgumentException - if two instances of the same qualifier type are given

IllegalArgumentException - if an instance of an annotation that is not a qualifier type is given

IllegalArgumentException - if the runtime type of the event object is assignable to the type of a container lifecycle event

ObserverException - if a notified observer throws a checked exception, it will be wrapped and rethrown as an (unchecked) ObserverException

resolveObserverMethods

<T> Set<ObserverMethod<? super T>> resolveObserverMethods(T event,
                                                        Annotation... qualifiers)

Return the set of observers for an event.

Type Parameters:

T - the type of the event

Parameters:

event - the event object

qualifiers - the event qualifiers

Throws:

IllegalArgumentException - if the runtime type of the event object contains a type variable

IllegalArgumentException - if two instances of the same 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

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.

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

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 was injected or the Java EE component from whose JNDI environment namespace the BeanManager was obtained.

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

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

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

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

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

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

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:

a1 - a qualifier to check

a2 - a qualifier to check

Returns:

true if the two qualifiers are equivalent, otherwise false

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:

a1 - an interceptor binding to check

a2 - an interceptor binding to check

Returns:

true if the two interceptor bindings are equivalent, otherwise false

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

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

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

getELResolver

javax.el.ELResolver getELResolver()

Returns a ELResolver that resolves beans by EL name.

wrapExpressionFactory

javax.el.ExpressionFactory wrapExpressionFactory(javax.el.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

createInjectionTarget

<T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> type)

Obtains an InjectionTarget 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

Throws:

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

createProducer

<X> Producer<?> createProducer(AnnotatedField<? super X> field,
                             Bean<X> declaringBean)

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

Type Parameters:

X - the bean class of the bean declaring the producer field

Parameters:

field - the AnnotatedField

declaringBean - the bean declaring the producer field, used to obtain the contextual instance which receives the producer field access. May be null if the producer field is a static field.

Throws:

IllegalArgumentException - if there is a definition error associated with the producer field

createProducer

<X> Producer<?> createProducer(AnnotatedMethod<? super X> method,
                             Bean<X> declaringBean)

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

Type Parameters:

X - the bean class of the bean declaring the producer method

Parameters:

method - the AnnotatedMethod

declaringBean - the bean declaring the producer method used to obtain the contextual instance which receives the producer method invocation. May be null if the producer method is a static method.

Throws:

IllegalArgumentException - if there is a definition error associated with the producer method

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 probided implementation of InjectionTarget

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.

Type Parameters:

T - the type

Parameters:

type - the AnnotatedType

Returns:

a container probided implementation of InjectionTarget

createBean

<T> Bean<T> createBean(BeanAttributes<T> attributes,
                     Class<T> beanClass,
                     InjectionTarget<T> injectionTarget)

Obtains a Bean for the given BeanAttributes, bean class and 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 values of BeanAttributes.isAlternative() and Bean.isNullable()

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

injectionTarget - an InjectionTarget, which is used to create and destroy instances of the bean, to perform dependency injection and lifecycle callbacks, and which determines the return value of Bean.getInjectionPoints()

Returns:

a container provided implementation of Bean

createBean

<T> Bean<T> createBean(BeanAttributes<T> attributes,
                     Class<?> beanClass,
                     Producer<T> producer)

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

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 values of BeanAttributes.isAlternative() and Bean.isNullable()

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

producer - a Producer, which is used to create and destroy instances of the bean, and which determines the return value of Bean.getInjectionPoints()

Returns:

a container provided implementation of Bean

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

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

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