javax.enterprise.inject.spi.BeanManager Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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.lang.reflect.TypeVariable;
import java.util.List;
import java.util.Set;
import javax.el.ELResolver;
import javax.el.ExpressionFactory;
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;
/**
* The interface BeanManager is the central point for dealing with CDI.
* The BeanManager provides operations for resolving CDI {@link Bean}s,
* obtaining the Contextual References of them, etc. There are operations
* related with;
*
*
* - Firing observer events
* - Creating {@link CreationalContext}s
* - Resolution of beans, interceptors, decorators and observers
* - Other utility methods etc..
*
*
*/
public interface BeanManager
{
/**
* Returns a bean instance reference for the given bean.
*
* @param bean bean that its reference is getting
* @param beanType bean api type that is implemented by the proxy
* @param ctx creational context is used to destroy any object with scope @Dependent
* @return bean reference
* @throws IllegalArgumentException if given bean type is not api type of the given bean object
* @throws java.lang.IllegalStateException if this method gets called before the AfterDeploymentValidation event is fired.
*/
public Object getReference(Bean bean, Type beanType, CreationalContext ctx);
/**
* Gets injection point bean reference.
*
* @param injectionPoint injection point definition
* @param ctx creational context that is passed to the {@link Bean#create(CreationalContext)} method
* @return bean reference
* @throws UnsatisfiedResolutionException if no bean found for the given injection point
* @throws AmbiguousResolutionException if more than one bean found
* @throws java.lang.IllegalStateException if this method gets called before the AfterDeploymentValidation event is fired.
*/
public Object getInjectableReference(InjectionPoint injectionPoint, CreationalContext ctx);
/**
* Returns a new creational context implementation.
*
* @return new creational context
*/
public CreationalContext createCreationalContext(Contextual contextual);
/**
* Returns set of beans that their api types contain
* given bean type and given qualifiers.
*
*
* If no qualifier is given, @Current is assumed.
*
*
* @param beanType required bean type
* @param qualifiers required qualifiers
* @return set of beans
* @throws IllegalArgumentException given bean type is a {@link TypeVariable}
* @throws IllegalArgumentException given qualifier annotation is not a qualifier
* @throws IllegalArgumentException same qualifier is given
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public Set> getBeans(Type beanType, Annotation... qualifiers);
/**
* Returns set of beans with given Expression Language name.
*
* @param name name of the bean
* @return set of beans with given name
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public Set> getBeans(String name);
/**
* Returns passivation capable bean given id.
*
* @param id bean id
* @return passivation capable bean given id
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public Bean getPassivationCapableBean(String id);
/**
* Returns a bean object that is resolved according to the type safe resolution rules.
*
* @param bean class info
* @param beans set of beans
* @return bean that is resolved according to the type safe resolution rules
* @throws AmbiguousResolutionException if ambigious exists
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public Bean resolve(Set> beans);
/**
* Fires an event with given even object and qualifiers.
*
* @param event observer event object
* @param qualifiers event qualifiers
* @throws IllegalArgumentException event object contains a {@link TypeVariable}
* @throws IllegalArgumentException given qualifier annotation is not a qualifier
* @throws IllegalArgumentException same qualifier is given
*/
public void fireEvent(Object event, Annotation... qualifiers);
/**
* Returns set of observer methods.
*
* @param event type
* @param event even object
* @param qualifiers event qualifiers
* @return set of observer methods
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public Set> resolveObserverMethods(T event, Annotation... qualifiers);
/**
* Returns a list of decorator.
*
* @param types bean types of the decorated bean
* @param qualifiers decorated bean qualifiers
* @return list of decorator
* @throws IllegalArgumentException given qualifier annotation is not a qualifier
* @throws IllegalArgumentException same qualifier is given
* @throws IllegalArgumentException if types is empty set
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
List> resolveDecorators(Set types, Annotation... qualifiers);
/**
* Returns a list of interceptor.
*
* @param type interception type
* @param interceptorBindings interceptor bindings
* @return list of interceptor
* @throws IllegalArgumentException given binding annotation is not a binding
* @throws IllegalArgumentException same binding is given
* @throws IllegalArgumentException binding is not an interceptor binding
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
List> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings);
/**
* Validates injection point.
*
* @param injectionPoint injection point
* @throws InjectionException if problem exist
* @throws java.lang.IllegalStateException if this method gets called before the AfterBeanDiscovery event is fired.
*/
public void validate(InjectionPoint injectionPoint);
/**
* Returns true if given type is a scope type, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a scope type, false otherwise
*/
public boolean isScope(Class annotationType);
/**
* Returns true if given type is a normal scope type, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a scope type, false otherwise
*/
public boolean isNormalScope(Class annotationType);
/**
* Returns true if given type is a passivating scope type, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a scope type, false otherwise
*/
public boolean isPassivatingScope(Class annotationType);
/**
* Returns true if given type is a qualifier, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a qualifier, false otherwise
*/
public boolean isQualifier(Class annotationType);
/**
* Check whether the 2 given qualifiers are the same.
* This takes {@link javax.enterprise.util.Nonbinding} into account by ignoring
* those properties.
* @param qualifier1
* @param qualifier2
* @return true if all non-nonbinding attributes are equals, false otherwise
*/
public boolean areQualifiersEquivalent(Annotation qualifier1, Annotation qualifier2);
/**
* @param qualifier
* @return the hashCode of the Annotation. All {@link javax.enterprise.util.Nonbinding} fields get ignored
*/
public int getQualifierHashCode(Annotation qualifier);
/**
* Returns true if given type is a interceptor binding, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a interceptor binding, false otherwise
*/
public boolean isInterceptorBinding(Class annotationType);
/**
* Check whether the 2 given Interceptor Binding annotations are the same.
* This takes {@link javax.enterprise.util.Nonbinding} into account by ignoring
* those properties.
* @param interceptorBinding1
* @param interceptorBinding2
* @return true if all non-nonbinding attributes are equals, false otherwise
*/
public boolean areInterceptorBindingsEquivalent(Annotation interceptorBinding1, Annotation interceptorBinding2);
/**
* @param interceptorBinding
* @return the hashCode of the Annotation. All {@link javax.enterprise.util.Nonbinding} fields get ignored
*/
public int getInterceptorBindingHashCode(Annotation interceptorBinding);
/**
* Returns true if given type is a stereotype type, false otherwise.
*
* @param annotationType annotation type
* @return true if given type is a stereotype, false otherwise
*/
public boolean isStereotype(Class annotationType);
/**
* Returns a set of meta-annotations that are defined on the binding
*
* @param qualifier binding class
* @return a set of meta-annotations that are defined on the binding
*/
public Set getInterceptorBindingDefinition(Class qualifier);
/**
* Returns a set of meta-annotations that are defined on the stereotype type.
*
* @param stereotype stereotype type class
* @return a set of meta-annotations that are defined on the stereotype type
*/
public Set getStereotypeDefinition(Class stereotype);
/**
* Returns a context with given scope type.
*
* @param scope scope type class type
* @return a context with given scope type
*/
public Context getContext(Class scope);
/**
* Returns CDI container Expression Language resolver.
*
* @return el resolver
*/
public ELResolver getELResolver();
/**
* Returns a {@link AnnotatedType} instance for the given
* class.
*
* @param class type
* @param type class
* @return a {@link AnnotatedType} instance
*/
public AnnotatedType createAnnotatedType(Class type);
/**
* Creates a new instance of injection target Bean.
*
* @param bean type
* @param type annotated type
* @return injection target
*/
public InjectionTarget createInjectionTarget(AnnotatedType type);
/**
* Create an {@link InjectionPoint} for an annotated field.
* @param field
* @throws IllegalArgumentException if there is a definition error on the given field
* @return injection point
*/
public InjectionPoint createInjectionPoint(AnnotatedField field);
/**
* Create an {@link InjectionPoint} for an annotated parameter.
* @param parameter
* @throws IllegalArgumentException if there is a definition error on the given parameter
* @return injection point
*/
public InjectionPoint createInjectionPoint(AnnotatedParameter parameter);
/**
* @param type
* @param
* @return the InjectionTargetFactory which is able to create {@link InjectionTarget}s for the given AnnotatedType.
*/
public InjectionTargetFactory getInjectionTargetFactory(AnnotatedType type);
/**
* @param field
* @param declaringBean
* @param
* @return the ProducerFactory which is able to create {@link Producer}s for the given AnnotatedField.
*/
public ProducerFactory getProducerFactory(AnnotatedField field, Bean declaringBean);
/**
* @param method
* @param declaringBean
* @param
* @return the ProducerFactory which is able to create {@link Producer}s for the given AnnotatedMethod.
*/
public ProducerFactory getProducerFactory(AnnotatedMethod method, Bean declaringBean);
/**
* This method creates bean meta information from a given {@link AnnotatedType}.
* The created BeanAttributes can later be used to create a {@link Bean}
* via {@link #createBean(BeanAttributes, Class, InjectionTargetFactory)} or
* {@link #createBean(BeanAttributes, Class, ProducerFactory)}
*
* @param type
* @param
* @return the BeanAttributes created from parsing the given AnnotatedType
*/
public BeanAttributes createBeanAttributes(AnnotatedType type);
/**
* This method creates bean meta information from a given {@link AnnotatedMember}.
* The created BeanAttributes can later be used to create a {@link Bean}
* via {@link #createBean(BeanAttributes, Class, InjectionTargetFactory)} or
* {@link #createBean(BeanAttributes, Class, ProducerFactory)}.
*
* @param member
* @return the BeanAttributes created from parsing the given AnnotatedType
*/
public BeanAttributes createBeanAttributes(AnnotatedMember member);
/**
* Create a {@link Bean} from the given bean attributes.
* This version of the method uses a given {@link InjectionTargetFactory}.
* @param attributes
* @param beanClass
* @param injectionTargetFactory
* @param
* @return the container created Bean
*/
public Bean createBean(BeanAttributes attributes, Class beanClass,
InjectionTargetFactory injectionTargetFactory);
/**
* Create a {@link Bean} from the given bean attributes.
* This version of the method uses a given {@link ProducerFactory}.
* @param attributes
* @param beanClass
* @param producerFactory
* @param
* @return the container created Bean
*/
public Bean createBean(BeanAttributes attributes, Class beanClass,
ProducerFactory producerFactory);
/**
* Resolves the Extension instance which gets used by this very BeanManager.
* The given extensionClass must be the effective class registered
* into META-INF/services and not some base class.
*
* @param extensionClass
* @param
* @return the Extension instance of this very BeanManager
*/
public T getExtension(Class extensionClass);
/**
* Wrapped around given expression factory and add CDI functionality.
* @param expressionFactory expression factory
* @return wrapped expression factory
*/
public ExpressionFactory wrapExpressionFactory(javax.el.ExpressionFactory expressionFactory);
}