条件性扩展的依赖性
Quarkus extension dependencies are usually configured in the same way as any other project dependencies in a project’s build file, for example the Maven pom.xml or the Gradle build scripts. However, Quarkus also supports types of dependencies that aren’t supported out-of-the-box by Maven and Gradle. Conditional Quarkus extension dependencies is one such example.
Conditional Dependencies
A conditional dependency is a dependency that is activated only if a certain condition is satisfied. If the condition is not satisfied then the dependency will not be activated. In that regard, conditional dependencies can be categorized as optional, meaning they may or may not appear in the resulting dependency graph.
A typical example of a conditional dependency would be a component that should be added to the classpath only in case all of its required dependencies are present on the classpath. If one or more of the component’s required dependencies aren’t available, instead of failing, the component should simply not be added.
Conditional Quarkus Extension Dependencies
A Quarkus extension may declare one or more conditional dependencies on other Quarkus extensions or regular Maven artifacts.
Let’s consider 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 the application dependencies (direct or transitive). In this case, the presence of quarkus-extension-c is the condition, which, if satisfied, will trigger inclusion of the quarkus-extension-b when Quarkus application dependencies are resolved.
The condition which triggers activation of an extension is configured in the extension’s META-INF/quarkus-extension.properties, which is included in the runtime artifact of the extension. 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; |
| 2 | the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with; |
| 3 | configuration of the dependency condition which will have to be satisfied for this extension to be added to 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.
|
The dependencyCondition element may contain more than artifact, in which case all the configured artifacts must be present on the classpath for the condition to be satisfied.
Now, having a dependency condition recorded in the descriptor of the quarkus-extension-b, other extensions may declare a conditional dependency on it.
extensions with dependency conditions present in their metadata could still appear as regular dependencies in Maven pom.xml and Gradle build scripts, in which case their conditions will simply be ignored.
|
A conditional dependency is configured in the runtime artifact of a Quarkus extension. In this example, the quarkus-extension-a will declare a conditional dependency on the quarkus-extension-b, which can be done in the following two ways.
Declaring a dependency as optional
If an extension includes 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 |
Given that quarkus-extension-b includes a dependency condition, Quarkus will interpret an optional dependency on the quarkus-extension-b as conditional.
| In general, for every runtime extension artifact dependency on another runtime extension artifact there must be the 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 |
If the quarkus-extension-b dependency wasn’t declared as <optional>true</optional> it would make the quarkus-extension-b a required dependency of the quarkus-extension-a and its dependency condition would be ignored by the application dependency resolver.
|
Declaring a conditional dependency in the Quarkus extension descriptor
Conditional dependencies can also be configured in the Quarkus extension descriptor directly. Here is an example of how it can be done in the Quarkus extension plugin configuration of the quarkus-extension-a:
<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)
<artifact>org.acme:quarkus-extension-b:${b.version}</artifact> (4)
</conditionalDependencies>
</configuration>
</execution>
</executions>
</plugin>
<!-- SKIPPED CONTENT -->| 1 | the runtime Quarkus extension artifact ID; |
| 2 | the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with; |
| 3 | the conditional dependency configuration element; |
| 4 | the artifact coordinates of conditional dependencies on other extensions. |
In this case, the Maven dependency is not at all required in the pom.xml file.
Dev mode-only extension dependencies
Extensions can also declare conditional dependencies on other extensions using dev mode as the condition or one of the conditions for those dependencies to be activated.
Dev mode-only extension dependencies can be configured in the Quarkus extension plugin in the following way:
<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>
<conditionalDevDependencies> (3)
<artifact>org.acme:quarkus-extension-b:${b.version}</artifact> (4)
</conditionalDevDependencies>
</configuration>
</execution>
</executions>
</plugin>
<!-- SKIPPED CONTENT -->| 1 | the runtime Quarkus extension artifact ID; |
| 2 | the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with; |
| 3 | conditional dependencies that should be evaluated only in dev mode; |
| 4 | the artifact coordinates of a conditional dependency. |
The quarkus-extension-b, in this example, may or may not define its own condition to be evaluated.
If the quarkus-extension-b does not define a dependency condition on its own (there is no dependency condition recorded in its META-INF/quarkus-extension.properties), the quarkus-extension-b will only be added as a dependency of the quarkus-extension-a in dev mode but not in other modes (prod or test).
If the quarkus-extension-b does define a dependency condition on its own (a dependency condition recorded in its META-INF/quarkus-extension.properties), the quarkus-extension-b will be added as a dependency of the quarkus-extension-a in dev mode only if its condition is satisfied (the artifacts it requires are present in the application dependency graph).
Dev mode dependencies on regular Maven artifacts
Extensions may also declare conditional dependencies on regular Maven artifacts, that are not Quarkus extensions. Given that regular Maven artifacts do not include Quarkus metadata, the condition for their inclusion is configured by an extension depending on them.
For example
<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>
<conditionalDevDependencies> (3)
<artifact>org.acme:library-b:${b.version}</artifact> (4)
</conditionalDevDependencies>
</configuration>
</execution>
</executions>
</plugin>
<!-- SKIPPED CONTENT -->| 1 | the runtime Quarkus extension artifact ID; |
| 2 | the goal that generates the extension descriptor which every Quarkus runtime extension project should be configured with; |
| 3 | conditional dependencies that should be evaluated only in dev mode; |
| 4 | the artifact coordinates of a conditional dependency. |
In this example library-b is a regular Maven artifact that will be added as a dependency of the quarkus-extension-a only when an application is launched in dev mode.
