jakarta.enterprise.inject.spi.configurator.BeanConfigurator Maven / Gradle / Ivy
Show all versions of jakarta.enterprise.cdi-api Show documentation
/*
* 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 jakarta.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 jakarta.enterprise.context.spi.Contextual;
import jakarta.enterprise.context.spi.CreationalContext;
import jakarta.enterprise.inject.Instance;
import jakarta.enterprise.inject.spi.AfterBeanDiscovery;
import jakarta.enterprise.inject.spi.AnnotatedType;
import jakarta.enterprise.inject.spi.Bean;
import jakarta.enterprise.inject.spi.BeanAttributes;
import jakarta.enterprise.inject.spi.InjectionPoint;
import jakarta.enterprise.inject.spi.PassivationCapable;
import jakarta.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.
*
* CDI Lite implementations are not required to provide support for Portable Extensions.
*
* @see AfterBeanDiscovery#addBean()
* @author Martin Kouba
* @author Antoine Sabot-Durand
* @param the class of the bean instance
* @since 2.0
*/
public interface BeanConfigurator {
/**
* 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 beanClass(Class beanClass);
/**
* Add an InjectionPoint to the configured bean
*
* @param injectionPoint the injectionPoint to add
* @return self
*/
BeanConfigurator addInjectionPoint(InjectionPoint injectionPoint);
/**
* Add InjectionPoints to the configured bean
*
* @param injectionPoints the injectionPoints to add
* @return self
*/
BeanConfigurator addInjectionPoints(InjectionPoint... injectionPoints);
/**
* Add InjectionPoints to the configured bean
*
* @param injectionPoints the injectionPoints to add
* @return self
*/
BeanConfigurator addInjectionPoints(Set injectionPoints);
/**
* Replace InjectionPoints for the configured bean
*
* @param injectionPoints the injectionPoints for the configured bean
* @return self
*/
BeanConfigurator injectionPoints(InjectionPoint... injectionPoints);
/**
* Replace InjectionPoints for the configured bean
*
* @param injectionPoints the injectionPoints for the configured bean
* @return self
*/
BeanConfigurator injectionPoints(Set injectionPoints);
/**
* Make the configured bean implements {@link PassivationCapable} and its Id for passivation.
*
*
* @param id for
* @see PassivationCapable#getId()
* @return self
*/
BeanConfigurator id(String id);
/**
* Set a callback to create a bean instance.
*
* @param instance type
* @param callback the callback to create the instance
* @return self
* @see Contextual#create(CreationalContext)
*/
BeanConfigurator createWith(Function, U> callback);
/**
* Set a callback to create a bean instance.
*
* 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 instance type
* @param callback the callback to create the instance
* @return self
*/
BeanConfigurator produceWith(Function, U> callback);
/**
* Set a callback to destroy a bean instance.
*
* If no destroy callback is specified, a NOOP callback is automatically set.
*
* @param callback the callback to destroy the instance
* @return self
*/
BeanConfigurator destroyWith(BiConsumer> callback);
/**
* Set a callback to destroy a bean instance.
*
* If no dispose callback is specified, a NOOP callback is automatically set.
*
* 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 disposeWith(BiConsumer> callback);
/**
* Read the information from the given annotated type. All relevant information is overwritten.
*
* @param instance type
* @param type class to read information from
* @return self
*/
BeanConfigurator read(AnnotatedType type);
/**
* Read the information from the given bean attributes. All relevant information is overwritten.
*
* @param beanAttributes beanAttributes to read information from
* @return self
*/
BeanConfigurator read(BeanAttributes beanAttributes);
/**
* Add a type to the bean types
*
* @param type the type to add
* @return self
*/
BeanConfigurator addType(Type type);
/**
* Add a type to the bean types
*
* @param typeLiteral the type to add
* @return self
*/
BeanConfigurator addType(TypeLiteral typeLiteral);
/**
* Add types to the bean types
*
* @param types types to add
* @return self
*/
BeanConfigurator addTypes(Type... types);
/**
* Add types to the bean types
*
* @param types types to add
* @return self
*/
BeanConfigurator addTypes(Set 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 addTransitiveTypeClosure(Type type);
/**
* Replace bean types
*
* @param types the types of the configured bean
* @return self
*/
BeanConfigurator types(Type... types);
/**
* Replace bean types
*
* @param types the types of the configured bean
* @return self
*/
BeanConfigurator types(Set types);
/**
* Replace Bean scope
*
* @param scope new scope for the configured bean
* @return self
*/
BeanConfigurator scope(Class scope);
/**
* Add a qualifier to the configured bean
*
* @param qualifier qualifier to add
* @return self
*/
BeanConfigurator addQualifier(Annotation qualifier);
/**
* Add qualifiers to the bean.
*
* @param qualifiers qualifiers to add
* @return self
*/
BeanConfigurator addQualifiers(Annotation... qualifiers);
/**
* Add qualifiers to the bean.
*
* @param qualifiers qualifiers to add
* @return self
*/
BeanConfigurator addQualifiers(Set qualifiers);
/**
* Replace all qualifiers.
*
* @param qualifiers qualifiers for the build bean
* @return self
*/
BeanConfigurator qualifiers(Annotation... qualifiers);
/**
* Replace all qualifiers.
*
* @param qualifiers for the configured bean
* @return self
*/
BeanConfigurator qualifiers(Set qualifiers);
/**
* Add a stereotype to the configured bean
*
* @param stereotype stereotype to add
* @return self
*/
BeanConfigurator addStereotype(Class stereotype);
/**
* Add stereotypes to the configured bean
*
* @param stereotypes stereotypes to add
* @return self
*/
BeanConfigurator addStereotypes(Set> stereotypes);
/**
* Replace stereotypes on the configured bean
*
* @param stereotypes for the configured bean
* @return self
*/
BeanConfigurator stereotypes(Set> stereotypes);
/**
* Set the name of the configured bean
*
* @param name name for the configured bean
* @return self
*/
BeanConfigurator 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 alternative(boolean value);
/**
* Set the priority of the configured bean.
* By default, the configured bean does not have a priority.
*
* This is equivalent to putting the {@link jakarta.annotation.Priority Priority}
* annotation to an actual bean class or making a custom
* {@link jakarta.enterprise.inject.spi.Bean Bean} class implement
* {@link jakarta.enterprise.inject.spi.Prioritized Prioritized}.
*
* This method has no effect if the configured bean is not an alternative.
*
* @param priority the priority value
* @return self
*/
BeanConfigurator priority(int priority);
}