////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Conditional Extension Dependencies

include::./attributes.adoc[]

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:

[source,xml]
----
<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-bootstrap-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.

NOTE: 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:

[source,xml]
----
<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`

IMPORTANT: 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.

[source,xml]
----
<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.

IMPORTANT: 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:

[source,xml]
----
<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-bootstrap-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`.
