rovarga commented on code in PR #2135: URL: https://github.com/apache/karaf/pull/2135#discussion_r2467142017
########## manual/src/main/asciidoc/user-guide/provisioning.adoc: ########## @@ -406,6 +408,229 @@ A prerequisite feature is a special kind of dependency. If you add the `prerequi } ---- +[[optional-feature-dependencies]] +===== Optional feature dependencies + +A feature dependency can be marked as optional using the `dependency="true"` attribute. This creates a flexible dependency mechanism where the feature dependency is only installed if it's actually needed. + +---- +<feature name="my-feature" version="1.0.0"> + <feature dependency="true">optional-feature</feature> + <requirement>some-capability</requirement> +</feature> +---- + +**How optional dependencies work:** + +* **Default behavior** (without `dependency="true"`): The feature dependency is always installed +* **Optional behavior** (with `dependency="true"`): The feature dependency is only installed if the required capabilities are not already provided by the system + +This mechanism enables: +* **Alternative implementations**: Multiple features can provide the same capability, and only one will be installed +* **Conflict avoidance**: Prevents multiple implementations of the same service from being installed simultaneously +* **Flexible deployment**: Features can work with different providers without modification + +**Note**: While the `dependency="true"` attribute is supported for feature dependencies, the current Karaf standard features primarily use this pattern for bundle dependencies. Feature-level optional dependencies are more commonly used in custom feature definitions where alternative implementations need to be selected at deployment time. + +===== Capabilities and requirements + +Features can declare what they provide (capabilities) and what they need (requirements). This enables the feature resolver to automatically install the right dependencies and avoid conflicts. + +**Capabilities** + +A capability declares what a feature provides to the system: + +---- +<feature name="http-provider" version="1.0.0"> + <bundle>mvn:com.example/http-bundle/1.0.0</bundle> + <capability>http-service;provider:=my-http</capability> +</feature> +---- + +The capability syntax is: `namespace;attribute1:=value1;attribute2:=value2` + +**Requirements** + +A requirement declares what a feature needs from the system: + +---- +<feature name="web-app" version="1.0.0"> + <requirement>http-service</requirement> + <bundle>mvn:com.example/web-bundle/1.0.0</bundle> +</feature> +---- + +The requirement syntax can include OSGi filter expressions: + +---- +<requirement>osgi.ee;filter:="(&(osgi.ee=JavaSE)(!(version>=1.8)))"</requirement> +---- + +**How the resolver works:** + +1. When a feature with requirements is installed, the resolver checks if the required capabilities are already available +2. If capabilities are missing, it looks for features that provide them Review Comment: "any required capability is missing" -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
