tessl/maven-io-quarkus--quarkus-arc-deployment

Quarkus ArC deployment module providing build-time CDI optimization and configuration capabilities

—

Pending

Overview

Eval results

Files

Build Items

Name: tessl/maven-io-quarkus--quarkus-arc-deployment
Author: tessl

Build items are the primary API for extending Quarkus ArC's CDI functionality at build time. They provide type-safe communication between build steps and enable customization of bean discovery, registration, and container configuration.

Capabilities

Bean Registration

/**
 * Register additional bean classes for CDI discovery
 */
public class AdditionalBeanBuildItem extends MultiBuildItem {
    public AdditionalBeanBuildItem(String... beanClasses);
    public AdditionalBeanBuildItem(Class<?>... beanClasses);
    
    public static Builder builder();
    public static AdditionalBeanBuildItem unremovableOf(Class<?> beanClass);
    public static AdditionalBeanBuildItem unremovableOf(String beanClass);
    
    public List<String> getBeanClasses();
    public boolean contains(String beanClass);
    public boolean isRemovable();
    public DotName getDefaultScope();
}

/**
 * Builder for fluent AdditionalBeanBuildItem creation
 */
public static class AdditionalBeanBuildItem.Builder {
    public Builder addBeanClasses(String... beanClasses);
    public Builder addBeanClasses(Class<?>... beanClasses);
    public Builder setUnremovable();
    public Builder setRemovable();
    public Builder setDefaultScope(DotName scope);
    public Builder requiresContainerServices();
    public AdditionalBeanBuildItem build();
}

Usage Examples:

// Register service classes as CDI beans
@BuildStep
AdditionalBeanBuildItem registerServices() {
    return AdditionalBeanBuildItem.builder()
        .addBeanClasses(MyService.class, MyRepository.class)
        .setUnremovable()
        .setDefaultScope(DotNames.APPLICATION_SCOPED)
        .build();
}

// Register beans by class name
@BuildStep
AdditionalBeanBuildItem registerByName() {
    return new AdditionalBeanBuildItem("com.example.Service", "com.example.Config");
}

Synthetic Bean Creation

Create beans programmatically without requiring source classes, enabling advanced runtime configuration.

/**
 * Register synthetic (programmatically created) beans
 */
public class SyntheticBeanBuildItem extends MultiBuildItem {
    public static ExtendedBeanConfigurator configure(Class<?> implClazz);
    public static ExtendedBeanConfigurator configure(DotName implClazz);
    public static ExtendedBeanConfigurator create(Class<?> implClazz);
    public static ExtendedBeanConfigurator create(DotName implClazz);
}

/**
 * Extended configurator for synthetic beans with Quarkus-specific features
 */
public static class SyntheticBeanBuildItem.ExtendedBeanConfigurator 
    extends BeanConfiguratorBase<SyntheticBeanBuildItem.ExtendedBeanConfigurator> {
    
    public SyntheticBeanBuildItem done();
    public ExtendedBeanConfigurator supplier(Supplier<?> supplier);
    public ExtendedBeanConfigurator runtimeValue(RuntimeValue<?> runtimeValue);
    public <T> ExtendedBeanConfigurator createWith(
        Function<SyntheticCreationalContext<T>, T> function);
    public ExtendedBeanConfigurator runtimeProxy(Object proxy);
    public ExtendedBeanConfigurator setRuntimeInit();
    public ExtendedBeanConfigurator checkActive(Supplier<ActiveResult> checkActive);
}

Usage Examples:

// Create synthetic bean from supplier
@BuildStep
SyntheticBeanBuildItem createDatabaseConnection(DatabaseConfig config) {
    return SyntheticBeanBuildItem.configure(DatabaseConnection.class)
        .scope(ApplicationScoped.class)
        .supplier(() -> new DatabaseConnection(config.url(), config.username()))
        .done();
}

// Create synthetic bean with runtime initialization
@BuildStep
SyntheticBeanBuildItem createRuntimeService() {
    return SyntheticBeanBuildItem.configure(RuntimeService.class)
        .setRuntimeInit()
        .createWith(context -> {
            // Access to SyntheticCreationalContext for dependency injection
            return new RuntimeService(context.getBean(Configuration.class));
        })
        .done();
}

Bean Exclusion and Protection

Control which beans are discovered and prevent important beans from being removed during optimization.

/**
 * Mark beans as unremovable during unused bean removal
 */
public class UnremovableBeanBuildItem extends MultiBuildItem {
    public UnremovableBeanBuildItem(Predicate<BeanInfo> predicate);
    
    public static UnremovableBeanBuildItem beanClassNames(String... classNames);
    public static UnremovableBeanBuildItem beanClassNames(Set<String> classNames);
    public static UnremovableBeanBuildItem beanTypes(DotName... typeNames);
    public static UnremovableBeanBuildItem beanTypes(Class<?>... types);
    public static UnremovableBeanBuildItem beanTypes(Set<DotName> typeNames);
    public static UnremovableBeanBuildItem beanClassAnnotation(DotName annotationName);
    public static UnremovableBeanBuildItem targetWithAnnotation(DotName annotationName);
    
    public Predicate<BeanInfo> getPredicate();
    public Set<String> getClassNames();
}

/**
 * Exclude types from CDI discovery
 */
public class ExcludedTypeBuildItem extends MultiBuildItem {
    public ExcludedTypeBuildItem(String match);
    public String getMatch();
}

Usage Examples:

// Protect specific bean classes from removal
@BuildStep
UnremovableBeanBuildItem protectServices() {
    return UnremovableBeanBuildItem.beanClassNames(
        "com.example.CriticalService",
        "com.example.SystemService"
    );
}

// Protect beans with specific annotations
@BuildStep
UnremovableBeanBuildItem protectAnnotatedBeans() {
    return UnremovableBeanBuildItem.beanClassAnnotation(
        DotName.createSimple("com.example.Important")
    );
}

// Exclude packages from discovery  
@BuildStep
ExcludedTypeBuildItem excludeTestPackages() {
    return new ExcludedTypeBuildItem("com.example.test.**");
}

Bean Metadata and Discovery

Provide information about bean archives and control bean discovery phases.

/**
 * Jandex index with complete CDI information
 */
public class BeanArchiveIndexBuildItem extends SimpleBuildItem {
    public BeanArchiveIndexBuildItem(IndexView index, IndexView immutableIndex, 
                                    Set<DotName> generatedClassNames);
    
    public IndexView getIndex();
    public IndexView getImmutableIndex();
    public Set<DotName> getGeneratedClassNames();
}

/**
 * Marks completion of bean discovery phase
 */
public class BeanDiscoveryFinishedBuildItem extends SimpleBuildItem {
    // Marker build item indicating bean discovery is complete
}

/**
 * Bean registration phase marker
 */
public class BeanRegistrationPhaseBuildItem extends SimpleBuildItem {
    public BeanRegistrationPhaseBuildItem(BeanProcessor.Builder builder);
    public BeanProcessor.Builder getBeanProcessor();
}

Custom Scopes and Annotations

/**
 * Register custom CDI scope annotations
 */
public class CustomScopeBuildItem extends MultiBuildItem {
    public CustomScopeBuildItem(Class<? extends Annotation> scope);
    public CustomScopeBuildItem(DotName annotationName);
    public DotName getAnnotationName();
}

/**
 * Register additional bean-defining annotations
 */
public class BeanDefiningAnnotationBuildItem extends MultiBuildItem {
    public BeanDefiningAnnotationBuildItem(DotName name);
    public BeanDefiningAnnotationBuildItem(DotName name, DotName defaultScope);
    public BeanDefiningAnnotationBuildItem(DotName name, DotName defaultScope, boolean removable);
    
    public DotName getName();
    public DotName getDefaultScope();
    public boolean isRemovable();
}

/**
 * Automatically add scope annotations to classes
 */
public class AutoAddScopeBuildItem extends MultiBuildItem {
    public static Builder builder();
    
    public boolean isContainerServicesRequired();
    public DotName getDefaultScope();
    public boolean isUnremovable();
    public String getReason();
    public int getPriority();
    public boolean test(ClassInfo clazz, Collection<AnnotationInstance> annotations, IndexView index);
}

Usage Examples:

// Register custom scope
@BuildStep
CustomScopeBuildItem registerCustomScope() {
    return new CustomScopeBuildItem(TenantScoped.class);
}

// Auto-add scopes to matching classes
@BuildStep
AutoAddScopeBuildItem autoScopeServices() {
    return AutoAddScopeBuildItem.builder()
        .containsOne("com.example.service")
        .defaultScope(DotNames.APPLICATION_SCOPED)
        .reason("Service classes should be application scoped")
        .build();
}

Generated Classes

Handle dynamically generated bean classes during the build process.

/**
 * Represents a generated CDI bean class
 */
public class GeneratedBeanBuildItem extends MultiBuildItem {
    public GeneratedBeanBuildItem(String name, byte[] data);
    public GeneratedBeanBuildItem(String name, byte[] data, String source);
    public GeneratedBeanBuildItem(String name, byte[] data, String source, boolean applicationClass);
    
    public String getName();
    public byte[] getData();
    public String getSource();
    public boolean isApplicationClass();
}

Annotation and Metadata Transformation

Transform annotations and metadata on CDI components during the build process.

/**
 * Transform annotations on CDI components
 */
public class AnnotationsTransformerBuildItem extends MultiBuildItem {
    public AnnotationsTransformerBuildItem(AnnotationsTransformer transformer);
    public AnnotationsTransformer getAnnotationsTransformer();
}

/**
 * Transform injection point qualifiers
 */
public class InjectionPointTransformerBuildItem extends MultiBuildItem {
    public InjectionPointTransformerBuildItem(InjectionPointsTransformer transformer);
    public InjectionPointsTransformer getTransformer();
}

/**
 * Transform observer methods
 */
public class ObserverTransformerBuildItem extends MultiBuildItem {
    public ObserverTransformerBuildItem(ObserverTransformer transformer);
    public ObserverTransformer getObserverTransformer();
}

/**
 * Define auto-inject annotations for fields
 */
public class AutoInjectAnnotationBuildItem extends MultiBuildItem {
    public AutoInjectAnnotationBuildItem(DotName annotationName);
    public DotName getAnnotationName();
}

Interceptor and AOP Support

/**
 * Register interceptor binding annotations
 */
public class InterceptorBindingRegistrarBuildItem extends MultiBuildItem {
    public InterceptorBindingRegistrarBuildItem(InterceptorBindingRegistrar registrar);
    public InterceptorBindingRegistrar getInterceptorBindingRegistrar();
}

/**
 * Access to the interceptor resolver
 */
public class InterceptorResolverBuildItem extends SimpleBuildItem {
    public InterceptorResolverBuildItem(InterceptorResolver interceptorResolver);
    public InterceptorResolver getInterceptorResolver();
}

/**
 * Support for static method interception
 */
public class InterceptedStaticMethodBuildItem extends MultiBuildItem {
    public InterceptedStaticMethodBuildItem(String className, String methodName, 
                                           Type returnType, Type[] parameterTypes);
    public String getClassName();
    public String getMethodName();
    public Type getReturnType();
    public Type[] getParameterTypes();
}

Context and Scope Management

Manage CDI contexts and custom scope implementations.

/**
 * Context registration phase access
 */
public class ContextRegistrationPhaseBuildItem extends SimpleBuildItem {
    public static class ContextConfiguratorBuildItem extends MultiBuildItem {
        // Nested class for context configurators
    }
}

/**
 * Custom current context factory provider
 */
public class CurrentContextFactoryBuildItem extends SimpleBuildItem {
    public CurrentContextFactoryBuildItem(RuntimeValue<CurrentContextFactory> factory);
    public RuntimeValue<CurrentContextFactory> getFactory();
}

/**
 * Information about custom scopes
 */
public class CustomScopeAnnotationsBuildItem extends SimpleBuildItem {
    public CustomScopeAnnotationsBuildItem(Set<DotName> customScopeNames);
    public Set<DotName> getCustomScopeNames();
    public boolean isScopeIn(Collection<AnnotationInstance> annotations);
}

Qualifier and Stereotype Registration

/**
 * Register qualifier annotations
 */
public class QualifierRegistrarBuildItem extends MultiBuildItem {
    public QualifierRegistrarBuildItem(QualifierRegistrar registrar);
    public QualifierRegistrar getQualifierRegistrar();
}

/**
 * Register stereotype annotations
 */
public class StereotypeRegistrarBuildItem extends MultiBuildItem {
    public StereotypeRegistrarBuildItem(StereotypeRegistrar registrar);
    public StereotypeRegistrar getStereotypeRegistrar();
}

/**
 * Build-time enabled stereotypes information
 */
public class BuildTimeEnabledStereotypesBuildItem extends SimpleBuildItem {
    public BuildTimeEnabledStereotypesBuildItem(Set<DotName> stereotypes);
    public Set<DotName> getStereotypes();
}

Configuration and Conditions

Handle build-time configuration and conditional logic.

/**
 * Validate mandatory config properties at runtime
 */
public class ConfigPropertyBuildItem extends MultiBuildItem {
    public ConfigPropertyBuildItem(String propertyName, Type propertyType, 
                                  String defaultValue, ExecutionTime executionTime);
    public String getPropertyName();
    public Type getPropertyType();
    public String getDefaultValue();
    public ExecutionTime getExecutionTime();
}

/**
 * Handle build-time conditions
 */
public class BuildTimeConditionBuildItem extends MultiBuildItem {
    public BuildTimeConditionBuildItem(Predicate<BuildTimeConditionEvaluator.BuildTimeConditionContext> condition, 
                                      boolean enabledWhenMatched);
    public Predicate<BuildTimeConditionEvaluator.BuildTimeConditionContext> getCondition();
    public boolean isEnabledWhenMatched();
}

/**
 * Excluded build-time condition information
 */
public class BuildExclusionsBuildItem extends SimpleBuildItem {
    public BuildExclusionsBuildItem(Set<String> excludedTypes, 
                                   Function<String, Optional<Predicate<BeanInfo>>> predicateFunction);
    public Set<String> getExcludedTypes();
    public Function<String, Optional<Predicate<BeanInfo>>> getPredicateFunction();
}

Archive and Discovery Control

Control bean archive discovery and package handling.

/**
 * Register logic to identify bean archives
 */
public class BeanArchivePredicateBuildItem extends MultiBuildItem {
    public BeanArchivePredicateBuildItem(Predicate<ApplicationArchive> predicate);
    public Predicate<ApplicationArchive> getPredicate();
}

/**
 * Mark bean archives as Quarkus-compatible
 */
public class KnownCompatibleBeanArchiveBuildItem extends MultiBuildItem {
    public KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId);
    public String getGroupId();
    public String getArtifactId();
}

/**
 * Exclude packages from split package detection
 */
public class IgnoreSplitPackageBuildItem extends MultiBuildItem {
    public IgnoreSplitPackageBuildItem(String packageName);
    public String getPackageName();
}

/**
 * Final application class predicate
 */
public class CompletedApplicationClassPredicateBuildItem extends SimpleBuildItem {
    public CompletedApplicationClassPredicateBuildItem(Predicate<DotName> predicate);
    public Predicate<DotName> getPredicate();
}

Reflection and Code Generation

Handle reflection requirements and code generation phases.

/**
 * Request reflective access for bean classes
 */
public class ReflectiveBeanClassBuildItem extends MultiBuildItem {
    public ReflectiveBeanClassBuildItem(String className);
    public String getClassName();
}

/**
 * Resource generation phase marker
 */
public class ResourcesGeneratedPhaseBuildItem extends EmptyBuildItem {
    // Phase marker for resource generation completion
}

/**
 * Method invoker creation access
 */
public class InvokerFactoryBuildItem extends MultiBuildItem {
    public InvokerFactoryBuildItem(InvokerFactory invokerFactory);
    public InvokerFactory getInvokerFactory();
}

Integration and Extensions

Handle CDI extensions and integration with other systems.

/**
 * CDI Lite build compatible extensions entry point
 */
public class BuildCompatibleExtensionsBuildItem extends SimpleBuildItem {
    public BuildCompatibleExtensionsBuildItem(BuildCompatibleExtensions extensions);
    public BuildCompatibleExtensions getExtensions();
}

/**
 * Non-CDI resource injection support
 */
public class ResourceAnnotationBuildItem extends MultiBuildItem {
    public ResourceAnnotationBuildItem(DotName name);
    public DotName getName();
}

/**
 * OpenTelemetry integration configuration
 */
public class OpenTelemetrySdkBuildItem extends SimpleBuildItem {
    // OpenTelemetry SDK configuration information
}

/**
 * Runtime-init synthetic bean coordination
 */
public class SyntheticBeansRuntimeInitBuildItem extends EmptyBuildItem {
    // Marker for runtime-init synthetic beans
}

Validation and Build Phases

Control validation phases and build completion markers.

/**
 * Validation phase marker with error reporting
 */
public class ValidationPhaseBuildItem extends SimpleBuildItem {
    public ValidationPhaseBuildItem(
        BeanDeploymentValidator.ValidationContext validationContext,
        BeanProcessor beanProcessor
    );
    
    public static class ValidationErrorBuildItem extends MultiBuildItem {
        public ValidationErrorBuildItem(Throwable error);
        public Throwable getError();
    }
}

/**
 * Observer registration phase access
 */
public class ObserverRegistrationPhaseBuildItem extends SimpleBuildItem {
    public static class ObserverConfiguratorBuildItem extends MultiBuildItem {
        // Nested class for observer configurators
    }
}

/**
 * Component inspection access
 */
public class SynthesisFinishedBuildItem extends SimpleBuildItem {
    public SynthesisFinishedBuildItem(List<BeanInfo> beans, List<ObserverInfo> observers);
    public List<BeanInfo> getBeans();
    public List<ObserverInfo> getObservers();
}

/**
 * Pre-container initialization marker
 */
public class PreBeanContainerBuildItem extends SimpleBuildItem {
    // Marker for pre-container build phase
}

/**
 * Registered components inspection
 */
public class RegisteredComponentsBuildItem extends SimpleBuildItem {
    // Base class for component inspection during build
}

/**
 * Query transformed annotations
 */
public class TransformedAnnotationsBuildItem extends SimpleBuildItem {
    public TransformedAnnotationsBuildItem(AnnotationStore annotationStore);
    public AnnotationStore getAnnotations();
}

Build Item Categories

MultiBuildItem vs SimpleBuildItem

MultiBuildItem: Multiple instances allowed per build (e.g., AdditionalBeanBuildItem)
SimpleBuildItem: Single instance per build (e.g., BeanContainerBuildItem)
EmptyBuildItem: Marker items with no data, used for phase coordination

Build Item Usage Patterns

Registration: Add new beans, scopes, or annotations
Protection: Prevent bean removal or mark as unremovable
Configuration: Customize CDI behavior and settings
Transformation: Modify existing beans or annotations
Phase Control: Coordinate build phases and dependencies

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkus--quarkus-arc-deployment

docs

tessl/maven-io-quarkus--quarkus-arc-deployment

build-items.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Build Items

Capabilities

Bean Registration

Synthetic Bean Creation

Bean Exclusion and Protection

Bean Metadata and Discovery

Custom Scopes and Annotations

Generated Classes

Annotation and Metadata Transformation

Interceptor and AOP Support

Context and Scope Management

Qualifier and Stereotype Registration

Configuration and Conditions

Archive and Discovery Control

Reflection and Code Generation

Integration and Extensions

Validation and Build Phases

Build Item Categories

MultiBuildItem vs SimpleBuildItem

Build Item Usage Patterns

build-items.mddocs/