CDI 4.0 Lite - Understanding Build Compatible Extensions with Examples

This is the fourth article in the Mamezou Developer Site Advent Calendar 2023.

It has been a year since the release of JakartaEE 10, but there is still almost no information about the Build compatible extensions introduced from JakartaEE 10. Even the official Specification provides only a simplistic explanation that seems to merely restate class and method names, and it was unclear how to use it effectively or how it differs from the previously existing Portable extensions.

While searching for a good example on GitHub, I found a very understandable sample. In this article, I would like to explain Build compatible extensions using this sample.

Let's dive right into the main topic. Normally, I would explain the purpose and functionality before moving into the code explanation with a phrase like "So, let's", but since Build compatible extensions are a difficult feature to grasp, I will start by explaining the sample code that uses Build compatible extensions.

In this article, I will explain the topic of Build compatible extensions that we will use.

Build compatible extensions extend existing CDI features using APIs defined in their specifications. First, I will explain the target of the functionality extension using Build compatible extensions.

The target for CDI extension is the following classes. As you can see from the code shown below, the implementation of each class is quite simple.

Processor is an interface defined with a doWork method that performs some work, and for this, we use two implementation classes: MyProcessor and AnotherProcessor. Both are implementation classes of the Processor interface, but @Important is only attached to the MyProcessor class. Additionally, the implementation of the doWork method in both is a simple one that only outputs logs.

public interface Processor {
    void doWork();
}

@Important
public class MyProcessor implements Processor {
    private static final Logger log = LoggerFactory.getLogger(MyProcessor.class);
    @Override
    public void doWork() {
        log.info("Working really hard");
    }
}

public class AnotherProcessor implements Processor {
    private static final Logger log = LoggerFactory.getLogger(AnotherProcessor.class);
    @Override
    public void doWork() {
        log.info("Working barely enough");
    }
}

Next is the ImportantClassChecker, which is an interface that checks whether a class passed as an argument is important. This time, we use the ImportantClassCheckerImpl as the implementation class, which pre-sorts a set of important classes and determines them as "important" if the class passed as an argument is included in that set.

public interface ImportantClassChecker {
    boolean isImportant(Class<?> clazz);
}

public class ImportantClassCheckerImpl implements ImportantClassChecker {
    private final Set<String> importantClasses;
    public ImportantClassCheckerImpl(Set<String> importantClasses) {
        this.importantClasses = importantClasses;
    }
    @Override
    public boolean isImportant(Class<?> clazz) {
        return importantClasses.contains(clazz.getName());
    }
}

Using Build compatible extensions, we will change the classes described in "Target of CDI Extension" to the state shown below at runtime.

• After CDI extension (red elements are changes/additions)

You might wonder how the implementation described in "Target of CDI Extension" can be transformed into the "After CDI Extension" implementation. This involves Java's black magic-like bytecode manipulation. The CDI container manipulates the bytecode of the class files described in "Target of CDI Extension" according to the implementation of Build compatible extensions and modifies them into the class files of "After CDI Extension" by runtime (startup).

From this, the implementation of Build compatible extensions can be said to instruct the CDI container "which classes to" and "how to modify".

So, what instructions are necessary in this sample? They are as follows:

1. Make the MyProcessor and AnotherProcessor classes targets of CDI Beans (subject to CDI container management)
2. Set the CDI scope of the MyProcessor and AnotherProcessor classes to @ApplicationScoped
3. Add a log marker to the doWork implementation method of the Processor interface
4. Collect the class names of CDI Beans with @Important attached to the Processor
5. Generate an instance of CDI Bean that is an instance of the ImportantClassCheckerImpl class and injectable as the ImportantClassChecker interface using the ImportantClassCheckerCreator
6. When generating an instance of ImportantClassCheckerImpl with the ImportantClassCheckerCreator, pass the class names collected in step 4.

The implementation of the ImportantClassCheckerCreator that generates CDI Bean instances is as follows:

public class ImportantClassCheckerCreator 
        implements SyntheticBeanCreator<ImportantClassCheckerImpl> {
    @Override
    public ImportantClassCheckerImpl create(Instance<Object> lookup, Parameters params) {
        String[] importantProcessors = params.get("importantProcessors", String[].class);
        return new ImportantClassCheckerImpl(Set.of(importantProcessors));
    }
}

SyntheticBeanCreator is an interface defined as part of Build compatible extensions, but here it is sufficient to understand it as a simple one that passes the params passed as arguments to the constructor of ImportantClassCheckerImpl.

Now that the explanation of the topic is complete, we move on to the main subject. First, the implementation of Build compatible extensions that realizes the above topic is as follows:

public class BuildExtension implements BuildCompatibleExtension {
    private static Logger log = LoggerFactory.getLogger(BuildExtension.class);
    private final Set<ClassInfo> processors = new HashSet<>();
    @Discovery
    public void discoverFrameworkClasses(ScannedClasses scan) {
        log.info("*** execute Discovery ***");
        Config config = ConfigProvider.getConfig();
        config.getOptionalValue("sample.app.processer.class", String[].class)
                .ifPresent(values -> Stream.of(values).forEach(scan::add));
    }
    @Enhancement(types = Processor.class, withSubtypes = true)
    public void addInterceptorBindingToProcessors(ClassConfig clazz) {
        log.info("*** execute Enhancement ***");
        clazz.addAnnotation(ApplicationScoped.class);
        clazz.methods()
                .stream()
                .filter(it -> it.info().name().equals("doWork") and it.info().parameters().isEmpty())
                .forEach(it -> it.addAnnotation(Logged.class));
    }
    @Registration(types = Processor.class)
    public void rememberProcessors(BeanInfo bean) {
        log.info("*** execute Registration ***");
        if (bean.isClassBean()) {
            processors.add(bean.declaringClass());
        }
    }
    @Synthesis
    public void registerImportanceImpl(SyntheticComponents synth) {
        log.info("*** execute Synthesis ***");
        String[] importantProcessors = processors.stream()
                .filter(it -> it.hasAnnotation(Important.class))
                .map(ClassInfo::name)
                .toArray(String[]::new);
        synth.addBean(ImportantClassCheckerImpl.class)
                .type(ImportantClassChecker.class)
                .withParam("importantProcessors", importantProcessors)
                .createWith(ImportantClassCheckerCreator.class);
    }
    @Validation
    public void validateProcessors(Messages msg) {
        log.info("*** execute Validation ***");
        if (processors.isEmpty()) {
            msg.error("At least one `Processor` implementation must exist");
        }
    }
}

The first thing you notice when looking at the code is the annotations attached to the methods. CDI Bean initialization is divided into several phases, each corresponding to an annotation defined in Build compatible extensions. Methods with these phase annotations are called back by the CDI runtime according to the CDI Bean initialization lifecycle.

• Discovery Phase

  • The phase in which the CDI runtime detects classes with Bean definition annotations such as @ApplicationScoped or @RequestScoped Bean
  • Called for methods with @Discovery, allowing you to add classes to be detected or add interceptor binding annotations

• Enhancement Phase

  • The phase in which annotations on detected classes may be changed
  • Called for methods with @Enhancement, allowing you to add or remove annotations on detected classes, fields, or methods

• Registration Phase

  • The phase in which detected classes are registered to the CDI container as CDI Beans, interceptors, or observers
  • Called for methods with @Registration, allowing you to perform processes you want to carry out when specified classes are registered to the CDI container

• Synthesis Phase

  • The phase in which synthetic Beans and observers are dynamically defined and registered
  • Called for methods with @Synthesis, allowing you to dynamically define and register Beans and observers using the API of Build compatible extensions

• Validation Phase

  • The final phase to verify the processes of Build compatible extensions
  • Called for methods with @Validation, allowing you to verify the processes of Build compatible extensions and, if there are problems, fail the deployment process

Now that you understand the initialization phases and corresponding annotations of Build compatible extensions, let's see what the sample does in each phase.

In the Discovery phase, the following is done (relevant code reposted).

@Discovery
public void discoverFrameworkClasses(ScannedClasses scan) {
  log.info("*** execute Discovery ***");
  Config config = ConfigProvider.getConfig();
  config.getOptionalValue("sample.app.processer.class", String[].class) ...(1)
        .ifPresent(values -> Stream.of(values).forEach(scan::add));     ...(2)
}

1. Load the class names (FQCN) registered in the configuration file^[1] with the key sample.app.processer.class
2. Add the loaded class names as detected Bean classes using ScannedClasses#add(String). In the subsequent Enhancement phase, you can operate on the annotations of Bean classes detected in the Discovery phase.
   Classes with Bean definition annotations such as @ApplicationScoped or @RequestScoped are automatically detected as Bean classes, but other classes are not detected. Therefore, if you want to detect classes without Bean definition annotations as detection targets, add them as detection classes using ScannedClasses#add(String) in the Discovery phase as shown in the sample.
   Although the sample retrieves class names from the configuration file, this is not related to the specifications of Build compatible extensions. You can directly specify class names as string literals like "foo.bar.Baz" or use Foo.class.getName() without any problems.

In the Enhancement phase, the following is done (relevant code reposted).

@Enhancement(types = Processor.class, withSubtypes = true)         ...(1)
public void addInterceptorBindingToProcessors(ClassConfig clazz) { ...(2)
    log.info("*** execute Enhancement ***");
    clazz.addAnnotation(ApplicationScoped.class);                  ...(3)
    clazz.methods()
            .stream()
            .filter(it -> it.info().name().equals("doWork") && it.info().parameters().isEmpty())
            .forEach(it -> it.addAnnotation(Logged.class));        ...(4)
}

1. Specify the Bean class you want to process (operate on annotations) during the Enhancement phase using the types attribute. If you want to include subtypes as well as the matching class, set the withSubtypes attribute to true (default is false).
2. Callbacks are placed on classes from the detected classes in the Discovery phase that meet the conditions specified by the Enhancement annotation. In this example, since the types attribute specification is an interface, the applicable ones are the implementation classes, MyProcessor and AnotherProcessor, and the addInterceptorBindingToProcessors method with @Enhancement attached is called twice. At the time of the call, the class information of the call target is set and passed as ClassConfig.
3. Add the ApplicationScoped annotation to the class definition of the call target. This makes both the MyProcessor and AnotherProcessor classes managed as Application scope Beans.
4. Add the Logged annotation to the parameterless doWork method defined in the call target class. The Logged annotation is bound to LoggingInterceptor, so this annotation operation makes the doWork method call a target of LoggingInterceptor. The LoggingInterceptor is implemented as follows:

@Logged
@Interceptor
@Priority(Interceptor.Priority.APPLICATION)
public class LoggingInterceptor {
    private static final Logger log = LoggerFactory.getLogger(LoggingInterceptor.class);
    @Inject
    ImportantClassChecker importance;
    @AroundInvoke
    public Object intercept(InvocationContext ctx) throws Exception {
        Class<?> clazz = ctx.getMethod().getDeclaringClass();
        Level level = importance.isImportant(clazz) ? Level.WARN : Level.INFO;
        try {
            log.atLevel(level).setMessage("Starting work").log();
            return ctx.proceed();
        } finally {
            log.atLevel(level).setMessage("Work finished").log();
        }
    }
}

In the Registration phase, the following is done (relevant code reposted).

@Registration(types = Processor.class)          ...(1)
public void rememberProcessors(BeanInfo bean) { ...(2)
    log.info("*** execute Registration ***");
    if (bean.isClassBean()) {
        processors.add(bean.declaringClass());  ...(3)
    }
}

1. Specify the Bean class you want to monitor for registration to the CDI container using the types attribute. Like the Enhancement phase, callbacks are placed on the matching types specified by the Registration annotation. In this sample, the applicable ones are the MyProcessor and AnotherProcessor classes.
2. The CDI Bean information that is the target of the callback is set and called with the BeanInfo argument.
3. In this sample, to check the Processor Bean classes with @Important in the subsequent Synthesis phase, the information (ClassInfo) of the Processor type Bean classes is stored in a field Set. Note that the BuildCompatibleExtension instance is guaranteed by the CDI container to be one per implementation class.

In the Synthesis phase, the following is done (relevant code reposted).

@Synthesis
public void registerImportanceImpl(SyntheticComponents synth) {
    log.info("*** execute Synthesis ***");
    String[] importantProcessors = processors.stream()
            .filter(it -> it.hasAnnotation(Important.class))
            .map(ClassInfo::name)
            .toArray(String[]::new); ...(1)

    synth.addBean(ImportantClassCheckerImpl.class)                 ...(2)
            .type(ImportantClassChecker.class)                     ...(3)
            .withParam("importantProcessors", importantProcessors) ...(4)
            .createWith(ImportantClassCheckerCreator.class);       ...(5)
}

,1. Create an array of class names from the Processor type Bean classes collected in the Registration phase that have the @Important class annotation.
2. Create a synthetic Bean with ImportantClassCheckerImpl as the Bean class.
3. Add the ImportantClassChecker interface as a type the synthetic Bean possesses. The type of a Bean refers to the types that are injectable.
4. Specify the parameters to be passed when creating the synthetic Bean instance. The parameters specified here will be passed as arguments to the create method of the synthetic Bean creator class specified in the subsequent createWith method.
5. Specify the creator class (an implementation class of the SyntheticBeanCreator interface) for the synthetic Bean. The instance returned by the create method of the creator class will be managed by the CDI container according to its scope. In this sample, the scope is not explicitly specified, so it defaults to Dependent.

In the Validation phase, the following is done (relevant code reposted).

@Validation
public void validateProcessors(Messages msg) {
    log.info("*** execute Validation ***");
    if (processors.isEmpty()) {
        msg.error("At least one `Processor` implementation must exist"); ...(1)
    }
}

1. By calling the error method on the Message instance passed as an argument, you can fail the deployment process. The sample ensures that the deployment process fails if no Processor type Bean class is registered in the CDI container.

After seeing the implementation example, let's consider what Build compatible extensions ultimately are. In conclusion, Build compatible extensions can be said to achieve the following two points compared to Portable extensions:

• Realization of a simpler API for CDI extensions
• Shift-left of CDI initialization processing

The sample introduced in this article could also be implemented using Portable extensions, but frankly, the API of Portable extensions is complex (difficult).

For example, to simply make a class without a Bean definition annotation a CDI Bean, Portable extensions require the following implementation. Although it has few lines, the code is difficult to understand due to the discrepancy between what is being done and the methods being called.

public class SamplePortableExtension implements Extension {
    void addBean(@Observes BeforeBeanDiscovery event) {
        event.addAnnotatedType(SampleBean.class, "sampleBean");
    }
}

In contrast, Build compatible extensions can achieve this with the following concise implementation.

public class SampleBuildExtension implements BuildCompatibleExtension {
    @Discovery
    public void discovery(ScannedClasses scan) {
        scan.add(SampleBean.class.getName());
    }
}

Portable extensions not only have a complex API but also require deep knowledge of the CDI container lifecycle. Thus, Build compatible extensions have made it possible to implement CDI extensions that were previously difficult and complex with a simpler API.

Portable extensions use reflection to dynamically collect metadata of necessary objects. Therefore, the initialization process of Portable extensions had to be performed at startup when instances of Beans and others are created.

However, the main tasks performed in this CDI initialization process are:

1. Scanning of Bean definition annotations
2. Scanning of @Injection
3. Resolution of dependencies
4. Generation of proxy bytecode
5. Creation of Beans (instantiation)

Among these, tasks 1 to 4 always yield the same results. Additionally, since tasks 1 to 4 take time, they have been a factor in the slow startup of CDI containers.

The idea behind Build compatible extensions is whether the initialization tasks from 1 to 4, which are performed during startup, could instead be performed during the build time (compile time) of the application. Traditional Portable extensions used reflection, which, as previously mentioned, could only be performed at startup. Clearing this hurdle and allowing CDI extensions to be performed without reflection led to the development of Build compatible extensions^[4].

Comparing the timing of CDI initialization processing by traditional Portable extensions and Build compatible extensions side by side results in the following:

You can see that the CDI initialization processing has moved to the left. This is the shift-left of CDI initialization processing, which performs the same tasks at build time instead of startup time, thereby speeding up the application startup.

This article introduced only the necessary Build compatible extensions APIs to realize the sample, but there are many other arguments you can take in callback methods. Becoming proficient in using CDI extensions can greatly expand what you can do with CDI. I hope this article inspires you to explore further.