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

Capacidades de ampliación

Las extensiones de Quarkus pueden proporcionar ciertas capacidades y requerir que otras extensiones proporcionen ciertas capacidades en una aplicación para funcionar correctamente.

Una capacidad representa un aspecto técnico, por ejemplo, puede ser una implementación de alguna funcionalidad, un contrato o una especificación. Cada capacidad tiene un nombre que debe seguir la convención de nomenclatura de paquetes de Java, por ejemplo, io.quarkus.rest.

Las promesas de capacidad y los requisitos se describen en los descriptores de extensión de Quarkus - META-INF/quarkus-extension.properties entradas de los artefactos JAR de la extensión en tiempo de ejecución.

Sólo se permite un único proveedor de cualquier capacidad en una aplicación. Si se detecta más de un proveedor de una capacidad, la compilación de la aplicación fallará con el mensaje de error correspondiente.

Si una extensión requiere una determinada capacidad, debe haber otra entre las dependencias de la aplicación que proporcione esa capacidad, de lo contrario la construcción fallará con el correspondiente mensaje de error.

En el momento de la compilación, todas las capacidades encontradas en la aplicación se agregarán en una instancia del elemento de compilación io.quarkus.deployment.Capabilities que los pasos de compilación de extensión pueden inyectar para comprobar si una determinada capacidad está disponible o no.

Declarar las capacidades

The quarkus-extension-maven-plugin:extension-descriptor Maven goal and the extensionDescriptor Gradle task, that generate extension descriptors, allow configuring provided and required capabilities in the following way:

Maven
<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-extension-maven-plugin</artifactId>
    <configuration>
        <capabilities>
            <provides>io.quarkus.hibernate.orm</provides> (1)
            <requires>io.quarkus.agroal</requires> (2)
        </capabilities>
    </configuration>
</plugin>
1 la extensión proporciona la capacidad de io.quarkus.hibernate.orm (se permiten múltiples elementos de provides )
2 la extensión requiere que se proporcione la capacidad de io.quarkus.agroal para funcionar correctamente (se permiten múltiples elementos de requires )
Gradle (Groovy DSL)
quarkusExtension {
    capabilities {
        provides 'io.quarkus.rest' (1)
        requires 'io.quarkus.resteasy' (2)
    }
}
1 la extensión proporciona la capacidad de io.quarkus.hibernate.orm (se permiten múltiples elementos de provides )
2 la extensión requiere que se proporcione la capacidad de io.quarkus.agroal para funcionar correctamente (se permiten múltiples elementos de requires )
El plugin de extensión de Gradle es todavía experimental y puede cambiar en el futuro.
Gradle (DSL de Kotlin)
quarkusExtension {
    capabilities {
        provides("io.quarkus.rest") (1)
        requires("io.quarkus.resteasy") (2)
    }
}
1 la extensión proporciona la capacidad de io.quarkus.hibernate.orm (se permiten múltiples elementos de provides )
2 la extensión requiere que se proporcione la capacidad de io.quarkus.agroal para funcionar correctamente (se permiten múltiples elementos de requires )
El plugin de extensión de Gradle es todavía experimental y puede cambiar en el futuro.

Promesas y requisitos de capacidad condicionales

Una capacidad puede ser proporcionada o requerida sólo si se cumple una determinada condición, por ejemplo, si una determinada opción de configuración está habilitada o en base a alguna otra condición. Así es como se puede configurar una promesa de capacidad condicional:

Maven
<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-extension-maven-plugin</artifactId>
    <configuration>
        <capabilities>
            <providesIf> (1)
                <positive>io.quarkus.container.image.openshift.deployment.OpenshiftBuild</positive> (2)
                <name>io.quarkus.container.image.openshift</name> (3)
            </providesIf>
        </capabilities>
    </configuration>
</plugin>
1 declaración de una capacidad condicional
2 que debe ser resuelta en true por una clase que implemente java.util.function.BooleanSupplier
3 nombre de la capacidad proporcionada
providesIf permite listar múltiples elementos <positive> así como <negative>.

También se admite el elemento correspondiente requiresIf.

Gradle (Groovy DSL)
quarkusExtension {
    capabilities {
        provides 'io.quarkus.container.image.openshift' onlyIf ['io.quarkus.container.image.openshift.deployment.OpenshiftBuild'] (1)
    }
}
1 que debe ser resuelta en true por una clase que implemente java.util.function.BooleanSupplier
También es posible especificar las condiciones de onlyIfNot. También se pueden establecer condiciones para las capacidades requeridas.
Gradle (DSL de Kotlin)
quarkusExtension {
    capabilities {
        provides("io.quarkus.container.image.openshift").onlyIf(["io.quarkus.container.image.openshift.deployment.OpenshiftBuild"]) (1)
    }
}
1 que debe ser resuelta en true por una clase que implemente java.util.function.BooleanSupplier
También es posible especificar las condiciones de onlyIfNot. . También se pueden establecer condiciones para las capacidades requeridas.

En este caso, io.quarkus.container.image.openshift.deployment.OpenshiftBuild debe incluirse en una de las dependencias de despliegue de la extensión e implementar java.util.function.BooleanSupplier. En el momento de la construcción, el bootstrap de Quarkus creará una instancia de la misma y registrará la capacidad de io.quarkus.container.image.openshift sólo si su método getAsBoolean() devuelve true.

Una aplicación de la OpenshiftBuild podría tener el siguiente aspecto:

import java.util.function.BooleanSupplier;

import io.quarkus.container.image.deployment.ContainerImageConfig;

public class OpenshiftBuild implements BooleanSupplier {

    private ContainerImageConfig containerImageConfig;

    OpenshiftBuild(ContainerImageConfig containerImageConfig) {
        this.containerImageConfig = containerImageConfig;
    }

    @Override
    public boolean getAsBoolean() {
        return containerImageConfig.builder.map(b -> b.equals(OpenshiftProcessor.OPENSHIFT)).orElse(true);
    }
}

CapabilityBuildItem

Cada capacidad proporcionada se representará con una instancia de io.quarkus.deployment.builditem.CapabilityBuildItem en el momento de la construcción. Teóricamente, los `CapabilityBuildItem’s podrían ser producidos por los pasos de construcción de la extensión directamente, pasando por alto la declaración correspondiente en los descriptores de la extensión. Sin embargo, esta forma de proporcionar capacidades debería evitarse, a menos que haya una muy buena razón para no declarar una capacidad en el descriptor.

Las capacidades producidas por los pasos de construcción de extensiones no están disponibles para las herramientas de desarrollo de Quarkus. Como consecuencia, dichas capacidades no pueden tenerse en cuenta al analizar la compatibilidad de las extensiones durante la creación del proyecto o al añadir nuevas extensiones a un proyecto.

Capacidades de consulta

Todas las capacidades encontradas en una aplicación serán agregadas durante la construcción en una instancia de io.quarkus.deployment.Capabilities build item, que puede ser inyectada por los pasos de construcción de la extensión para comprobar si una determinada capacidad está presente o no. E.j.

    @BuildStep
    HealthBuildItem addHealthCheck(Capabilities capabilities, DataSourcesBuildTimeConfig dataSourcesBuildTimeConfig) {
        if (capabilities.isPresent(Capability.SMALLRYE_HEALTH)) {
            return new HealthBuildItem("io.quarkus.agroal.runtime.health.DataSourceHealthCheck",
                    dataSourcesBuildTimeConfig.healthEnabled);
        } else {
            return null;
        }
    }

Prefijos de capacidad

Al igual que un nombre de capacidad, un prefijo de capacidad es una cadena separada por puntos que se compone del primer elemento de nombre de capacidad o de una secuencia separada por puntos de los elementos de nombre de capacidad empezando por el primero. Por ejemplo, para la capacidad io.quarkus.resteasy.json.jackson se registrarán los siguientes prefijos:

  • io

  • io.quarkus

  • io.quarkus.resteasy

  • io.quarkus.resteasy.json

Capabilities.isCapabilityWithPrefixPresent(prefix) podría utilizarse para comprobar si una capacidad con un prefijo determinado está presente.

Dado que en una aplicación sólo se permite un único proveedor de una determinada capacidad, los prefijos de capacidad permiten expresar un cierto aspecto común entre capacidades diferentes pero algo relacionadas. Por ejemplo, puede haber extensiones que proporcionen las siguientes capacidades:

  • io.quarkus.resteasy.json.jackson

  • io.quarkus.resteasy.json.jackson.client

  • io.quarkus.resteasy.json.jsonb

  • io.quarkus.resteasy.json.jsonb.client

La inclusión de cualquiera de estas extensiones en una aplicación habilitará el serializador JSON de RESTEasy. En caso de que un paso de compilación necesite comprobar si el serializador JSON de RESTEasy ya está habilitado en una aplicación, en lugar de comprobar si está presente alguna de esas capacidades, podría simplemente comprobar si está presente una extensión con el prefijo io.quarkus.resteasy.json.

Related content