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