Improve provisioning documentation with optional dependencies and capabilities #2135
Conversation
…abilities - Added documentation for optional feature dependencies - Added capabilities and requirements explanation - Added conditional bundles and features section - Added comprehensive database service example - Added bundle refresh handling details - Fixed minor typo (Sometime → Sometimes)
| **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 |
There was a problem hiding this comment.
I think we want to provide examples of interoperability when version ranges are concerned.
Consider a feature with dependency=true and version=[1, 2) and another feature doing dependency=false version=1.0.1 .. and similar.
We really want to highlight how dependency=true makes interop with others easier.
| * **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. |
There was a problem hiding this comment.
hmm... I think it is also supported for <bundle>, right?
| </feature> | ||
| ---- | ||
|
|
||
| The requirement syntax can include OSGi filter expressions: |
There was a problem hiding this comment.
can we include a link to https://docs.osgi.org/specification/osgi.core/8.0.0/framework.module.html#framework.module.filtersyntax ?
| **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 |
There was a problem hiding this comment.
"any required capability is missing"
|
|
||
| 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) |
There was a problem hiding this comment.
"typically"? @jbonofre can we make firm statement it is the first (in what sense)?
|
|
||
| **Requirement-based conditions** | ||
|
|
||
| Install content only when specific OSGi requirements are satisfied: |
There was a problem hiding this comment.
related to above filter specification, we want to highlight this is a highly-dynamic mechanism, which can be dependent on runtime details, for example, when installing OS- or CPU-specific features as done in https://github.com/opendaylight/odlparent/blob/be317b379a316d5f298b2fb3e932247a2bc0de84/features/odl-netty-4/src/main/feature/template.xml#L15-L27
|
|
||
| During feature resolution and deployment, Karaf automatically detects bundles that need to be refreshed to ensure proper wiring and package resolution. This refresh mechanism is crucial for maintaining a consistent OSGi environment. | ||
|
|
||
| **When bundles are refreshed:** |
There was a problem hiding this comment.
I very much like this section, but in my experience users are flabbergasted by the various causes.
Can we perhaps include example messages logged in karaf.log when these happen? Perhaps in a 'Diagnosing causes of bundle refresh' section?
2 participants
This PR enhances the provisioning documentation with comprehensive coverage of:
These additions provide users with better understanding of advanced Karaf provisioning features.