or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced-features.md bean-container.md build-items.md configuration.md index.md processors.md

tile.json

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

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/io.quarkus/quarkus-arc-deployment@3.23.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-arc-deployment@3.23.0

Quarkus ArC Deployment

Quarkus ArC Deployment is the build-time component of Quarkus's optimized CDI (Contexts and Dependency Injection) implementation. It processes CDI beans, interceptors, decorators, and observers at build time to generate optimized bytecode, eliminating runtime reflection and enabling fast startup times with reduced memory footprint.

Package Information

Package Name: quarkus-arc-deployment
Package Type: maven
Language: Java
Group ID: io.quarkus
Artifact ID: quarkus-arc-deployment
Installation: Add to Maven pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-arc-deployment</artifactId>
    <version>3.23.0</version>
    <scope>provided</scope>
</dependency>

Core Imports

// Core build items for extending CDI functionality
import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
import io.quarkus.arc.deployment.SyntheticBeanBuildItem;
import io.quarkus.arc.deployment.UnremovableBeanBuildItem;
import io.quarkus.arc.deployment.BeanContainerBuildItem;
import io.quarkus.arc.deployment.BeanArchiveIndexBuildItem;
import io.quarkus.arc.deployment.BeanRegistrationPhaseBuildItem;
import io.quarkus.arc.deployment.ValidationPhaseBuildItem;

// Configuration interfaces
import io.quarkus.arc.deployment.ArcConfig;
import io.quarkus.arc.deployment.ArcConfig.OptimizeContexts;

// Annotation and metadata transformation
import io.quarkus.arc.deployment.AnnotationsTransformerBuildItem;
import io.quarkus.arc.deployment.InjectionPointTransformerBuildItem;
import io.quarkus.arc.deployment.ObserverTransformerBuildItem;

// Scope and context management
import io.quarkus.arc.deployment.CustomScopeBuildItem;
import io.quarkus.arc.deployment.ContextRegistrationPhaseBuildItem;
import io.quarkus.arc.deployment.CurrentContextFactoryBuildItem;

// Interceptor and AOP support
import io.quarkus.arc.deployment.InterceptorBindingRegistrarBuildItem;
import io.quarkus.arc.deployment.InterceptorResolverBuildItem;
import io.quarkus.arc.deployment.InterceptedStaticMethodBuildItem;

// Build processors and steps
import io.quarkus.arc.deployment.ArcProcessor;
import io.quarkus.deployment.annotations.BuildStep;
import io.quarkus.deployment.annotations.Record;
import io.quarkus.deployment.annotations.ExecutionTime;

// Jandex indexing
import org.jboss.jandex.DotName;
import org.jboss.jandex.IndexView;
import org.jboss.jandex.AnnotationInstance;

Basic Usage

// Example Quarkus extension using ArC deployment APIs
@BuildStep
AdditionalBeanBuildItem registerBeans() {
    return AdditionalBeanBuildItem.builder()
        .addBeanClasses(MyService.class, MyConfiguration.class)
        .setUnremovable()
        .build();
}

@BuildStep
SyntheticBeanBuildItem createSyntheticBean() {
    return SyntheticBeanBuildItem.configure(MyRuntimeBean.class)
        .scope(ApplicationScoped.class)
        .supplier(() -> new MyRuntimeBean())
        .done();
}

Architecture

Quarkus ArC Deployment is built around several key architectural patterns:

Build Items: Primary extension API providing type-safe communication between build steps
Build Processors: Classes containing @BuildStep methods that consume and produce build items
Configuration: Typed configuration interfaces for build-time CDI settings
Synthetic Components: Programmatic creation of CDI beans, interceptors, and observers
Bean Discovery: Automated scanning and registration of CDI components
Optimization: Build-time analysis for unused bean removal and context optimization

Capabilities

Build Items API

Core build items for registering beans, configuring CDI behavior, and extending the container at build time. These are the primary integration points for Quarkus extensions.

// Register additional bean classes for CDI discovery
public class AdditionalBeanBuildItem extends MultiBuildItem {
    public AdditionalBeanBuildItem(String... beanClasses);
    public AdditionalBeanBuildItem(Class<?>... beanClasses);
    public static Builder builder();
}

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

// Mark beans as unremovable during unused bean removal
public class UnremovableBeanBuildItem extends MultiBuildItem {
    public static UnremovableBeanBuildItem beanClassNames(String... classNames);
    public static UnremovableBeanBuildItem beanTypes(Class<?>... types);
    public static UnremovableBeanBuildItem beanClassAnnotation(DotName annotationName);
}

Build Items

Configuration API

Build-time configuration interfaces for customizing CDI container behavior, bean discovery, and optimization settings.

// Main ArC configuration interface
public interface ArcConfig {
    String removeUnusedBeans();
    boolean autoInjectFields();
    boolean transformUnproxyableClasses();
    Optional<List<String>> selectedAlternatives();
    Optional<List<String>> excludeTypes();
    boolean detectWrongAnnotations();
    boolean strictCompatibility();
}

Configuration

Bean Container Integration

Integration with the CDI bean container, providing access to the fully initialized container and registration of container listeners.

// Access to the fully initialized CDI bean container
public class BeanContainerBuildItem extends SimpleBuildItem {
    public BeanContainerBuildItem(BeanContainer value);
    public BeanContainer getValue();
}

// Register listeners for bean container initialization
public class BeanContainerListenerBuildItem extends MultiBuildItem {
    public BeanContainerListenerBuildItem(BeanContainerListener beanContainerListener);
    public BeanContainerListener getBeanContainerListener();
}

Bean Container

Annotation and Metadata Transformation

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

// 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();
}

Context and Scope Management

Manage CDI contexts and custom scope implementations with full lifecycle control.

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

// Context registration phase access
public class ContextRegistrationPhaseBuildItem extends SimpleBuildItem {
    // Provides access to context registration configurators
}

Interceptor and AOP Support

Comprehensive support for interceptors, method interception, and aspect-oriented programming features.

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

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

Build Phases and Lifecycle

Control build phases, validation, and lifecycle events throughout the CDI container construction process.

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

// Validation phase with error reporting
public class ValidationPhaseBuildItem extends SimpleBuildItem {
    public static class ValidationErrorBuildItem extends MultiBuildItem {
        public ValidationErrorBuildItem(Throwable error);
    }
}

Advanced CDI Features

Support for advanced CDI features including custom scopes, observers, qualifiers, and stereotypes with build-time transformation capabilities.

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

// Transform annotations on CDI components
public class AnnotationsTransformerBuildItem extends MultiBuildItem {
    public AnnotationsTransformerBuildItem(AnnotationTransformation transformation);
    public AnnotationTransformation getAnnotationTransformation();
}

Advanced Features

Archive and Discovery Control

Control bean archive discovery, indexing, and package handling with flexible configuration options.

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

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

Configuration and Conditions

Handle build-time configuration, conditional logic, and environment-specific behavior.

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

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

Reflection and Code Generation

Handle reflection requirements, code generation phases, and bytecode manipulation.

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

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

Processors and Build Steps

Core processors implementing the CDI build-time logic and extension points for custom build step integration.

// Main ArC processor with CDI build steps
public class ArcProcessor {
    @BuildStep
    public BeanContainerBuildItem build(/* various build items */);
    
    @BuildStep
    public ValidationPhaseBuildItem validate(/* validation inputs */);
    
    @BuildStep
    public BeanRegistrationPhaseBuildItem registerBeans(/* registration inputs */);
}

// Adaptor for bytecode generation during bean creation
public class GeneratedBeanGizmoAdaptor implements ClassOutput {
    public void write(String name, byte[] data);
    public String getSource();
    public boolean isApplicationClass();
}

Processors

Types

Core Build Item Types

// Base classes for build items
public abstract class MultiBuildItem {
    // Multiple instances allowed per build
}

public abstract class SimpleBuildItem {
    // Single instance per build
}

// Builder pattern for additional beans
public static class AdditionalBeanBuildItem.Builder {
    public Builder addBeanClasses(String... beanClasses);
    public Builder addBeanClasses(Class<?>... beanClasses);
    public Builder setUnremovable();
    public Builder setDefaultScope(DotName scope);
    public AdditionalBeanBuildItem build();
}

Synthetic Bean Configuration

// Extended configurator for synthetic beans
public static class SyntheticBeanBuildItem.ExtendedBeanConfigurator 
    extends BeanConfiguratorBase<SyntheticBeanBuildItem.ExtendedBeanConfigurator> {
    
    public SyntheticBeanBuildItem done();
    public ExtendedBeanConfigurator supplier(Supplier<?> supplier);
    public ExtendedBeanConfigurator runtimeValue(RuntimeValue<?> runtimeValue);
    public ExtendedBeanConfigurator setRuntimeInit();
}

Configuration Interfaces

// Main configuration interface with all build-time settings
public interface ArcConfig {
    String removeUnusedBeans();
    boolean autoInjectFields();
    boolean transformUnproxyableClasses();
    boolean transformPrivateInjectedFields();
    boolean failOnInterceptedPrivateMethod();
    Optional<List<String>> selectedAlternatives();
    boolean autoProducerMethods();
    Optional<List<String>> excludeTypes();
    Optional<List<String>> unremovableTypes();
    Map<String, IndexDependencyConfig> excludeDependency();
    boolean detectUnusedFalsePositives();
    boolean detectWrongAnnotations();
    boolean strictCompatibility();
    ArcDevModeConfig devMode();
    ArcTestConfig test();
    Optional<List<String>> ignoredSplitPackages();
    ArcContextPropagationConfig contextPropagation();
    OptimizeContexts optimizeContexts();
}

// Development mode configuration
public interface ArcDevModeConfig {
    boolean monitoringEnabled();
    boolean lifecycleEvents();
}

// Test mode configuration  
public interface ArcTestConfig {
    boolean disableApplicationIndex();
    boolean transformTestClasses();
}

// Context propagation configuration
public interface ArcContextPropagationConfig {
    boolean enabled();
    Optional<List<String>> propagatedContexts();
}

// Index dependency configuration
public interface IndexDependencyConfig {
    Optional<String> groupId();
    Optional<String> artifactId();
    Optional<String> classifier();
}

Configuration Enums

// Context optimization strategies
public enum OptimizeContexts {
    AUTO,     // Automatically determine optimization based on usage
    ENABLED,  // Force enable context optimization
    DISABLED  // Disable context optimization
}

Build Item Categories

// Base build item types
public abstract class MultiBuildItem {
    // Multiple instances allowed per build step
}

public abstract class SimpleBuildItem {
    // Single instance per build step
}

public abstract class EmptyBuildItem {
    // Marker build items with no data payload
}

Transformer and Registrar Interfaces

// Annotation transformation interface
public interface AnnotationsTransformer {
    boolean appliesTo(AnnotationTarget.Kind kind);
    void transform(TransformationContext transformationContext);
}

// Injection point transformation interface
public interface InjectionPointsTransformer {
    boolean appliesTo(Type requiredType, Set<Annotation> qualifiers);
    void transform(TransformationContext transformationContext);
}

// Observer transformation interface  
public interface ObserverTransformer {
    boolean appliesTo(MethodInfo observerMethod, AnnotationInstance observesAnnotation);
    void transform(ObserverTransformationContext transformationContext);
}

// Interceptor binding registrar interface
public interface InterceptorBindingRegistrar {
    void register(RegistrationContext registrationContext);
}

// Qualifier registrar interface
public interface QualifierRegistrar {
    void register(RegistrationContext registrationContext);
}

// Stereotype registrar interface
public interface StereotypeRegistrar {
    void register(RegistrationContext registrationContext);
}

Utility and Helper Types

// Bean container interface for runtime access
public interface BeanContainer {
    <T> T select(Class<T> type, Annotation... qualifiers);
    boolean hasBean(Class<?> type, Annotation... qualifiers);
    void destroy(Object instance);
}

// Bean container listener for initialization callbacks
public interface BeanContainerListener {
    void created(BeanContainer container);
}

// Runtime value wrapper for recorder integration
public interface RuntimeValue<T> {
    T getValue();
}

// Synthetic creational context for programmatic bean creation
public interface SyntheticCreationalContext<T> {
    <U> U getBean(Class<U> type, Annotation... qualifiers);
    T create();
}