geronimo-jcdi_2.0_spec/src/main/java/javax/enterprise/inject/spi/BeanManager.java

/*
 * 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;


/**
 * <p>The interface <code>BeanManager</code> 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;</p>
 * 
 * <ul>
 *  <li>Firing observer events</li>
 *  <li>Creating {@link CreationalContext}s</li>
 *  <li>Resolution of beans, interceptors, decorators and observers</li>
 *  <li>Other utility methods etc..</li>
 * </ul>
 *
 */
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 <code>@Dependent</code>
     * @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 <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual);
    
    /**
     * Returns set of beans that their api types contain
     * given bean type and given qualifiers.
     * 
     * <p>
     * If no qualifier is given, <code>@Current</code> is assumed.
     * </p>
     * 
     * @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<Bean<?>> 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<Bean<?>> 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 <X> 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 <X> Bean<? extends X> resolve(Set<Bean<? extends X>> 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 <T> 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 <T> Set<ObserverMethod<? super T>> 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<Decorator<?>> resolveDecorators(Set<Type> 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<Interceptor<?>> 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<? extends Annotation> 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<? extends Annotation> 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<? extends Annotation> 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<? extends Annotation> 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 <code>true</code> if all non-nonbinding attributes are equals, <code>false</code> 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<? extends Annotation> 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 <code>true</code> if all non-nonbinding attributes are equals, <code>false</code> 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<? extends Annotation> 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<Annotation> getInterceptorBindingDefinition(Class<? extends Annotation> 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<Annotation> getStereotypeDefinition(Class<? extends Annotation> 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<? extends Annotation> scope);
    
    /**
     * Returns CDI container Expression Language resolver.
     * 
     * @return el resolver
     */
    public ELResolver getELResolver();
    
    /**
     * Returns a {@link AnnotatedType} instance for the given
     * class.
     * 
     * @param <T> class type
     * @param type class
     * @return a {@link AnnotatedType} instance
     */
    public <T> AnnotatedType<T> createAnnotatedType(Class<T> type);
    
    /**
     * Creates a new instance of injection target Bean.
     * 
     * @param <T> bean type
     * @param type annotated type
     * @return injection target
     */
    public <T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> 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 <T>
     * @return the InjectionTargetFactory which is able to create {@link InjectionTarget}s for the given AnnotatedType.
     */
    public <T> InjectionTargetFactory<T> getInjectionTargetFactory(AnnotatedType<T> type);

    /**
     * @param field
     * @param declaringBean
     * @param <X>
     * @return the ProducerFactory which is able to create {@link Producer}s for the given AnnotatedField.
     */
    public <X> ProducerFactory<X> getProducerFactory(AnnotatedField<? super X> field, Bean<X> declaringBean);

    /**
     * @param method
     * @param declaringBean
     * @param <X>
     * @return the ProducerFactory which is able to create {@link Producer}s for the given AnnotatedMethod.
     */
    public <X> ProducerFactory<X> getProducerFactory(AnnotatedMethod<? super X> method, Bean<X> 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 <T>
     * @return the BeanAttributes created from parsing the given AnnotatedType
     */
    public <T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> 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 <T>
     * @return the container created Bean
     */
    public <T> Bean<T> createBean(BeanAttributes<T> attributes, Class<T> beanClass,
                                  InjectionTargetFactory<T> 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 <T>
     * @return the container created Bean
     */
    public <T, X> Bean<T> createBean(BeanAttributes<T> attributes, Class<X> beanClass,
                                     ProducerFactory<X> producerFactory);

    /**
     * Resolves the Extension instance which gets used by this very BeanManager.
     * The given <code>extensionClass</code> must be the effective class registered
     * into META-INF/services and not some base class.
     *
     * @param extensionClass
     * @param <T>
     * @return the Extension instance of this very BeanManager
     */
    public <T extends Extension> T getExtension(Class<T> 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);
}