javax.enterprise.inject.spi.BeanManager Maven / Gradle / Ivy
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat, Inc., and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.enterprise.inject.spi;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Set;
import javax.el.ELResolver;
import javax.el.ExpressionFactory;
import javax.enterprise.context.ContextNotActiveException;
import javax.enterprise.context.spi.Context;
import javax.enterprise.context.spi.Contextual;
import javax.enterprise.context.spi.CreationalContext;
import javax.enterprise.inject.AmbiguousResolutionException;
import javax.enterprise.inject.InjectionException;
import javax.enterprise.inject.UnsatisfiedResolutionException;
/**
*
* 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 {@linkplain javax.naming JNDI} by looking up the name
* {@code java:comp/BeanManager}.
*
*
*
* Web components may obtain an instance of BeanManager by calling
* {@link javax.servlet.ServletContext#getAttribute(String)} with javax.enterprise.inject.spi.BeanManager as the
* attribute name.
*
*
*
* Any operation of BeanManager may be called at any time during the execution of the application.
*
*
* @author Gavin King
* @author Pete Muir
* @author Clint Popetz
* @author David Allen
*/
public interface BeanManager {
/**
* Obtains a contextual reference for a certain {@linkplain Bean bean} and a certain bean type of the bean.
*
* @param bean the {@link Bean} object representing the bean
* @param beanType a bean type that must be implemented by any client proxy that is returned
* @param ctx a {@link javax.enterprise.context.spi.CreationalContext} that may be used to destroy any object with scope
* {@link javax.enterprise.context.Dependent} that is created
* @return a contextual reference representing the bean
* @throws IllegalArgumentException if the given type is not a bean type of the given bean
*/
public Object getReference(Bean bean, Type beanType, CreationalContext ctx);
/**
* Obtains an injectable reference for a certain {@linkplain InjectionPoint injection point}.
*
* @param ij the target injection point
* @param ctx a {@link javax.enterprise.context.spi.CreationalContext} that may be used to destroy any object with scope
* {@link javax.enterprise.context.Dependent} that is created
* @return the injectable reference
* @throws UnsatisfiedResolutionException if typesafe resolution results in an unsatisfied dependency
* @throws AmbiguousResolutionException typesafe resolution results in an unresolvable ambiguous dependency
*/
public Object getInjectableReference(InjectionPoint ij, CreationalContext ctx);
/**
* Obtain an instance of a {@link javax.enterprise.context.spi.CreationalContext} for the given
* {@linkplain javax.enterprise.context.spi.Contextual contextual type}, or for a non-contextual object.
*
* @param contextual the {@link javax.enterprise.context.spi.Contextual}, or a null value in the case of a non-contextual
* object
* @return the new {@link javax.enterprise.context.spi.CreationalContext}
*/
public CreationalContext createCreationalContext(Contextual contextual);
/**
* 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 {@linkplain javax.enterprise.inject.Default default qualifier} is assumed.
*
* @param beanType the required bean type
* @param qualifiers the required qualifiers
* @return the resulting set of {@linkplain Bean beans}
* @throws IllegalArgumentException if the given type represents a type variable
* @throws IllegalArgumentException if two instances of the same qualifier type are given
* @throws IllegalArgumentException if an instance of an annotation that is not a qualifier type is given
*/
public Set> getBeans(Type beanType, Annotation... qualifiers);
/**
* 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.
*
* @param name the EL name
* @return the resulting set of {@linkplain Bean beans}
*/
public Set> getBeans(String name);
/**
* Returns the {@link javax.enterprise.inject.spi.PassivationCapable} bean with the given identifier.
*
* @param id the identifier
* @return a {@link Bean} that implements {@link javax.enterprise.inject.spi.PassivationCapable} and has the given
* identifier, or a null value if there is no such bean
*/
public Bean getPassivationCapableBean(String id);
/**
* Apply the ambiguous dependency resolution rules to a set of {@linkplain Bean beans}.
*
* @param a common type of the beans
* @param beans a set of {@linkplain Bean beans} of the given type
* @throws AmbiguousResolutionException if the ambiguous dependency resolution rules fail
*/
public Bean resolve(Set> beans);
/**
* Validate a certain {@linkplain InjectionPoint injection point}.
*
* @param injectionPoint the {@linkplain InjectionPoint 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
*/
public void validate(InjectionPoint injectionPoint);
/**
* Fire an event and notify observers.
*
* @param event the event object
* @param qualifiers the event qualifiers
* @throws IllegalArgumentException if the runtime type of the event object contains a type variable
* @throws IllegalArgumentException if two instances of the same qualifier type are given
* @throws IllegalArgumentException if an instance of an annotation that is not a qualifier type is given
*/
public void fireEvent(Object event, Annotation... qualifiers);
/**
* Return the set of observers for an event.
*
* @param the type of the event
* @param event the event object
* @param qualifiers the event qualifiers
* @throws IllegalArgumentException if the runtime type of the event object contains a type variable
* @throws IllegalArgumentException if two instances of the same qualifier type are given
* @throws IllegalArgumentException if an instance of an annotation that is not a qualifier type is given
*/
public Set> resolveObserverMethods(T event, Annotation... qualifiers);
/**
* Return an ordered list of {@linkplain Decorator 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.
*
* @param types the set of bean types of the decorated bean
* @param qualifiers the qualifiers declared by the decorated bean
* @return the resulting set of {@linkplain Decorator decorators}
* @throws IllegalArgumentException if the set of bean types is empty
* @throws IllegalArgumentException if an annotation which is not a binding type is passed
* @throws IllegalArgumentException if two instances of the same binding type are passed
*/
public List> resolveDecorators(Set types, Annotation... qualifiers);
/**
* Return an ordered list of enabled {@linkplain Interceptor 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.
*
* @param type the type of the interception
* @param interceptorBindings the interceptor bindings
* @return the resulting set of {@linkplain Interceptor interceptors}
* @throws IllegalArgumentException if no interceptor binding type is given
* @throws IllegalArgumentException if two instances of the same interceptor binding type are given
* @throws IllegalArgumentException if an instance of an annotation that is not an interceptor binding type is given
*/
public List> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings);
/**
* Test the given annotation type to determine if it is a {@linkplain javax.enterprise.context scope type}.
*
* @param annotationType the annotation type
* @return true if the annotation type is a {@linkplain javax.enterprise.context scope type}
*/
public boolean isScope(Class annotationType);
/**
* Test the given annotation type to determine if it is a {@linkplain javax.enterprise.context normal scope type}.
*
* @param annotationType the annotation type
* @return true if the annotation type is a {@linkplain javax.enterprise.context normal scope type}
*/
public boolean isNormalScope(Class annotationType);
/**
* Test the given annotation type to determine if it is a passivating {@linkplain javax.enterprise.context scope type}.
*
* @param annotationType the annotation type
* @return true if the annotation type is a passivating scope type
*/
public boolean isPassivatingScope(Class annotationType);
/**
* Test the given annotation type to determine if it is a {@linkplain javax.inject.Qualifier qualifier type}.
*
* @param annotationType the annotation type
* @return true if the annotation type is a {@linkplain javax.inject.Qualifier qualifier type}
*/
public boolean isQualifier(Class annotationType);
/**
* Test the given annotation type to determine if it is an {@linkplain javax.interceptor.InterceptorBinding interceptor
* binding type} .
*
* @param annotationType the annotation to test
* @return true if the annotation type is a {@linkplain javax.interceptor.InterceptorBinding interceptor binding
* type}
*/
public boolean isInterceptorBinding(Class annotationType);
/**
* Test the given annotation type to determine if it is a {@linkplain javax.enterprise.inject.Stereotype stereotype}.
*
* @param annotationType the annotation type
* @return true if the annotation type is a {@linkplain javax.enterprise.inject.Stereotype stereotype}
*/
public boolean isStereotype(Class annotationType);
/**
* Obtains the set of meta-annotations for a certain {@linkplain javax.interceptor.InterceptorBinding interceptor binding
* type} .
*
* @param bindingType the {@linkplain javax.interceptor.InterceptorBinding interceptor binding type}
* @return the set of meta-annotations
*/
public Set getInterceptorBindingDefinition(Class bindingType);
/**
* Obtains meta-annotations for a certain {@linkplain javax.enterprise.inject.Stereotype stereotype}.
*
* @param stereotype the {@linkplain javax.enterprise.inject.Stereotype stereotype}
* @return the set of meta-annotations
*/
public Set getStereotypeDefinition(Class stereotype);
/**
* Obtains an active {@linkplain javax.enterprise.context.spi.Context context object} for the given
* {@linkplain javax.enterprise.context scope} .
*
* @param scopeType the {@linkplain javax.enterprise.context scope}
* @return the {@linkplain javax.enterprise.context.spi.Context context object}
* @throws ContextNotActiveException if there is no active context object for the given scope
* @throws IllegalArgumentException if there is more than one active context object for the given scope
*/
public Context getContext(Class scopeType);
/**
* Returns a {@link javax.el.ELResolver} that resolves beans by EL name.
*/
public ELResolver getELResolver();
/**
* Returns a wrapper {@link javax.el.ExpressionFactory} that delegates {@link javax.el.MethodExpression} and
* {@link javax.el.ValueExpression} creation to the given {@link javax.el.ExpressionFactory}. When a Unified EL expression
* is evaluated using a {@link javax.el.MethodExpression} or {@link javax.el.ValueExpression} returned by the wrapper
* {@link javax.el.ExpressionFactory}, the container handles destruction of objects with scope
* {@link javax.enterprise.context.Dependent}.
*
*
* @param expressionFactory the {@link javax.el.ExpressionFactory} to wrap
* @return the wrapped {@link javax.el.ExpressionFactory}
*/
public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
/**
* Obtain an {@link AnnotatedType} that may be used to read the annotations of the given class or interface.
*
* @param the class or interface
* @param type the {@link java.lang.Class} object
* @return the {@link AnnotatedType}
*/
public AnnotatedType createAnnotatedType(Class type);
/**
* Obtains an {@link InjectionTarget} for the given {@link AnnotatedType}. The container ignores the annotations and types
* declared by the elements of the actual Java class and uses the metadata provided via the {@link Annotated} interface
* instead.
*
* @param the type
* @param type the {@link AnnotatedType}
* @returns a container provided implementation of {@link InjectionTarget}
* @throws IllegalArgumentException if there is a definition error associated with any injection point of the type
*/
public InjectionTarget createInjectionTarget(AnnotatedType type);
/**
* Obtains a {@link BeanAttributes} for the given {@link AnnotatedType}. The container ignores the annotations and types
* declared by the elements of the actual Java class and uses the metadata provided via the {@link Annotated} interface
* instead.
*
* @param the type
* @param type the {@link AnnotatedType}
* @return a container probided implementation of {@link InjectionTarget}
*/
public BeanAttributes createBeanAttributes(AnnotatedType type);
/**
* Obtains a {@link BeanAttributes} for the given {@link AnnotatedType}. The container ignores the annotations and types
* declared by the elements of the actual Java class and uses the metadata provided via the {@link Annotated} interface
* instead.
*
* @param the type
* @param type the {@link AnnotatedType}
* @return a container probided implementation of {@link InjectionTarget}
*/
public BeanAttributes createBeanAttributes(AnnotatedMember type);
/**
* Obtains a {@link Bean} for the given {@link BeanAttributes}, bean class and {@link InjectionTarget}.
*
* @param attributes a {@link BeanAttributes} which determines the bean types, qualifiers, scope, name and stereotypes of
* the returned {@link Bean}, and the return values of {@link Bean#isAlternative()} and {@link Bean#isNullable()}
* @param beanClass a class, which determines the return value of {@link Bean#getClass()}
* @param injectionTarget an {@link 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
* {@link Bean#getInjectionPoints()}
* @return a container provided implementation of {@link Bean}
*/
public Bean createBean(BeanAttributes attributes, Class beanClass, InjectionTarget injectionTarget);
/**
* Obtains a {@link Bean} for the given {@link BeanAttributes}, bean class and {@link Producer}.
*
* @param attributes a {@link BeanAttributes} which determines the bean types, qualifiers, scope, name and stereotypes of
* the returned {@link Bean}, and the return values of {@link Bean#isAlternative()} and {@link Bean#isNullable()}
* @param beanClass a class, which determines the return value of {@link Bean#getClass()}
* @param producer a Producer, which is used to create and destroy instances of the bean, and which determines the return
* value of {@link Bean#getInjectionPoints()}
* @return a container provided implementation of {@link Bean}
*/
public Bean createBean(BeanAttributes attributes, Class beanClass, Producer producer);
/**
* Obtains a container provided implementation of {@link InjectionPoint} for the given {@link AnnotatedField}.
*
* @param field the {@link AnnotatedField} defining the injection point
* @return the container provided {@link InjectionPoint}
* @throws IllegalArgumentException if there is a definition error associated with the injection point
*/
public InjectionPoint createInjectionPoint(AnnotatedField field);
/**
* Obtains a container provided implementation of {@link InjectionPoint} for the given {@link AnnotatedParameter}.
*
* @param parameter the {@link AnnotatedParameter} defining the injection point
* @return the container provided {@link InjectionPoint}
* @throws IllegalArgumentException if there is a definition error associated with the injection point
*/
public InjectionPoint createInjectionPoint(AnnotatedParameter parameter);
/**
* Obtains the container's instance of an Extension class declared in META-INF/services.
*
* @param the type of the extension
* @param extensionClass the type of the extension class
* @return the extension instance
* @throws IllegalArgumentException if the container has no instance of the given class
*/
public T getExtension(Class extensionClass);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy