Implement OSGi R8 Retention Policy specification

[Copilot]

Implements the Retention Policy feature from the OSGi R8 Declarative Services specification (https://docs.osgi.org/specification/osgi.cmpn/8.0.0/service.component.html#service.component-retention.policy).

Note: The Satisfying Condition feature was already merged upstream and is no longer part of this PR.

Changes

Retention Policy Implementation

Implements the <retention-policy> element that controls whether component instances are retained when their use count drops to zero:

• XmlConstants.java: Added EL_RETENTION_POLICY element constant and RETENTION_POLICY_RETAIN/DISCARD value constants
• XmlHandler.java: Added parsing for <retention-policy> element
  • Maps "retain" to setDelayedKeepInstances(true) - keeps instances when use count is zero
  • Maps "discard" to setDelayedKeepInstances(false) - disposes instances when use count is zero (default)
  • Includes validation with warnings for invalid values
• XmlHandlerTest.java: Added unit tests for both "retain" and "discard" values
• Test resources: Created test XML files for retention policy validation
• README.md: Added comprehensive "Retention Policy (OSGi R8)" documentation section explaining:
  • Problem statement: expensive components/caches had no lifecycle control when use count dropped to zero
  • Usage examples for both "retain" and "discard" values
  • Use cases (expensive initialization, caches, event handlers, utility services)
  • Compatibility note about existing Felix delayedKeepInstances extension
  • Link to OSGi 8.0.0 specification
• changelog.txt: Documented retention policy implementation in version 2.2.15

Retention Policy Examples

Retain component instances (prevent disposal when not in use):

<scr:component name="expensive.cache.component" xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.example.ExpensiveCacheComponent"/>
    <retention-policy>retain</retention-policy>
</scr:component>

Discard component instances (default behavior):

<scr:component name="disposable.component" xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.example.DisposableComponent"/>
    <retention-policy>discard</retention-policy>
</scr:component>

Testing

• ✅ All 172 unit tests pass (2 new tests for retention-policy)
• ✅ Build completes successfully
• ✅ Backward compatible - existing Felix delayedKeepInstances extension still works
• ✅ Standard OSGi R8 retention-policy element properly maps to internal implementation

The retention-policy implementation leverages Felix's existing delayedKeepInstances functionality, ensuring seamless integration while maintaining backward compatibility.

• Fixes Implement the new preliminary specification chages in OSGI SCR #6

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement the new preliminary specification chages in OSGI SCR</issue_title>
<issue_description>The Felix SCR implementation needs to be enhanced to support the new proposed specification change here:

• [ds] Add new component retention policy to control service lifecycle osgi/osgi#875

Originally described here

• [ds] support a retention policy for components osgi/osgi#720

in a previous discussion it was stated that apache felix maybe already contains such custom extension, we should check if this is the case and then reuse that as it now becomes specification compliant,</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Implement the new preliminary specification chages in OSGI SCR #6

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[laeubi]

@copilot your finding is correct, but this part is already released and felix just missed to update that, so we should keep the changes you made here.

But we still miss the actual NEW thing added in osgi/osgi#875 that is Components that are expensive to activate/deactivate or maintain caches currently have no control over lifecycle when service use count drops to zero. They either stay permanently active (immediate=true) or get deactivated on every idle period (immediate=false).

So the specification now defines a new element in the component XML "retention-policy" that do not discard components if their use-count goes to zero and instead keep them around forever.

It might help you to look at this specific commit and what it changes more carefully osgi/osgi@9b5c211 then match this up with how felix handles the "immediate" attribute in regard to the service use count.

[Copilot]

@copilot your finding is correct, but this part is already released and felix just missed to update that, so we should keep the changes you made here.

But we still miss the actual NEW thing added i...

I've implemented the retention-policy element from the OSGi R8 specification. The implementation:

• Adds support for the <retention-policy> element with values "retain" and "discard"
• Maps to the existing delayedKeepInstances functionality for backward compatibility
• Includes comprehensive documentation in README.md explaining the problem statement, usage, and use cases
• Adds unit tests for both retention policy values
• All 172 tests pass

The retention-policy element controls whether component instances are retained when their use count drops to zero, solving the problem you described where expensive components or those with caches had no control over lifecycle.

Commit: dbc2e51

[laeubi]

@copilot some changes where already merged in the upstream I merged the changes now but it seems the enhancements to the docs of the last change was lost, can you update the docs for the retention policy change again?

As Satisfying Condition is already merge upstream we do not further need to consider it here and can update PR title + description as well!

[Copilot]

@copilot some changes where already merged in the upstream I merged the changes now but it seems the enhancements to the docs of the last change was lost, can you update the docs for the retention pol...

I've restored the Retention Policy documentation that was lost during the upstream merge. The changes include:

• Updated README.md with the complete Retention Policy section (problem statement, usage examples, use cases, and compatibility notes)
• Updated changelog.txt with the Retention Policy implementation entry
• Updated references to use the official OSGi 8.0.0 specification links
• Updated intro text to mention both Satisfying Condition and Retention Policy features

I've also updated the PR title and description to focus on Retention Policy only, since Satisfying Condition was already merged upstream.

Commit: 650bce3