Conditional Extension Dependencies

Quarkus extension dependencies are usually configured in the same way as any other project dependencies in the project’s build file, e.g. the Maven pom.xml or the Gradle build scripts. However, there are dependency types that aren’t yet supported out-of-the-box by Maven and Gradle. What we refer here to as "conditional dependencies" is one example.

Conditional Dependencies

The idea behind the notion of the conditional dependency is that such a dependency must be activated only if a certain condition is satisfied. If the condition is not satisfied then the dependency must not be activated. In that regard, conditional dependencies can be categorized as optional, i.e. they may or may not appear in the resulting set of project dependencies.

In which cases could conditional dependencies be useful? A typical example would be a component that should be activated only in case all of its required dependencies are available. If one or more of the component’s required dependencies aren’t available, instead of failing, the component should simply not be activated.

Quarkus Conditional Extension Dependencies

Quarkus supports conditional extension dependencies. I.e. one Quarkus extension may declare one or more conditional dependencies on other Quarkus extensions. Conditional dependencies on and from non-extension artifacts aren’t supported.

Let’s take the following scenario as an example: quarkus-extension-a has an optional dependency on quarkus-extension-b which should be included in a Quarkus application only if quarkus-extension-c is found among its dependencies (direct or transitive). In other words, the presence of quarkus-extension-c is the condition which, if satisfied, enables quarkus-extension-b during the build of a Quarkus application.

The condition which triggers activation of an extension is configured in the extension’s descriptor, which is included into the runtime artifact of the extension as META-INF/quarkus-extension.properties. Given that extension descriptor is generated by the Quarkus plugin at extension build time, extension developers can add the following configuration to express the condition which would have to be satisfied for the extension to be activated:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-b</artifactId> (1)

  <!-- SKIPPED CONTENT -->

  <build>
    <plugins>
      <plugin>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-extension-maven-plugin</artifactId>
        <version>${quarkus.version}</version>
        <executions>
          <execution>
            <phase>process-resources</phase>
            <goals>
              <goal>extension-descriptor</goal> (2)
            </goals>
            <configuration>
              <dependencyCondition> (3)
                <artifact>org.acme:quarkus-extension-c</artifact> (4)
              </dependencyCondition>
            </configuration>
          </execution>
        </executions>
      </plugin>

  <!-- SKIPPED CONTENT -->

1	runtime Quarkus extension artifact ID, in our example `quarkus-extension-b`;
2	the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with;
3	configuration of the condition which will have to be satisfied for this extension to be included into a Quarkus application expressed as a list of artifacts that must be present among the application dependencies;
4	an artifact key (in the format of `groupId:artifactId[:<classifier>:<extension>]` but typically simply `<groupId>:<artifactId>`) of the artifact that must be present among the application dependencies for the condition to be satisfied.

In the example above the artifact used in the condition configuration happens to be a runtime Quarkus extension artifact but it could as well be any other artifact. There could also be more than one artifact element in the body of dependencyCondition.

Now, having a dependency activating condition in the descriptor of quarkus-extension-b, other extensions may declare a conditional dependency on it.

A conditional dependency is configured in the runtime artifact of a Quarkus extension. In our example, it’s the quarkus-extension-a that has a conditional dependency on quarkus-extension-b, which can be expressed in two ways.

Declaring a dependency as `optional`

If an extension was configured with a dependency condition in its descriptor, other extensions may configure a conditional dependency on it by simply adding <optional>true</optional> to the dependency configuration. In our example it would look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a</artifactId> (1)

  <!-- SKIPPED CONTENT -->

  <dependencies>
    <dependency>
      <groupId>org.acme</groupId>
      <artifactId>quarkus-extension-b</artifactId> (2)
      <optional>true</optional>
    </dependency>

  <!-- SKIPPED CONTENT -->

1	the runtime extension artifact `quarkus-extension-a`
2	declares an optional Maven dependency on the runtime extension artifact `quarkus-extension-b`

In general, for every runtime extension artifact dependency on another runtime extension artifact there must be a corresponding deployment extension artifact dependency on the other deployment extension artifact. And if the runtime dependency is declared as optional then the corresponding deployment dependency must also be configured as optional.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a-deployment</artifactId> (1)

  <!-- SKIPPED CONTENT -->

  <dependencies>
    <dependency>
      <groupId>org.acme</groupId>
      <artifactId>quarkus-extension-b-deployment</artifactId> (2)
      <optional>true</optional>
    </dependency>

  <!-- SKIPPED CONTENT -->

1	the deployment extension artifact `quarkus-extension-a-deployment`
2	declares an optional Maven dependency on the deployment extension artifact `quarkus-extension-b-deployment`

Normally, optional Maven extension dependencies are ignored by the Quarkus dependency resolver at build time. In this case though, the optional dependency quarkus-extension-b includes a dependency condition in its extension descriptor, which turns this optional Maven dependency into a Quarkus conditional extension dependency.

If quarkus-extension-b wasn’t declared as <optional>true</optional> that would make quarkus-extension-b a required dependency of quarkus-extension-a and its dependency condition would be ignored.

Declaring a conditional dependency in the Quarkus extension descriptor

Conditional dependencies can also be configured in the Quarkus extension descriptor. The conditional dependency configured above could be expressed in the extension descriptor of quarkus-extension-a as:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- SKIPPED CONTENT -->

  <artifactId>quarkus-extension-a</artifactId> (1)

  <!-- SKIPPED CONTENT -->

  <build>
    <plugins>
      <plugin>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-extension-maven-plugin</artifactId>
        <version>${quarkus.version}</version>
        <executions>
          <execution>
            <phase>process-resources</phase>
            <goals>
              <goal>extension-descriptor</goal> (2)
            </goals>
            <configuration>
              <conditionalDependencies> (3)
                <extension>org.acme:quarkus-extension-b:${b.version}</extension> (4)
              </conditionalDependencies>
            </configuration>
          </execution>
        </executions>
      </plugin>

  <!-- SKIPPED CONTENT -->

1	runtime Quarkus extension artifact ID, in our example `quarkus-extension-a`
2	the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with
3	conditional dependency configuration element
4	artifact coordinates of conditional dependencies on other extensions.

In this case, the Maven dependency is not at all required in the pom.xml.

Conditional Dependencies
Quarkus Conditional Extension Dependencies
- Declaring a dependency as optional
- Declaring a conditional dependency in the Quarkus extension descriptor

Conditional Extension Dependencies

Conditional Dependencies

Quarkus Conditional Extension Dependencies

Declaring a dependency as `optional`

Declaring a conditional dependency in the Quarkus extension descriptor

Related content

On the same topics

Conditional Extension Dependencies

Conditional Dependencies

Quarkus Conditional Extension Dependencies

Declaring a dependency as optional

Declaring a conditional dependency in the Quarkus extension descriptor

Related content

On the same topics

Declaring a dependency as `optional`