Will my lib or framework work on Quarkus or GraalVM?

Quarkus extension

Unit of Quarkus distribution
- A Maven dep of a user app
Focus on some specific lib/framework/aspect

Two Maven modules

Build time module

my-ext-deployment

 
class MyExtProcessor {
  @BuildStep
  ... buildStep1(...) {...}

  @BuildStep
  ... buildStep2(...) {...}

  ...
}

Runtime module

my-ext

@Recorder
class MyExtRecorder {

  ... runtimeTask1(...) {...}


  ... runtimeTask2(...) {...}

  ...
}

class MyExtProcessor {

  /* BuildSteps typically produce BuildItems */
  @BuildStep
  NameBuildItem nameStep() {
    return new NameBuildItem("Joe");
  }

  /* BuildItems carry some payload */
  final class NameBuildItem extends SimpleBuildItem {
    final String name; /* The payload */
    ...
  }
}

class MyExtProcessor {

  /* BuildSteps may consume BuildItems */
  @BuildStep
  HelloBuildItem helloStep(NameBuildItem nameItem) {
    return new HelloBuildItem("Hello " + nameItem.getName());
  }

  @BuildStep
  NameBuildItem nameStep() {
    return new NameBuildItem("Joe");
  }
  /* helloStep depending on the nameStep
   * determines the execution order */
}

class MyExtProcessor {

  @BuildStep
  void helloStep(
        NameBuildItem nameItem,          /* BuildSteps may consume*/
        GreetingBuildItem greetingItem,  /* multiple BuildItems */
        /* Results can also be published via BuildProducers */
        BuildProducer<HelloBuildItem> helloProducer,
        BuildProducer<FooBuildItem> fooProducer) {

    /* BuildSteps may produce multiple BuildItems */
    helloProducer.produce(
        new HelloBuildItem(
            greetingItem.getGreeting() + " " + nameItem.getName());

    fooProducer.produce(new FooBuildItem());
  }
}

A common `@BuildStep`:

Find classes having some annotation
Register them for reflection

Jandex

A Java annotation indexer
and offline reflection library.

Used by @BuildSteps
to inspect the application code

https://github.com/wildfly/jandex

class JacksonProcessor {
  @BuildStep
  void registerDeserializers(
        CombinedIndexBuildItem combinedIndex, /* Pass the Jandex */
        BuildProducer<ReflectiveClassBuildItem> reflProducer) {

    DotName JSON_DESERIALIZE =
        DotName.createSimple(JsonDeserialize.class.getName());
    for (AnnotationInstance annot    /* Query for the annotations */
        : combinedIndex.getIndex().getAnnotations(JSON_DESERIALIZE)) {
      /* Do some filtering */
      AnnotationTarget annotTarget = annot.target();
      if (CLASS.equals(annotTarget.kind())) {
        DotName dotName = annotTarget.asClass().name();
        Type jandexType = Type.create(dotName, Type.Kind.CLASS);
        /* ... and finally register the type for reflextion */
        reflProducer.produce(new ReflectiveClassBuildItem(jandexType));
}}}}

Code Adapted from the Jackson Extension

More Jandex usecases

Find classes/fields/methods having some annotation
Find classes implementing an interface
Find subclasses of a class
List fields, methods and constructors of a class

Build time module

my-ext-deployment

 
class MyExtProcessor {
  @BuildStep
  ... buildStep1(...) {...}

  @BuildStep
  ... buildStep2(...) {...}

  ...
}

Runtime module

my-ext

@Recorder
class MyExtRecorder {

  ... runtimeTask1(...) {...}


  ... runtimeTask2(...) {...}

  ...
}

class CamelProcessor {
  @Record(ExecutionTime.STATIC_INIT)  /*    @Recorders can be injected  */
  @BuildStep                          /* ⮦ as BuildStep method params  */
  CamelContextBuildItem context(CamelRecorder recorder) {
    RuntimeValue<CamelContext> context = recorder.createContext();
    return new CamelContextBuildItem(context);  /* ⮤ @BuildStep methods */
  }/* ⮤ The RuntimeValue can be dispatched */   /*   can invoke        */
}  /*  to other @BuildSteps via a BuildItem */   /*   @Recorder methods */

@Recorder
public class CamelRecorder {
  public RuntimeValue<CamelContext> createContext() {
           /* ⮤ A handle to pass values between recorders */
    FastCamelContext context = new FastCamelContext();
    return new RuntimeValue<>(context);
}}

Code Adapted from the Apache Camel Quarkus

Extensions may depend on each other

E.g. mp-metrics extension
depends on
camel-quarkus-core

so it can consume the CamelContextBuildItem and adjust the CamelContext as needed

class MpMetricsProcessor {
  @Record(ExecutionTime.STATIC_INIT)
  @BuildStep
  public void configureCamelContext(
        MpMetricsRecorder recorder,
        CamelContextBuildItem ctxItem) {
    recorder.configureCamelContext(ctxItem.getCamelContext());
}}

@Recorder
public class MpMetricsRecorder {
  public void configureCamelContext(RuntimeValue<CamelContext> ctxVal) {
               /* Unwrap the RuntimeValue ⮧ */
    CamelContext camelContext = ctxVal.getValue();
    /* ... and configure it as needed */
    ManagementStrategy strategy = camelContext.getManagementStrategy();
    strategy.addEventNotifier(new MpMetricsCamelContextEventNotifier());
}}

Code Adapted from the Apache Camel Quarkus

Resulting application bootstrap code:

class GeneratedMain { /* bytecode in reality, pseudocode here */
  static { /* Chunks recorded with @Record(ExecutionTime.STATIC_INIT) */
    CamelRecorder camelRecorder = new CamelRecorder();
    RuntimeValue<CamelContext> val1 = camelRecorder.createContext();
    /* The order of the calls is given by
     * the dependencies between the @BuildSteps */
    MpMetricsRecorder mpMetricsRecorder = new MpMetricsRecorder();
    mpMetricsRecorder.configureCamelContext(val1);
  }

  public static main(String[] args) {
    /* Chunks recorded with @Record(ExecutionTime.RUNTIME_INIT) */
    new VertxRecorder().openSocket(); /* can't do this in static init */
}}

Mostly used `BuildItems`

ReflectiveClassBuildItem
register classes for reflection in the native mode
AdditionalBeanBuildItem, BeanDefiningAnnotationBuildItem
bean classes the CDI container should analyze
ExtensionSslNativeSupportBuildItem
turn on SSL in the native mode
CombinedIndexBuildItem, ApplicationIndexBuildItem
offline reflection and annotation index (Jandex)
NativeImageResourceBuildItem
src/main/resources and resources from JARs not included by default in the native image

List of BuildItems provided by Quarkus

Extension configuration

Extensions may expose their configuration through annotated POJOs
These may come in three flavors:
- BUILD_TIME
- BUILD_AND_RUN_TIME_FIXED
- RUN_TIME

Config POJO

@ConfigRoot(name = "camel", phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
public class CamelConfig {

    @ConfigItem
    public MainConfig main;

    @ConfigGroup
    public static class MainConfig {
        @ConfigItem(defaultValue = "true")
        public boolean enabled;
        /* This option can be set in application.properties via
         *
         *   camel.main.enabled = true
         *
         */
    }
}

Code Adapted from the Apache Camel Quarkus

Config in `@BuildSteps`

class CamelProcessor {
  @BuildStep
  ... discoverRoutesBuilderClassNames(CamelConfig config, ...) {
    if (config.main.enabled) {
        /* Do something */
    }
  }
}

Code Adapted from the Apache Camel Quarkus

Config in `@Recorders`

@Recorder
public class MyRecorder {
  void record(CamelConfig camelConfig) {

    if (camelConfig.main.enabled) {
      /* Do something */
    }

    /* Same effect using
     * org.eclipse.microprofile.config.ConfigProvider */
    if (ConfigProvider.getConfig()
        .getValue("camel.main.enabled", Boolean.class)) {
      /* Do something */
    }
}}

Code Adapted from the Apache Camel Quarkus

Substitutions

Provided by GraalVM
For replacing classes in the native image

Substitutions usecases

Last resort for fixing third party code
- E.g. avoid opening a socket, starting a Thread, etc. in a static initializer
Cut off uneeded code (and its dependencies)
- E.g. parsing an XML config that is not supported on Quarkus

A substitution example

(1/2)

/* The original class (simplified) */
package com.mysql.cj.jdbc;
public class AbandonedConnectionCleanupThread implements Runnable {
  private static final ExecutorService cleanupThreadExcecutorService;
  private static Thread threadRef = null;

  static {
    cleanupThreadExcecutorService =
        Executors.newSingleThreadExecutor(r -> { ... });
    /* GraalVM does not like threads being started in a static block */
    cleanupThreadExcecutorService.execute(
        new AbandonedConnectionCleanupThread());
  }
  ...
}

Code Adapted from the MySQL JDBC driver

A substitution example

(2/2)

@Substitute /* The substitution class */
@TargetClass(AbandonedConnectionCleanupThread.class)
final public class AbandonedConnectionCleanupThread_disable {

  /* No static initializer here */

  @Substitute
  protected static void trackConnection(
      MysqlConnection conn, NetworkResources io) {
      /* A no-op method */
  }
}

Code Adapted from the MySQL JDBC extension

Standards	Databases	3rd party libs/frameworks
Java EE (JPA, CDI, JTA, ...) MicroProfile (Health, Metrics, ...) Spring (via compatibility layers)	PostgreSQL, MySQL MSSQL, H2 FlyWay, Amazon DynamoDB MongoDB, Neo4j	Netty, Vert.x Camel, Infinispan, Kogito ...