CDI Portable Extension and Flyway

1. Overview

In this tutorial, we’ll go over an interesting feature of CDI (Context and Dependency Injection) called CDI portable extension.

First, we’ll start by understanding how it works, and then we’ll see how to write an extension. We’ll go through the steps to implement a CDI integration module for Flyway, so we can run a database migration on startup of a CDI container.

This tutorial assumes a basic understanding of CDI. Have a look at this article for an introduction to CDI.

2. What Is a CDI Portable Extension?

A CDI portable extension is a mechanism by which we can implement additional functionalities on top of the CDI container. At the bootstrap time, the CDI container scans the classpath and creates metadata about the discovered classes.

During this scanning process, the CDI container fires many initialization events which can be only observed by extensions. This is where a CDI portable extension comes into play.

A CDI Portable extension observes these events and then modifies or adds information to the metadata created by the container.

3. Maven Dependencies

Let’s start by adding the required dependency for the CDI API in the pom.xml. It’s sufficient for implementing an empty extension.

<dependency>
    <groupId>javax.enterprise</groupId>
    <artifactId>cdi-api</artifactId>
    <version>2.0.SP1</version>
</dependency>

And for running the application, we can use any compliant CDI implementation. In this article, we’ll use the Weld implementation.

<dependency>
    <groupId>org.jboss.weld.se</groupId>
    <artifactId>weld-se-core</artifactId>
    <version>3.0.5.Final</version>
    <scope>runtime</scope>
</dependency>

You can check if any new versions of the API and the implementation have been released at Maven Central.

4. Running Flyway in a Non-CDI Environment

Before we start integrating Flyway and CDI, we should look first at how to run it in a non-CDI context.

So let’s take a look at the following example taken from the official site of Flyway:

DataSource dataSource = //...
Flyway flyway = new Flyway();
flyway.setDataSource(dataSource);
flyway.migrate();

As we can see, we’re only using a Flyway instance which needs a DataSource instance.

Our CDI portable extension will later produce the Flyway and Datasource beans. For the purpose of this sample, we’ll use an embedded H2 database and we’ll provide DataSource properties through the DataSourceDefinition annotation.

5. CDI Container Initialization Events

At the application bootstrap, the CDI container starts by loading and instantiating all CDI portable extensions. Then, in each extension, it searches and registers observer methods of initialization events if any. After that, it performs the following steps:

1. Fires BeforeBeanDiscovery event before the scanning process begins
2. Performs the type discovery in which it scans archive beans, and for each discovered type it fires the ProcessAnnotatedType event
3. Fires the AfterTypeDiscovery event
4. Performs the bean discovery
5. Fires the AfterBeanDiscovery event
6. Performs bean validation and detect definition errors
7. Fires the AfterDeploymentValidation event

The intention of a CDI portable extension is then to observe these events, check metadata about the discovered beans, modify this metadata or add to it.

In a CDI portable extension, we can only observe these events.

6. Writing the CDI Portable Extension

Let’s see how we can hook into some of these events by building our own CDI portable extension.

6.1. Implementing the SPI Provider

A CDI portable extension is a Java SPI provider of the interface javax.enterprise.inject.spi.Extension. Have a look at this article for an introduction to Java SPI.

First, we start by providing the Extension implementation. Later, we’ll add observer methods to the CDI container bootstrap events:

public class FlywayExtension implements Extension {
}

Then, we add a file name META-INF/services/javax.enterprise.inject.spi.Extension with this content:

com.baeldung.cdi.extension.FlywayExtension

As an SPI, this Extension is loaded before the container bootstrap. So observer methods on the CDI bootstrap events can be registered.

6.2. Defining Observer Methods of Initialization Events

In this example, we make the Flyway class known to the CDI container before the scanning process begins. This is done in the registerFlywayType() observer method:

public void registerFlywayType(
  @Observes BeforeBeanDiscovery bbdEvent) {
    bbdEvent.addAnnotatedType(
      Flyway.class, Flyway.class.getName());
}

Here, we have added metadata about the Flyway class. From now on, it’ll behave as if it was scanned by the container. For this purpose, we have used the addAnnotatedType() method.

Next, we’ll observe the ProcessAnnotatedType event to make the Flyway class as a CDI managed bean:

public void processAnnotatedType(@Observes ProcessAnnotatedType<Flyway> patEvent) {
    patEvent.configureAnnotatedType()
      .add(ApplicationScoped.Literal.INSTANCE)
      .add(new AnnotationLiteral<FlywayType>() {})
      .filterMethods(annotatedMethod -> {
          return annotatedMethod.getParameters().size() == 1
            && annotatedMethod.getParameters().get(0).getBaseType()
              .equals(javax.sql.DataSource.class);
      }).findFirst().get().add(InjectLiteral.INSTANCE);
}

First, we annotate the Flyway class with @ApplicationScoped and @FlywayType annotations, then we search the Flyway.setDataSource(DataSource dataSource) method and we annotate it by @Inject.

The final result of the above operations have the same effect as if the container scans the following Flyway bean:

@ApplicationScoped
@FlywayType
public class Flyway {
 
    //...
    @Inject
    public void setDataSource(DataSource dataSource) {
      //...
    }
}

The next step is then to make a DataSource bean available for injection as our Flyway bean depends on a DataSource bean.

For that, we’ll process to register a DataSource Bean into the container and we’ll use the AfterBeanDiscovery event:

void afterBeanDiscovery(@Observes AfterBeanDiscovery abdEvent, BeanManager bm) {
    abdEvent.addBean()
      .types(javax.sql.DataSource.class, DataSource.class)
      .qualifiers(new AnnotationLiteral<Default>() {}, new AnnotationLiteral<Any>() {})
      .scope(ApplicationScoped.class)
      .name(DataSource.class.getName())
      .beanClass(DataSource.class)
      .createWith(creationalContext -> {
          DataSource instance = new DataSource();
          instance.setUrl(dataSourceDefinition.url());
          instance.setDriverClassName(dataSourceDefinition.className());
              return instance;
      });
}

As we can see, we need a DataSourceDefinition that provides the DataSource properties.

We can annotate any managed bean with the following annotation:

@DataSourceDefinition(
  name = "ds", 
  className = "org.h2.Driver", 
  url = "jdbc:h2:mem:testdb")

To extract these properties, we observe the ProcessAnnotatedType event along with the @WithAnnotations annotation:

public void detectDataSourceDefinition(
  @Observes @WithAnnotations(DataSourceDefinition.class) ProcessAnnotatedType<?> patEvent) {
    AnnotatedType at = patEvent.getAnnotatedType();
    dataSourceDefinition = at.getAnnotation(DataSourceDefinition.class);
}

And finally, we listen to the AfterDeployementValidation event to get the wanted Flyway bean from the CDI container and then invoke the migrate() method:

void runFlywayMigration(
  @Observes AfterDeploymentValidation adv, 
  BeanManager manager) {
    Flyway flyway = manager.createInstance()
      .select(Flyway.class, new AnnotationLiteral<FlywayType>() {}).get();
    flyway.migrate();
}

7. Conclusion

Building a CDI portable extension seems difficult at the first time, but once we understand the container initialization lifecycle and the SPI dedicated to extensions, it becomes a very powerful tool that we can use to build frameworks on top of Jakarta EE.

As usual, all the code samples shown in this article can be found over on GitHub.