The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Dependencias de extensión condicional

Las dependencias de las extensiones de Quarkus normalmente se configuran de la misma manera que cualquier otra dependencia del proyecto en el archivo de construcción del proyecto, por ejemplo, en Maven pom.xml o en los scripts de construcción de Gradle. Sin embargo, hay tipos de dependencias que todavía no están soportadas por Maven y Gradle. Lo que aquí llamamos "dependencias condicionales" es un ejemplo.

Dependencias condicionales

La idea que subyace a la noción de dependencia condicional es que dicha dependencia debe activarse sólo si se cumple una determinada condición. Si la condición no se cumple, la dependencia no debe activarse. En este sentido, las relaciones condicionales pueden clasificarse como opcionales, es decir, pueden aparecer o no en el conjunto resultante de relaciones del proyecto.

¿En qué casos podrían ser útiles las dependencias condicionales? Un ejemplo típico sería un componente que debe activarse sólo en caso de que todas sus dependencias requeridas estén disponibles. Si una o más de las dependencias necesarias del componente no están disponibles, en lugar de fallar, el componente simplemente no debería activarse.

Dependencias de la extensión condicional de Quarkus

Quarkus admite las dependencias condicionales de las extensiones. Es decir, una extensión de Quarkus puede declarar una o más dependencias condicionales de otras extensiones de Quarkus. No se admiten dependencias condicionales en y desde artefactos que no sean extensiones.

Tomemos el siguiente escenario como ejemplo: quarkus-extension-a tiene una dependencia opcional de quarkus-extension-b que debe incluirse en una aplicación Quarkus sólo si quarkus-extension-c se encuentra entre sus dependencias (directas o transitivas). En otras palabras, la presencia de quarkus-extension-c es la condición que, si se cumple, habilita a quarkus-extension-b durante la construcción de una aplicación Quarkus.

La condición que desencadena la activación de una extensión se configura en el descriptor de la extensión, que se incluye en el artefacto de tiempo de ejecución de la extensión como META-INF/quarkus-extension.properties. Dado que el descriptor de la extensión es generado por el plugin de Quarkus en el momento de la construcción de la extensión, los desarrolladores de la extensión pueden añadir la siguiente configuración para expresar la condición que tendría que ser satisfecha para que la extensión sea activada:

<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 ID del artefacto de extensión de Quarkus en tiempo de ejecución, en nuestro ejemplo quarkus-extension-b;
2 el objetivo que genera el descriptor de extensión con el que debe configurarse cada proyecto de extensión en tiempo de ejecución de Quarkus;
3 configuración de la condición que tendrá que ser satisfecha para que esta extensión sea incluida en una aplicación Quarkus expresada como una lista de artefactos que deben estar presentes entre las dependencias de la aplicación;
4 una clave de artefacto (con el formato de groupId:artifactId[:<classifier>:<extension>], pero normalmente es simplemente <groupId>:<artifactId>) del artefacto que debe estar presente entre las dependencias de la aplicación para que se cumpla la condición.
En el ejemplo anterior, el artifact utilizado en la configuración de la condición resulta ser un artefacto de extensión de Quarkus en tiempo de ejecución, pero también podría ser cualquier otro artefacto. También podría haber más de un elemento artifact en el cuerpo de dependencyCondition.

Ahora, al tener una condición de activación de la dependencia en el descriptor de quarkus-extension-b, otras extensiones pueden declarar una dependencia condicional sobre ella.

Una dependencia condicional se configura en el artefacto de tiempo de ejecución de una extensión de Quarkus. En nuestro ejemplo, es el quarkus-extension-a el que tiene una dependencia condicional de quarkus-extension-b, que puede expresarse de dos maneras.

Declarar una dependencia como optional

Si una extensión fue configurada con una condición de dependencia en su descriptor, otras extensiones pueden configurar una dependencia condicional sobre ella simplemente añadiendo <optional>true</optional> a la configuración de la dependencia. En nuestro ejemplo se verí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 -->

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

  <!-- SKIPPED CONTENT -->
1 el artefacto de extensión en tiempo de ejecución quarkus-extension-a
2 declara una dependencia opcional de Maven del artefacto de extensión en tiempo de ejecución quarkus-extension-b
En general, para cada dependencia de un artefacto de extensión en tiempo de ejecución de otro artefacto de extensión en tiempo de ejecución debe haber una dependencia correspondiente de un artefacto de extensión de despliegue de otro artefacto de extensión de despliegue. Y si la dependencia de tiempo de ejecución se declara como opcional, entonces la dependencia de despliegue correspondiente también debe configurarse como opcional.
<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 el artefacto de extensión del despliegue quarkus-extension-a-deployment
2 declara una dependencia opcional de Maven en el artefacto de extensión del despliegue quarkus-extension-b-deployment

Normalmente, las dependencias opcionales de las extensiones de Maven son ignoradas por el resolvedor de dependencias de Quarkus en tiempo de construcción. Sin embargo, en este caso, la dependencia opcional quarkus-extension-b incluye una condición de dependencia en su descriptor de extensión, que convierte esta dependencia opcional de Maven en una dependencia de extensión condicional de Quarkus.

Si quarkus-extension-b no fuera declarado como <optional>true</optional> eso haría que quarkus-extension-b fuera una dependencia requerida de quarkus-extension-a y su condición de dependencia sería ignorada.

Declarar una dependencia condicional en el descriptor de extensión de Quarkus

Las dependencias condicionales también pueden configurarse en el descriptor de la extensión de Quarkus. La dependencia condicional configurada anteriormente podría expresarse en el descriptor de extensión de quarkus-extension-a como:

<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 ID del artefacto de extensión de Quarkus en tiempo de ejecución, en nuestro ejemplo quarkus-extension-a
2 el objetivo que genera el descriptor de extensión con el que debe configurarse cada proyecto de extensión en tiempo de ejecución de Quarkus
3 elemento de configuración de dependencia condicional
4 coordenadas del artefacto de las dependencias condicionales de otras extensiones.

En este caso, la dependencia de Maven no es necesaria en absoluto en la página web pom.xml.