BeanConfigurator.java

/*
 * JBoss, Home of Professional Open Source
 * Copyright 2015, 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.configurator;

import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.Set;
import java.util.function.BiConsumer;
import java.util.function.Function;

import javax.enterprise.context.spi.Contextual;
import javax.enterprise.context.spi.CreationalContext;
import javax.enterprise.inject.Instance;
import javax.enterprise.inject.spi.AfterBeanDiscovery;
import javax.enterprise.inject.spi.AnnotatedType;
import javax.enterprise.inject.spi.Bean;
import javax.enterprise.inject.spi.BeanAttributes;
import javax.enterprise.inject.spi.InjectionPoint;
import javax.enterprise.inject.spi.PassivationCapable;
import javax.enterprise.util.TypeLiteral;

/**
 * This API is an helper to configure a new {@link Bean} instance.
 * CDI container must provides an implementation of this interface.
 *
 * This builder is not thread safe and shall not be used concurrently.
 *
 * @see AfterBeanDiscovery#addBean()
 * @author Martin Kouba
 * @author Antoine Sabot-Durand
 * @param <T> the class of the bean instance
 * @since 2.0
 */
public interface BeanConfigurator<T> {

    /**
     * Set the class of the configured Bean.
     * If not set, the extension class is used.
     *
     * @param beanClass class of the configured bean
     * @return self
     */
    BeanConfigurator<T> beanClass(Class<?> beanClass);

    /**
     * Add an InjectionPoint to the configured bean
     *
     * @param injectionPoint the injectionPoint to add
     * @return self
     */
    BeanConfigurator<T> addInjectionPoint(InjectionPoint injectionPoint);

    /**
     * Add InjectionPoints to the configured bean
     *
     * @param injectionPoints the injectionPoints to add
     * @return self
     */
    BeanConfigurator<T> addInjectionPoints(InjectionPoint... injectionPoints);

    /**
     * Add InjectionPoints to the configured bean
     *
     * @param injectionPoints the injectionPoints to add
     * @return self
     */
    BeanConfigurator<T> addInjectionPoints(Set<InjectionPoint> injectionPoints);

    /**
     * Replace InjectionPoints for the configured bean
     *
     * @param injectionPoints the injectionPoints for the configured bean
     * @return self
     */
    BeanConfigurator<T> injectionPoints(InjectionPoint... injectionPoints);

    /**
     * Replace InjectionPoints for the configured bean
     *
     * @param injectionPoints the injectionPoints for the configured bean
     * @return self
     */
    BeanConfigurator<T> injectionPoints(Set<InjectionPoint> injectionPoints);

    /**
     * Make the configured bean implements {@link PassivationCapable} and its Id for passivation.
     *
     *
     * @param id for
     * @see PassivationCapable#getId()
     * @return self
     */
    BeanConfigurator<T> id(String id);

    /**
     * Set a callback to create a bean instance.
     *
     * @param callback the callback to create the instance
     * @return self
     * @see Contextual#create(CreationalContext)
     */
    <U extends T> BeanConfigurator<U> createWith(Function<CreationalContext<U>, U> callback);

    /**
     * Set a callback to create a bean instance.
     * <p>
     * The {@link Instance} argument might be used to simulate producer method parameter injection. However, dependent scoped
     * bean instances obtained from {@link Instance} during the callback execution remain managed until the produced bean
     * instance is destroyed. Therefore, applications are encouraged to always destroy unneeded dependent scoped bean instances
     * obtained from {@link Instance}.
     * 
     * @param callback the callback to create the instance
     * @return self
     */
    <U extends T> BeanConfigurator<U> produceWith(Function<Instance<Object>, U> callback);

    /**
     * Set a callback to destroy a bean instance.
     * <p>
     * If no destroy callback is specified, a NOOP callback is automatically set.
     *
     * @param callback the callback to destroy the instance
     * @return self
     */
    BeanConfigurator<T> destroyWith(BiConsumer<T, CreationalContext<T>> callback);

    /**
     * Set a callback to destroy a bean instance.
     * <p>
     * If no dispose callback is specified, a NOOP callback is automatically set.
     * <p>
     * The {@link Instance} argument might be used to simulate disposer method parameter injection. All dependent scoped bean
     * instances obtained from {@link Instance} during the callback execution are destroyed when the execution completes.
     *
     * @param callback the callback to dispose the instance
     * @return self
     */
    BeanConfigurator<T> disposeWith(BiConsumer<T, Instance<Object>> callback);

    /**
     * Read the information from the given annotated type. All relevant information is overwritten.
     *
     * @param type class to read information from
     * @return self
     */
    <U extends T> BeanConfigurator<U> read(AnnotatedType<U> type);

    /**
     * Read the information from the given bean attributes. All relevant information is overwritten.
     *
     * @param beanAttributes beanAttributes to read information from
     * @return self
     */
    BeanConfigurator<T> read(BeanAttributes<?> beanAttributes);

    /**
     * Add a type to the bean types
     *
     * @param type the type to add
     * @return self
     */
    BeanConfigurator<T> addType(Type type);

    /**
     * Add a type to the bean types
     *
     * @param typeLiteral the type to add
     * @return self
     */
    BeanConfigurator<T> addType(TypeLiteral<?> typeLiteral);

    /**
     * Add types to the bean types
     *
     * @param types types to add
     * @return self
     */
    BeanConfigurator<T> addTypes(Type... types);

    /**
     * Add types to the bean types
     *
     * @param types types to add
     * @return self
     */
    BeanConfigurator<T> addTypes(Set<Type> types);

    /**
     * Adds an unrestricted set of bean types for the given type as if it represented a bean class of a managed bean.
     * Illegal bean types are omitted.
     *
     * @param type to build the closure from
     * @return self
     */
    BeanConfigurator<T> addTransitiveTypeClosure(Type type);

    /**
     * Replace bean types
     *
     * @param types the types of the configured bean
     * @return self
     */
    BeanConfigurator<T> types(Type... types);

    /**
     * Replace bean types
     *
     * @param types the types of the configured bean
     * @return self
     */
    BeanConfigurator<T> types(Set<Type> types);

    /**
     * Replace Bean scope
     *
     * @param scope new scope for the configured bean
     * @return self
     */
    BeanConfigurator<T> scope(Class<? extends Annotation> scope);

    /**
     * Add a qualifier to the configured bean
     *
     * @param qualifier qualifier to add
     * @return self
     */
    BeanConfigurator<T> addQualifier(Annotation qualifier);

    /**
     * Add qualifiers to the bean.
     *
     * @param qualifiers qualifiers to add
     * @return self
     */
    BeanConfigurator<T> addQualifiers(Annotation... qualifiers);

    /**
     * Add qualifiers to the bean.
     *
     * @param qualifiers qualifiers to add
     * @return self
     */
    BeanConfigurator<T> addQualifiers(Set<Annotation> qualifiers);

    /**
     * Replace all qualifiers.
     *
     * @param qualifiers qualifiers for the build bean
     * @return self
     */
    BeanConfigurator<T> qualifiers(Annotation... qualifiers);

    /**
     * Replace all qualifiers.
     *
     * @param qualifiers for the configured bean
     * @return self
     */
    BeanConfigurator<T> qualifiers(Set<Annotation> qualifiers);

    /**
     * Add a stereotype to the configured bean
     *
     * @param stereotype stereotype to add
     * @return self
     */
    BeanConfigurator<T> addStereotype(Class<? extends Annotation> stereotype);

    /**
     * Add stereotypes to the configured bean
     *
     * @param stereotypes stereotypes to add
     * @return self
     */
    BeanConfigurator<T> addStereotypes(Set<Class<? extends Annotation>> stereotypes);

    /**
     * Replace stereotypes on the configured bean
     *
     * @param stereotypes for the configured bean
     * @return self
     */
    BeanConfigurator<T> stereotypes(Set<Class<? extends Annotation>> stereotypes);

    /**
     * Set the name of the configured bean
     *
     * @param name name for the configured bean
     * @return self
     */
    BeanConfigurator<T> name(String name);

    /**
     * Change the alternative status of the configured bean.
     * By default the configured bean is not an alternative.
     *
     * @param value value for alternative property
     * @return self
     */
    BeanConfigurator<T> alternative(boolean value);

}