jbonofre commented on code in PR #2135: URL: https://github.com/apache/karaf/pull/2135#discussion_r2763108552
########## 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 Review Comment: I kind of agree, but I think the proposed change is good enough. ########## 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. Review Comment: It can be addressed in another PR though. ########## 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 +3. If multiple features provide the same capability, it chooses one (typically the first available) Review Comment: Yes, the resolver will take the first feature. I would be "clearer" here. ########## 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 +3. If multiple features provide the same capability, it chooses one (typically the first available) +4. Conditional dependencies (with `dependency="true"`) are only installed if their capabilities are needed + +This enables automatic dependency resolution and prevents conflicts between alternative implementations. + +===== Conditional bundles and features + +The `<conditional>` element allows features to include bundles or other features only when specific conditions are met. + +**Feature-based conditions** + +Install content only when a specific feature is present: + +---- +<feature name="my-feature" version="1.0.0"> + <bundle>mvn:com.example/core-bundle/1.0.0</bundle> + <conditional> + <condition>webconsole</condition> + <bundle>mvn:com.example/webconsole-plugin/1.0.0</bundle> + </conditional> +</feature> +---- + +**Requirement-based conditions** + +Install content only when specific OSGi requirements are satisfied: Review Comment: Yes, and it's very important. That's actually a concern from some users: the runtime can have different behaviors depending of what is installed, so it's basically not predictable. That's one of the main reason of the "simple/flat resolver" that will be provided (optionally) in Karaf 4.5.0. ########## 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. Review Comment: Correct, it also works for `bundle`. -- 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]
